From 8ceae8b7b504960e348ecda36c26db0b6fa12890 Mon Sep 17 00:00:00 2001
From: Alberto Contreras <alberto.contreras@canonical.com>
Date: Wed, 24 Jul 2024 22:23:30 +0200
Subject: [PATCH] doc: add diagram with boot stages (#5539)

SC-1835
Fixes GH-5334
---
 doc-requirements.txt         |  1 +
 doc/rtd/conf.py              |  1 +
 doc/rtd/explanation/boot.rst | 46 ++++++++++++++++++++++++++++++------
 3 files changed, 41 insertions(+), 7 deletions(-)

diff --git a/doc-requirements.txt b/doc-requirements.txt
index beb14dd9009..2bb66b5d2dc 100644
--- a/doc-requirements.txt
+++ b/doc-requirements.txt
@@ -9,4 +9,5 @@ sphinx-design
 sphinx-copybutton
 sphinx-notfound-page
 sphinxcontrib.datatemplates
+sphinxcontrib-mermaid
 sphinxcontrib-spelling
diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py
index 1ca6a85a208..55744abb992 100644
--- a/doc/rtd/conf.py
+++ b/doc/rtd/conf.py
@@ -44,6 +44,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.viewcode",
     "sphinxcontrib.datatemplates",
+    "sphinxcontrib.mermaid",
     "sphinxcontrib.spelling",
 ]
 
diff --git a/doc/rtd/explanation/boot.rst b/doc/rtd/explanation/boot.rst
index 6aff2856b66..b1421a209a5 100644
--- a/doc/rtd/explanation/boot.rst
+++ b/doc/rtd/explanation/boot.rst
@@ -3,13 +3,42 @@
 Boot stages
 ***********
 
-There are five stages to boot:
+There are five stages to boot which are run seqentially: ``Detect``, ``Local``,
+``Network``, ``Config`` and ``Final``
 
-1. Detect
-2. Local
-3. Network
-4. Config
-5. Final
+Visual representation of cloud-init boot stages with respect to network config
+and system accessibility:
+
+.. mermaid::
+
+  graph TB
+
+    D["<a href='#detect'>Detect</a>"] ---> L
+
+    L --> NU([Network up])
+    L & NU --> N
+    subgraph L["<a href='#local'>Local</a>"]
+        FI[Fetch IMDS]
+    end
+
+    N --> NO([Network online])
+    N & NO --> C
+    N --> S([SSH])
+    N --> Login([Login])
+
+    subgraph N["<a href='#network'>Network</a>"]
+        cloud_init_modules
+    end
+    %% cloud_config_modules
+
+    subgraph C["<a href='#config'>Config</a>"]
+        cloud_config_modules
+    end
+
+    C --> F
+    subgraph F["<a href='#final'>Final</a>"]
+        cloud_final_modules
+    end
 
 .. _boot-Detect:
 
@@ -83,7 +112,7 @@ Network
 +---------+--------+----------------------------------------------------------+
 | runs             | after local stage and configured networking is up        |
 +---------+--------+----------------------------------------------------------+
-| blocks           | as much of remaining boot as possible                    |
+| blocks           | majority of remaining boot (e.g. SSH and console login)  |
 +---------+--------+----------------------------------------------------------+
 | modules          | *cloud_init_modules* in ``/etc/cloud/cloud.cfg``         |
 +---------+--------+----------------------------------------------------------+
@@ -111,6 +140,9 @@ necessary for cloud-init to run should not be done until after this stage.
 A part-handler and :ref:`boothooks<explanation/format:\`\`cloud-boothook\`\`>`
 will run at this stage.
 
+After this stage completes, expect to be able to access the system via serial
+console login or SSH.
+
 .. _boot-Config:
 
 Config