Add project documentation to be displayed in RTD

docs/.custom_wordlist.txt

@@ -3,4 +3,21 @@ Upgrader
 ussuri
 Github
 frictionless
-COU
+COU
+SIGINT
+SIGINTs
+SIGTERM
+SIGTERMs
+STDOUT
+cou
+COUModel
+juju
+libjuju
+VPN
+ctrl
+snapcraft
+OpenStackApplication
+yaml
+backoff
+BACKOFF
+websockets

docs/explanation/analysis.rst

@@ -0,0 +1,17 @@
+========
+Analysis
+========
+
+This phase is responsible for obtaining all the required OpenStack cloud information
+from Juju: the model status and the configuration for each application is obtained
+and stored in an Analysis object, divided into control and data plane. Each
+application is represented by a generic **OpenStackApplication** class or by a custom
+subclass, e.g. **Keystone(OpenStackApplication)**.
+
+Required Juju commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code:: 
+
+    $ juju status
+    $ juju config <app-name>

docs/explanation/index.rst

@@ -1,3 +1,14 @@
 ===========
 Explanation
-===========
+===========
+
+This section provides additional information about the upgrade stages, implementation,
+and known issues.
+
+.. toctree::
+   :maxdepth: 1
+
+   analysis
+   planning
+   upgrade
+   known-issues

docs/explanation/known-issues.rst

@@ -0,0 +1,11 @@
+============
+Known issues
+============
+
+There are known upgrade bugs of the OpenStack that may help you troubleshoot an
+unsuccessful upgrade run: 
+
+- `Issues, charm procedures, and OpenStack upgrade notes`_
+
+.. LINKS:
+.. _Issues, charm procedures, and OpenStack upgrade notes: https://docs.openstack.org/charm-guide/latest/project/issues-and-procedures.html

docs/explanation/planning.rst

@@ -0,0 +1,42 @@
+========
+Planning
+========
+
+The plan has a tree structure with three main sections: pre-upgrade steps,
+control-plane upgrade and data-plane upgrade.
+
+.. code:: 
+
+    Top-level plan
+    ├── pre-upgrade steps
+    │   ├── verify cloud is in idle state
+    │   └── MySQL backup
+    ├── control-plane upgrade
+    │   ├── principal applications
+    │   |   ├── application 1..
+    │   |   |   ├── pre-upgrade steps
+    |   |   |   ├── upgrade steps
+    │   |   |   └── post-upgrade steps
+    │   |   └── application N
+    │   |       ├── pre-upgrade steps
+    |   |       ├── upgrade steps
+    │   |       └── post-upgrade steps
+    |   └── subordinate applications...
+    ├── data-plane upgrade
+    ...
+
+The **pre-upgrades** steps are used to obtain any further information about application 
+or to verify its state. 
+
+The **upgrade** steps are the main steps needed to run upgrades for each application.
+
+The **post-upgrade** steps are responsible for making sure that upgrade finishes
+successfully. 
+
+The update plan can also be obtained without the need to upgrade the cloud using
+the plan command. See :doc:`Plan the upgrade <../how-to/plan-upgrade>`.
+
+Required Juju commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+No Juju commands are used.

docs/explanation/upgrade.rst

@@ -0,0 +1,12 @@
+=======
+Upgrade
+=======
+
+This phase is responsible for applying the upgrade plan step by step. By default
+steps are applied sequentially, but there are steps which can be run in parallel.
+
+Required Juju commands
+~~~~~~~~~~~~~~~~~~~~~~
+
+Any upgrade step may require different Juju commands, from changing configuration
+to running commands directly on a unit.

docs/get-started/index.rst

@@ -1,3 +1,27 @@
 ===========
 Get started
-===========
+===========
+
+Verify Access
+-------------
+To use COU you need to have access to a `Charmed OpenStack`_ cloud, which is deployed
+using `Juju`_. COU uses Juju credentials to access the OpenStack cloud, so accessing
+the cloud with Juju is mandatory. Cloud access verification can be done by simply
+calling the juju status command.
+
+.. code:: bash
+    
+    juju status --model <name-of-your-openstack-model>
+
+Installation
+------------
+Install the COU snap from the `snap store`_:
+
+.. code:: bash
+    
+    sudo snap install charmed-openstack-upgrader
+
+.. LINKS
+.. _Charmed OpenStack: https://ubuntu.com/openstack/docs
+.. _Juju: https://juju.is/docs/juju
+.. _snap store: https://snapcraft.io/

