Add project documentation contents to be displayed on RTD (#210)

This PR adds contents of the project documentation to `docs/` to be
displayed on
[RTD](https://canonical-charmed-openstack-upgrader.readthedocs-hosted.com/en/latest/)
site.

docs/.custom_wordlist.txt

@@ -1,2 +1,23 @@
 OpenStack
-Upgrader
+Upgrader
+ussuri
+Github
+frictionless
+COU
+cou
+COUModel
+SIGINT
+SIGINTs
+SIGTERM
+SIGTERMs
+STDOUT
+juju
+libjuju
+VPN
+ctrl
+snapcraft
+OpenStackApplication
+yaml
+backoff
+BACKOFF
+websockets

docs/explanation/analysis.rst

@@ -0,0 +1,9 @@
+========
+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)**.

docs/explanation/index.rst

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

docs/explanation/planning.rst

@@ -0,0 +1,37 @@
+========
+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 the
+applications or to verify their 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 plan can also be obtained without the need to perform cloud upgrade using
+the **plan** command. See :doc:`Plan an upgrade <../how-to/plan-upgrade>`.

docs/explanation/upgrade.rst

@@ -0,0 +1,8 @@
+=======
+Upgrade
+=======
+
+This phase is responsible for applying the upgrade plan step by step (see
+:doc:`Upgrade a cloud <../how-to/upgrade-cloud>`). Most steps will be applied
+sequentially, but for some that are defined to be run in parallel, they will be
+executed in such a way.

docs/get-started/index.rst

@@ -0,0 +1,32 @@
+===========
+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.
+
+**COU** requires at minimum *write* permission to the target model (see
+`User access levels`_ for more information). To verify your current
+user's model-scoped access level, run the following Juju command and look for
+your OpenStack model.
+
+.. code:: bash
+    
+    juju models
+
+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
+.. _User access levels: https://juju.is/docs/juju/user-permissions
+.. _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_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

@@ -0,0 +1,18 @@
+=============
+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
+   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,53 @@
+==========================================
+Plan/Upgrade without cloud database backup
+==========================================
+
+By default, **COU** plans for and runs a backup step of the cloud database before
+proceeding to actual upgrade steps. This can be turned off with `--no-backup`  flag.
+
+Usage examples
+~~~~~~~~~~~~~~
+
+Plan:
+
+.. 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
+        ...
+
+Upgrade:
+
+.. code:: 
+
+    $ cou upgrade --no-backup
+    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 ✔
+    # note that there's no backup step being executed
+
+    Upgrade plan for 'rabbitmq-server' to victoria
+        Upgrade software packages of 'rabbitmq-server' from the current APT repositories
+        Upgrade 'rabbitmq-server' to the new channel: '3.9/stable'
+        Change charm config of 'rabbitmq-server' 'source' to 'cloud:focal-victoria'
+        Wait 1800s for model test-model to reach the idle state.
+        Check if the workload of 'rabbitmq-server' has been upgraded
+
+    Continue (y/n): y
+    Upgrade plan for 'rabbitmq-server' to victoria ✔
+    
+    ... # apply steps
+    Upgrade completed.