Status values

When you deploy an application with Juju, juju status will display the application status and the unit status, where the latter is represented by the status of its workload/charm and the status of its juju agent (all marked in green in the picture below). This document clarifies all these statuses—their possible values as well as their meanings.


Application status

As its name indicates, the application status reports on the status of each deployed application.

This status is the least common denominator of the workload statuses (see below) of all of the application’s units. So if all workloads are active, the application will also be active, but if even just one workload is blocked, the application will also be marked blocked.

The following figure provides an illustration of the status an application may be in at a given time, and lists the reasons for the transitions between different statuses:

Unit status

The unit status is given by the status of its workload/charm and the status of its juju agent.

A unit’s status is usually expressed as <workload status>/<agent status>, e.g. , active/idle or unknown/lost.

Workload / charm status

The workload / charm status reports the status of the charm(ed service):

Status Meaning
maintenance The charm is performing some (long-running) task such as installing a package or restarting a service. Or, the charm is still being setup (installed) and has had no chance to set its own status yet.
waiting The charm is alive and well, and is waiting for some event to occur. No human intervention required.
blocked The charm is stuck. Human attention/intervention is required.
active The charm is alive and well. Everything’s fine.
unknown The charm status is unknown. It may be still setting up, or something might have gone wrong.
terminated The workload container is being destroyed, e.g. as a consequence of juju destroy-model.

The workload status is generally speaking set by the charm (via e.g. self.unit.status = WaitingStatus('message')). As such, its semantics is ultimately up to the user. However, the meanings we listed in the table above serve as guidelines (‘best practices’) for when a given status should be set.

Exceptions to this rule are terminated and unknown workload statuses: these are set by the juju agent and are not controlled by charm code.

Agent status

The agent status reports the status of the juju agent running in the unit as it interacts with the juju controller:

Status Meaning
allocating The charm pod has not come up yet.
idle The juju agent in the charm container is not doing anything at the moment, and waiting for events.
executing The juju agent in the charm container is executing some task.
error The juju agent in the charm container has run but has encountered an uncaught charm exception.
lost The juju agent is unresponsive, or its pod/container has unexpectedly come down.

The agent status is determined and set by the juju agent, so it cannot be directly controlled by the charm or a human operator.

Each newly deployed unit starts in maintenance/allocating, quickly going to maintenance/executing as the setup phase hooks are executed. If, by the time the install hook (if any) returns, the charm has set no workload status, the unit will go to unknown/idle. So, in principle, at the end of the install event handler it should be clear if all went well (in which case the user should set active) or not.

A charm that does not implement update-status, including a reactive charm using the “default” update-status hook, will stay in the unknown state. This is a question I have fielded multiple times from users and it would be great to update the unknown documentation to indicate that this can be normal for some charms.

1 Like

There is one similarity between the blocked status and waiting status that i think we should make explicit as this would help a charm writer develop a clear mental model on how his/her charm should behave after setting one of these two statuses. In both these cases the charm should continue to monitor the condition that lead to blocked/waiting status and reset the status to active if the condition no longer persists. Emphasizing this may be important because it is easy to develop the misunderstanding that the charm need not do anything further once it has set blocked status since the system administrator has now been informed, particularly so since there is no equivalent of juju resolve for blocked status.

It might be worthwhile noting here that if the charm didn’t set a status, then Juju would mark it as Unknown.

In the past I recall it was advised to avoid including a message in ActiveStatus. If this is still the case then the example should probably reflect that.

I think UnknownStatus can be set by the user:

While not forbidden at the ops level, juju, on the other hand, will complain.

1 Like