docs/how-to/configure-connection.rst

@@ -0,0 +1,20 @@
+=================================
+Change model connection behaviour
+=================================
+
+There are three variables through which the connection behaviour to the Juju model
+can be tuned. This may be necessary if COU is run from behind a VPN or if the network
+is heavily used.
+
+* **COU_TIMEOUT** - set the timeout of retries for any calls by COUModel to libjuju. It's unit-less and the number represents the number of seconds. Defaults to 10 seconds.
+
+* **COU_MODEL_RETRIES** - set how many times to retry connecting to the Juju model before giving up. Defaults to 5.
+
+* **COU_MODEL_RETRY_BACKOFF** - sets the number of seconds in between connection retry attempts (for example, a backoff of 10 with 3 retries would wait 10s, 20s, and 30s). It’s unit-less and the number represents the number of seconds. Defaults to 2 seconds.
+
+Usage example
+~~~~~~~~~~~~~
+
+.. code::
+
+    $  COU_TIMEOUT=120 cou upgrade

docs/how-to/different-model.rst

@@ -0,0 +1,33 @@
+======================================
+Target a different model or controller
+======================================
+
+The current active model will be used by default, but it's possible to select a
+different one, even on a different controller. There are two ways to choose the
+model you want to operate on.
+
+Using CLI argument
+~~~~~~~~~~~~~~~~~~
+
+.. code::
+
+    $ cou plan --model <model-name>
+    $ cou plan --model <controller>:<model-name>
+
+Using environment variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since COU is using `python-libjuju`_, it's possible for some of the environment variables
+mentioned in the documented `Juju environment variables`_ to affect the behaviour of the
+program. For example, `JUJU_DATA`_ can be used to specify a different path for Juju
+configuration files.
+
+.. code::
+    
+    $ JUJU_MODEL=openstack cou plan
+    $ JUJU_DATA=./my-remote-cloud-juju-data cou plan
+
+.. LINKS
+.. _python-libjuju: https://github.com/juju/python-libjuju
+.. _Juju environment variables: https://juju.is/docs/juju/environment-variables#heading--jujudata
+.. _JUJU_DATA: https://juju.is/docs/juju/environment-variables#heading--jujudata

docs/how-to/index.rst

@@ -4,3 +4,16 @@ How-to guides
 
 These How-to guides will cover a variety of operations that
 are possible with COU.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   plan-upgrade
+   upgrade-cloud
+   different-model
+   interruption
+   configure-connection
+   non-interactive
+   no-backup
+   verbosity

docs/how-to/interruption.rst

