Status

See also: SDK | Status

In Juju, status can describe the status of an application or a unit, where the former can be inferred from the latter and the latter consists of the workload and the Juju agent status. This document gives more information about all of these different kinds of status – their values and their meanings.

Contents:

Types of status

Application status

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

The application status can be specified by the charm author. When not specified, it is the highest-priority status of the workload statuses 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.

See more: Workload / charm status

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):

Except for error, terminated and unknown, which are set by Juju, the workload status is generally speaking set by the charm. As such, its semantics is ultimately up to the charm author. The meanings listed below represent just the ideal case, if the charm author has followed the best practice guidelines.

Status Meaning
error The unit is in error, likely from a hook failure.
blocked The charm is stuck. Human intervention is required.
maintenance The charm is performing some (long-running) task such as installing a package or restarting a service. No human intervention is required.
waiting The charm is waiting for another charm it’s integrated with to be ready. No human intervention 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 is being destroyed, e.g. as a consequence of juju destroy-model.

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.

Status in the output of juju status

In the output of juju status, application status is given under App[lication] > Status and unit status – consisting, as we said, of the workload / charm status and of the Juju agent status – is given under Unit > Workload, Agent.


Expand to view a sample `juju status` output
Model        Controller           Cloud/Region        Version  SLA          Timestamp
charm-model  tutorial-controller  microk8s/localhost  3.1.5    unsupported  14:23:55+02:00

App             Version  Status  Scale  Charm           Channel    Rev  Address         Exposed  Message
demo-api-charm  1.0.0    active      1  demo-api-charm               0  10.152.183.175  no       
postgresql-k8s  14.7     active      1  postgresql-k8s  14/stable   73  10.152.183.237  no       Primary

Unit               Workload  Agent  Address      Ports  Message
demo-api-charm/0*  active    idle   10.1.157.72         
postgresql-k8s/0*  active    idle   10.1.157.74         Primary

See more: Command juju status

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. https://github.com/canonical/operator/pull/727


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: https://github.com/canonical/operator/blob/448c8b17efe05d1d700599496cc6a19e318f5127/ops/model.py#L895

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

1 Like

The following doc regarding Workload / charm status has varying information and is redundant when compared to the docs/sdk/status docs.

While docs/juju/status provides more information, the docs/sdk/status is more helpful (even linking to the corresponding ops library status).

Possible statuses

The possible status values are listed below, along with a link to their ops.StatusBase subclass for use in ops. They are listed in order from highest to lowest priority, where in case of multiple statuses the higher priority status is what gets surfaced to the user:

  • error: the unit is in error, likely from a hook failure (this status is set by Juju, not by the charm)
  • blocked: the unit requires manual intervention from the Juju user, as specified by the charm author (see status notes or the charm’s docs)
  • maintenance: the unit is performing maintenance tasks to get up and running
  • waiting: the unit is waiting on an application it’s integrated with
  • active: the unit is ready and offering the services it has been designed to offer
  • unknown: the initial, unknown status when the unit has not set its status yet

Specifically,

the unknown status can be achieved when the unit has not set its status yet

Is not mentioned in docs/juju/status # Workload / charm status and is more helpful than

The charm status is unknown. It may be still setting up, or something might have gone wrong.

Consider consolidating the two to make use of 1 point of reference.

Mention @tmihoc