diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index e72fe97a..d321a9b9 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1,2 +1,23 @@ OpenStack -Upgrader \ No newline at end of file +Upgrader +ussuri +Github +frictionless +COU +cou +COUModel +SIGINT +SIGINTs +SIGTERM +SIGTERMs +STDOUT +juju +libjuju +VPN +ctrl +snapcraft +OpenStackApplication +yaml +backoff +BACKOFF +websockets \ No newline at end of file diff --git a/docs/explanation/analysis.rst b/docs/explanation/analysis.rst new file mode 100644 index 00000000..04300b90 --- /dev/null +++ b/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)**. diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst new file mode 100644 index 00000000..44718c7f --- /dev/null +++ b/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 diff --git a/docs/explanation/planning.rst b/docs/explanation/planning.rst new file mode 100644 index 00000000..688eebf5 --- /dev/null +++ b/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>`. diff --git a/docs/explanation/upgrade.rst b/docs/explanation/upgrade.rst new file mode 100644 index 00000000..42b53978 --- /dev/null +++ b/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. diff --git a/docs/get-started/index.rst b/docs/get-started/index.rst new file mode 100644 index 00000000..42fbed62 --- /dev/null +++ b/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/ \ No newline at end of file diff --git a/docs/how-to/configure-connection.rst b/docs/how-to/configure-connection.rst new file mode 100644 index 00000000..db8e7aad --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/how-to/different-model.rst b/docs/how-to/different-model.rst new file mode 100644 index 00000000..6321a729 --- /dev/null +++ b/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 + $ cou plan --model : + +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 diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst new file mode 100644 index 00000000..16cbe19d --- /dev/null +++ b/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 diff --git a/docs/how-to/interruption.rst b/docs/how-to/interruption.rst new file mode 100644 index 00000000..d453f70b --- /dev/null +++ b/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 + $ \ No newline at end of file diff --git a/docs/how-to/no-backup.rst b/docs/how-to/no-backup.rst new file mode 100644 index 00000000..64a806fe --- /dev/null +++ b/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. diff --git a/docs/how-to/plan-upgrade.rst b/docs/how-to/plan-upgrade.rst new file mode 100644 index 00000000..4e541f23 --- /dev/null +++ b/docs/how-to/plan-upgrade.rst @@ -0,0 +1,81 @@ +================ +Plan an upgrade +================ + +The **plan** command is used to generate the upgrade plan; the result will be +printed on STDOUT. + +.. code:: + + $ cou plan + +Usage example +~~~~~~~~~~~~~ + +.. code:: + + $ cou plan + 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 + Backup mysql databases + 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 '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 + 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 + Upgrade plan for 'cinder' to victoria + Upgrade software packages of 'cinder' from the current APT repositories + Upgrade 'cinder' to the new channel: 'victoria/stable' + Change charm config of 'cinder' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app cinder to reach the idle state. + Check if the workload of 'cinder' has been upgraded + Upgrade plan for 'glance' to victoria + Upgrade software packages of 'glance' from the current APT repositories + Upgrade 'glance' to the new channel: 'victoria/stable' + Change charm config of 'glance' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app glance to reach the idle state. + Check if the workload of 'glance' has been upgraded + Upgrade plan for 'neutron-api' to victoria + Upgrade software packages of 'neutron-api' from the current APT repositories + Upgrade 'neutron-api' to the new channel: 'victoria/stable' + Change charm config of 'neutron-api' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app neutron-api to reach the idle state. + Check if the workload of 'neutron-api' has been upgraded + Upgrade plan for 'neutron-gateway' to victoria + Upgrade software packages of 'neutron-gateway' from the current APT repositories + Upgrade 'neutron-gateway' to the new channel: 'victoria/stable' + Change charm config of 'neutron-gateway' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app neutron-gateway to reach the idle state. + Check if the workload of 'neutron-gateway' has been upgraded + Upgrade plan for 'placement' to victoria + Upgrade software packages of 'placement' from the current APT repositories + Upgrade 'placement' to the new channel: 'victoria/stable' + Change charm config of 'placement' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app placement to reach the idle state. + Check if the workload of 'placement' has been upgraded + Upgrade plan for 'nova-cloud-controller' to victoria + Upgrade software packages of 'nova-cloud-controller' from the current APT repositories + Upgrade 'nova-cloud-controller' to the new channel: 'victoria/stable' + Change charm config of 'nova-cloud-controller' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app nova-cloud-controller to reach the idle state. + Check if the workload of 'nova-cloud-controller' has been upgraded + Upgrade plan for 'mysql' to victoria + Upgrade software packages of 'mysql' from the current APT repositories + Change charm config of 'mysql' 'source' to 'cloud:focal-victoria' + Wait 1800s for app mysql to reach the idle state. + Check if the workload of 'mysql' has been upgraded + Control Plane subordinate(s) upgrade plan + Upgrade plan for 'neutron-openvswitch' to victoria + Upgrade 'neutron-openvswitch' to the new channel: 'victoria/stable' diff --git a/docs/how-to/upgrade-cloud.rst b/docs/how-to/upgrade-cloud.rst new file mode 100644 index 00000000..733fcfe9 --- /dev/null +++ b/docs/how-to/upgrade-cloud.rst @@ -0,0 +1,151 @@ +=============== +Upgrade a cloud +=============== + +Run interactive upgrades +------------------------ + +Use the **upgrade** command to automatically plan and execute the upgrade of your +cloud. This command runs upgrade in interactive mode by default, requiring the user +to confirm each step. + +.. code:: + + $ cou upgrade + +Usage example +^^^^^^^^^^^^^ + +.. code:: + + $ cou upgrade + Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211917.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 + Backup mysql databases + 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 '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 + 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 + Upgrade plan for 'cinder' to victoria + Upgrade software packages of 'cinder' from the current APT repositories + Refresh 'cinder' to the latest revision of 'ussuri/stable' + Upgrade 'cinder' to the new channel: 'victoria/stable' + Change charm config of 'cinder' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app cinder to reach the idle state. + Check if the workload of 'cinder' has been upgraded + Upgrade plan for 'glance' to victoria + Upgrade software packages of 'glance' from the current APT repositories + Upgrade 'glance' to the new channel: 'victoria/stable' + Change charm config of 'glance' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app glance to reach the idle state. + Check if the workload of 'glance' has been upgraded + Upgrade plan for 'neutron-api' to victoria + Upgrade software packages of 'neutron-api' from the current APT repositories + Upgrade 'neutron-api' to the new channel: 'victoria/stable' + Change charm config of 'neutron-api' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app neutron-api to reach the idle state. + Check if the workload of 'neutron-api' has been upgraded + Upgrade plan for 'neutron-gateway' to victoria + Upgrade software packages of 'neutron-gateway' from the current APT repositories + Upgrade 'neutron-gateway' to the new channel: 'victoria/stable' + Change charm config of 'neutron-gateway' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app neutron-gateway to reach the idle state. + Check if the workload of 'neutron-gateway' has been upgraded + Upgrade plan for 'placement' to victoria + Upgrade software packages of 'placement' from the current APT repositories + Upgrade 'placement' to the new channel: 'victoria/stable' + Change charm config of 'placement' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app placement to reach the idle state. + Check if the workload of 'placement' has been upgraded + Upgrade plan for 'nova-cloud-controller' to victoria + Upgrade software packages of 'nova-cloud-controller' from the current APT repositories + Refresh 'nova-cloud-controller' to the latest revision of 'ussuri/stable' + Upgrade 'nova-cloud-controller' to the new channel: 'victoria/stable' + Change charm config of 'nova-cloud-controller' 'openstack-origin' to 'cloud:focal-victoria' + Wait 300s for app nova-cloud-controller to reach the idle state. + Check if the workload of 'nova-cloud-controller' has been upgraded + Upgrade plan for 'mysql' to victoria + Upgrade software packages of 'mysql' from the current APT repositories + Change charm config of 'mysql' 'source' to 'cloud:focal-victoria' + Wait 1800s for app mysql to reach the idle state. + Check if the workload of 'mysql' has been upgraded + Control Plane subordinate(s) upgrade plan + Upgrade plan for 'neutron-openvswitch' to victoria + Upgrade 'neutron-openvswitch' to the new channel: 'victoria/stable' + Would you like to start the upgrade? Continue (y/N): y + Running cloud upgrade... + Verify that all OpenStack applications are in idle state ✔ + Backup mysql databases ✔ + + 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 ✔ + + 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 + + Continue (y/n): y + Upgrade software packages of 'keystone' from the current APT repositories \ + + ... # apply each step + Upgrade completed. + + +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. \ No newline at end of file diff --git a/docs/how-to/verbosity.rst b/docs/how-to/verbosity.rst new file mode 100644 index 00000000..de0fda37 --- /dev/null +++ b/docs/how-to/verbosity.rst @@ -0,0 +1,36 @@ +====================== +Change verbosity level +====================== + +The verbose parameter can be used to increase the verbosity level. The parameter +can be used multiple times (up to four), increasing verbosity from error to debug +log level. + +The default verbosity level is **error**. + +Usage examples +~~~~~~~~~~~~~~ + +The warning level. + +.. code:: + + $ cou upgrade -v + +The info level. + +.. code:: + + $ cou upgrade -vv + +The debug level for all messages except **python-libjuju** and **websockets**. + +.. code:: + + $ cou upgrade -vvv + +The debug level for all messages including the **python-libjuju** and **websockets**. + +.. code:: + + $ cou upgrade -vvvv \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index ea8c2534..6c6c722a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,22 +1,57 @@ -Starter pack -============ +Charmed OpenStack Upgrader +========================== -This starter pack contains the files you need to quickly set up your Sphinx documentation. +`Charmed OpenStack Upgrader`_ (**COU**) is an application (packaged as a snap) to upgrade +a Canonical distribution of `Charmed OpenStack`_ +in an automated and frictionless manner. The application detects the version of the +running cloud and proposes an upgrade plan to the next available OpenStack release. -Before you start, see the information about `Read the Docs at Canonical`_ and the instructions for `How to publish documentation on Read the Docs`_. +**COU** follows the steps defined in the `charm-guide`_ upgrades overview. -Then, to start setting up your docs, check the :doc:`ReadMe ` for instructions. -The `Example product documentation`_ shows how to set up a Diátaxis structure in Sphinx. +Notes: -For quick help on reST or MyST syntax, see the :file:`doc-cheat-sheet.rst.txt` or :file:`doc-cheat-sheet-myst.md.txt` files in the repository. -(Open the files in your text editor; the rendered output is not very useful.) +- Currently only control plane upgrades are supported. + +- The tool supports upgrades from focal-ussuri to focal-yoga. + +Source code available on `Github`_. + +In this documentation +--------------------- + +.. grid:: 1 1 2 2 + + .. grid-item:: :doc:`Get Started ` + + **Start here** to prepare the environment and install the application + + .. grid-item:: :doc:`How-to guides ` + + **Step-by-step guides** covering key operations and common tasks + +.. grid:: 1 1 2 2 + + .. grid-item:: :doc:`Reference ` + + **Technical information** - commands, environmental variables, and known issues + + .. grid-item:: :doc:`Explanation ` + + **Additional information** - details of upgrade phases defined in **COU** -More information is available in the `reStructuredText style guide`_. .. toctree:: :hidden: :maxdepth: 2 - ReadMe - Inclusive language check exemptions - Setup script + get-started/index + how-to/index + reference/index + explanation/index + +.. LINKS +.. _Charmed OpenStack Upgrader: https://snapcraft.io/charmed-openstack-upgrader +.. _Charmed OpenStack: https://ubuntu.com/openstack/docs +.. _charm-guide: https://docs.openstack.org/charm-guide/latest/admin/upgrades/overview.html +.. _Code of conduct: https://ubuntu.com/community/ethos/code-of-conduct +.. _GitHub: https://github.com/canonical/charmed-openstack-upgrader diff --git a/docs/reference/commands.rst b/docs/reference/commands.rst new file mode 100644 index 00000000..9f7c22cd --- /dev/null +++ b/docs/reference/commands.rst @@ -0,0 +1,55 @@ +======== +Commands +======== + +**COU** offers only two commands; bash completion further simplifies its usage. + +Plan +---- + +The **plan** command will analyse the cloud and output a human-readable representation +of the proposed upgrade plan. It does not require any interaction. Refer to the +output below for a description of all allowed options. + +.. code:: + + $ cou plan --help + Usage: cou plan [options] + + Show the steps COU will take to upgrade the cloud to the next release. + + Options: + -h, --help Show this help message and exit. + --model MODEL_NAME Set the model to operate on. + If not set, the currently active Juju model will be used. + --backup, --no-backup + Include database backup step before cloud upgrade. + Default to enabling database backup. + --verbose, -v Increase logging verbosity in STDOUT. Multiple 'v's yield progressively more detail (up to 4). + Note that by default the logfile will include standard logs from juju and websockets, as well as debug logs from all other modules. To also include the debug level logs from juju and websockets modules, use the maximum verbosity. + --quiet, -q Disable output in STDOUT. + +Upgrade +------- + +The **upgrade** command will implicitly generate a plan before moving onto the actual +upgrade phase. Refer to the output below for a description of all available options. + +.. code:: + $ cou upgrade --help + Usage: cou upgrade [options] + + Run the cloud upgrade. + + Options: + -h, --help Show this help message and exit. + --model MODEL_NAME Set the model to operate on. + If not set, the currently active Juju model will be used. + --backup, --no-backup + Include database backup step before cloud upgrade. + Default to enabling database backup. + --verbose, -v Increase logging verbosity in STDOUT. Multiple 'v's yield progressively more detail (up to 4). + Note that by default the logfile will include standard logs from juju and websockets, as well as debug logs from all other modules. To also include the debug level logs from juju and websockets modules, use the maximum verbosity. + --quiet, -q Disable output in STDOUT. + --auto-approve Automatically approve and continue with each upgrade step without prompt. + diff --git a/docs/reference/environment-variables.rst b/docs/reference/environment-variables.rst new file mode 100644 index 00000000..9dba5d55 --- /dev/null +++ b/docs/reference/environment-variables.rst @@ -0,0 +1,8 @@ +===================== +Environment Variables +===================== + +* **JUJU_DATA** - sets the path containing Juju configuration files (e.g. credentials.yaml). Defaults to ~/.local/share/juju +* **COU_TIMEOUT** - define timeout for **COU** retry policy. Default value is 10 seconds. +* **COU_MODEL_RETRIES** - define how many times to retry the connection to Juju model before giving up. Default value is 5 times. +* **COU_MODEL_RETRY_BACKOFF** - define number of seconds to increase the wait between connection to the Juju model retry attempts. Default value is 2 seconds. diff --git a/docs/reference/index.rst b/docs/reference/index.rst new file mode 100644 index 00000000..785b9782 --- /dev/null +++ b/docs/reference/index.rst @@ -0,0 +1,12 @@ +========= +Reference +========= + +This section explains the list of available commands and environmental variables. + +.. toctree:: + :maxdepth: 1 + + commands + environment-variables + known-issues diff --git a/docs/reference/known-issues.rst b/docs/reference/known-issues.rst new file mode 100644 index 00000000..8645f20d --- /dev/null +++ b/docs/reference/known-issues.rst @@ -0,0 +1,10 @@ +============ +Known issues +============ + +Potential known upgrade bugs and non-standard procedures are listed in the OpenStack Charm Guide: + +- `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 \ No newline at end of file