@@ -0,0 +1,94 @@
+===============================
+Interrupt and resume an upgrade
+===============================
+
+Since a partially executed upgrade step can leave the cloud in an inconsistent state,
+COU ensures upgrades can be interrupted only in between steps. By doing so, upgrades
+can be safely stopped and resumed later on.
+
+Abort
+-----
+
+In interactive mode, the user must approve each step, and has a chance to interrupt
+the process at any prompt.
+
+Usage example:
+
+.. code:: 
+
+    $ cou upgrade
+    Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
+    Connected to 'test-model' ✔
+    Analyzing cloud... ✔
+    Generating upgrade plan... ✔
+    Upgrade cloud from 'ussuri' to 'victoria'
+    ...
+    Running cloud upgrade...
+    Verify that all OpenStack applications are in idle state ✔
+    Backup mysql databases ✔
+    Upgrade plan for 'keystone' to victoria
+        Upgrade software packages of 'keystone' from the current APT repositories
+        Upgrade 'keystone' to the new channel: 'victoria/stable'
+        Change charm config of 'keystone' 'openstack-origin' to 'cloud:focal-victoria'
+        Wait 1800s for model test-model to reach the idle state.
+        Check if the workload of 'keystone' has been upgraded
+
+    Would you like to start the upgrade? Continue (y/N): n
+    $
+
+SIGINT or SIGTERM signals
+-------------------------
+
+COU will exit upon receiving SIGINT or SIGTERM signals, but if the upgrade is already
+in progress one of two behaviours will occur. If SIGINT or SIGTERM is sent only once
+(e.g. by pressing *ctrl+c* once), currently running steps will be allowed to finish,
+but any further upgrade step will be cancelled. If cou receives two or more SIGINTs
+(e.g. by pressing *ctrl+c* multiple times) or SIGTERMs, the upgrade will be cancelled
+abruptly in a potentially unsafe way: currently running steps will be immediately
+stopped, and no further step will be executed. This is generally not recommended as
+the cloud may be left in an inconsistent state.
+
+Exiting before running upgrade plan:
+
+.. code:: 
+
+    $ cou upgrade - # ctrl+c is pressed while connecting to the controller
+    Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
+    Connecting to 'default' model... ✖
+    charmed-openstack-upgrader has been terminated
+    $ cou upgrade # ctrl+c is pressed while the cloud is being analyzed
+    Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
+    Connecting to 'default' model... ✔
+    Analyzing cloud... ✖
+    charmed-openstack-upgrader has been terminated
+    $ 
+
+Safe cancel:
+
+.. code::
+
+    $ cou upgrade # ctrl+c is pressed once during the upgrade
+    Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
+    Connected to 'test-model' ✔
+    Analyzing cloud... ✔
+    Generating upgrade plan... ✔
+    ...
+    Running cloud upgrade...
+    Canceling upgrade... (Press ctrl+c again to stop immediately) ✔
+    charmed-openstack-upgrader has been stopped safely 
+    $ 
+
+Unsafe cancel:
+
+.. code::
+
+    $ cou upgrade # ctrl+c is pressed twice during the upgrade
+    Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
+    Connected to 'test-model' ✔
+    Analyzing cloud... ✔
+    Generating upgrade plan... ✔
+    ...
+    Running cloud upgrade...
+    Canceling upgrade... (Press ctrl+c again to stop immediately) ✖
+    charmed-openstack-upgrader has been terminated without waiting
+    $ 

docs/how-to/no-backup.rst

@@ -0,0 +1,24 @@
+==========================================
+Run upgrades without cloud database backup
+==========================================
+
+By default, COU makes a backup of the cloud database before proceeding to actual
+upgrade steps. This can be turned off with `--no-backup`  flag.
+
+Usage example
+~~~~~~~~~~~~~
+
+.. code:: 
+
+    $ cou plan --no-backup
+    Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
+    Connected to 'test-model' ✔
+    Analyzing cloud... ✔
+    Generating upgrade plan... ✔
+    Upgrade cloud from 'ussuri' to 'victoria'
+        Verify that all OpenStack applications are in idle state
+        # note that there's no backup step planned
+        Control Plane principal(s) upgrade plan
+        Upgrade plan for 'rabbitmq-server' to victoria
+            Upgrade software packages of 'rabbitmq-server' from the current APT repositories
+        …

docs/how-to/non-interactive.rst

@@ -0,0 +1,36 @@
+============================
+Run non-interactive upgrades
+============================
+
+COU provides a non-interactive mode which suppresses user prompts. This option
+allows cou to be used by scripts or during upgrade testing. A quiet mode switch
+is also offered, which will only output error logs and a completion message to STDOUT.
+
+Usage examples
+~~~~~~~~~~~~~~
+
+Non-interactive mode:
+
+.. code:: 
+
+    $ cou upgrade --no-interactive
+    Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
+    Connected to 'test-model' ✔
+    Analyzing cloud... ✔
+    Generating upgrade plan... ✔
+    ...
+    Running cloud upgrade...
+    Verify that all OpenStack applications are in idle state ✔
+    Backup mysql databases ✔
+    Upgrade software packages of 'keystone' from the current APT repositories ✔
+    Upgrade 'keystone' to the new channel: 'victoria/stable' ✔
+    ...
+    Upgrade completed.
+
+
+Non-interactive and quiet mode:
+
+.. code:: 
+
+    $ cou upgrade --no-interactive --quiet
+    Upgrade completed.