From 6fc10ed70f65ef97be938d6cac624099e0d2a934 Mon Sep 17 00:00:00 2001
From: Brett Holman <brett.holman@canonical.com>
Date: Wed, 6 Dec 2023 11:54:26 -0700
Subject: [PATCH] doc: Document boot status meaning (#4670)

---
 doc/rtd/howto/status.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/doc/rtd/howto/status.rst b/doc/rtd/howto/status.rst
index 01079f542ca9..350dc5816f43 100644
--- a/doc/rtd/howto/status.rst
+++ b/doc/rtd/howto/status.rst
@@ -58,5 +58,29 @@ See the list of all possible reported statuses:
     "degraded running"
     "disabled"
 
+Cloud-init enablement status
+----------------------------
+
+Separately from the current running status described above, cloud-init can also
+report how it was disabled or enabled. This can be viewed by checking
+the `boot_status_code` in ``cloud-init status --long``, which may
+contain any of the following states:
+
+- ``'unknown'``: ``ds-identify`` has not run yet to determine if cloud-init
+  should be run during this boot
+- ``'disabled-by-marker-file'``: :file:`/etc/cloud/cloud-init.disabled` exists
+  which prevents cloud-init from ever running
+- ``'disabled-by-generator'``: ``ds-identify`` determined no applicable
+  cloud-init datasources
+- ``'disabled-by-kernel-cmdline'``: kernel cmdline contained
+  cloud-init=disabled
+- ``'disabled-by-environment-variable'``: environment variable
+  ``KERNEL_CMDLINE`` contained ``cloud-init=disabled``
+- ``'enabled-by-kernel-cmdline'``: kernel cmdline contained
+  cloud-init=enabled
+- ``'enabled-by-generator'``: ``ds-identify`` detected possible cloud-init
+  datasources
+- ``'enabled-by-sysvinit'``: enabled by default in SysV init environment
+
 See :ref:`our explanation of failure states<failure_states>` for more
 information.