From 2e63a4a76351e7dc9f94d9ea7b382c3b485fdfe0 Mon Sep 17 00:00:00 2001 From: Ben Hoyt Date: Wed, 13 Mar 2024 10:53:23 +1300 Subject: [PATCH 1/2] doc(model): clarify distinction between maintenance and waiting status --- ops/model.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/ops/model.py b/ops/model.py index c2a42b291..2b539a45f 100644 --- a/ops/model.py +++ b/ops/model.py @@ -1854,9 +1854,9 @@ class MaintenanceStatus(StatusBase): """The unit is performing maintenance tasks. The unit is not yet providing services, but is actively doing work in preparation - for providing those services. This is a "spinning" state, not an error state. It - reflects activity on the unit itself, not on peers or related units. - + for providing those services. This is a "spinning" state, not an error state. In + contrast to :class:`WaitingStatus`, "maintenance" reflects activity on this unit + or charm, not on peers or related units. """ name = 'maintenance' @@ -1865,9 +1865,10 @@ class MaintenanceStatus(StatusBase): class WaitingStatus(StatusBase): """A unit is unable to progress. - The unit is unable to progress to an active state because an application with which - it is integrated is not running. - + The unit is unable to progress to an active state because an application it + is integrated with is not yet ready. In contrast to + :class:`MaintenanceStatus`, "waiting" reflects activity on related units, + not on this unit or charm. """ name = 'waiting' From 1c33246c377edeba1a446c30aa1526641f509c18 Mon Sep 17 00:00:00 2001 From: Ben Hoyt Date: Wed, 17 Jul 2024 15:19:22 +1200 Subject: [PATCH 2/2] Updates per discussion in Madrid --- ops/model.py | 34 ++++++++++++++++++++-------------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/ops/model.py b/ops/model.py index 2b539a45f..d752a36a5 100644 --- a/ops/model.py +++ b/ops/model.py @@ -1830,9 +1830,12 @@ class ErrorStatus(StatusBase): @StatusBase.register class ActiveStatus(StatusBase): - """The unit is ready. + """The unit or application is ready and active. - The unit believes it is correctly offering all the services it has been asked to offer. + Set this status when the charm is correctly offering all the services it + has been asked to offer. If the unit or application is operational but + some feature (like high availability) is in a degraded state, set "active" + with an appropriate message. """ name = 'active' @@ -1842,33 +1845,36 @@ def __init__(self, message: str = ''): @StatusBase.register class BlockedStatus(StatusBase): - """The unit requires manual intervention. + """The unit or application requires manual intervention. - An admin has to manually intervene to unblock the unit and let it proceed. + Set this status when an administrator has to manually intervene to unblock + the charm to let it proceed. """ name = 'blocked' @StatusBase.register class MaintenanceStatus(StatusBase): - """The unit is performing maintenance tasks. + """The unit or application is performing maintenance tasks. - The unit is not yet providing services, but is actively doing work in preparation - for providing those services. This is a "spinning" state, not an error state. In - contrast to :class:`WaitingStatus`, "maintenance" reflects activity on this unit - or charm, not on peers or related units. + Set this status when the charm is performing an operation such as + ``apt install``, or is waiting for something under its control, such as + ``pebble-ready`` or an exec operation in the workload container. In + contrast to :class:`WaitingStatus`, "maintenance" reflects activity on + this unit or charm, not on peers or related units. """ name = 'maintenance' @StatusBase.register class WaitingStatus(StatusBase): - """A unit is unable to progress. + """The unit or application is waiting on a charm it's integrated with. - The unit is unable to progress to an active state because an application it - is integrated with is not yet ready. In contrast to - :class:`MaintenanceStatus`, "waiting" reflects activity on related units, - not on this unit or charm. + Set this status when waiting on a charm this is integrated with. For + example, a web app charm would set "waiting" status when it is integrated + with a database charm that is not ready yet (it might be creating a + database). In contrast to :class:`MaintenanceStatus`, "waiting" reflects + activity on related units, not on this unit or charm. """ name = 'waiting'