Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation #216

Merged
merged 2 commits into from
Jan 12, 2024
Merged

Update documentation #216

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51a1944
Update documentation
agileshaw Jan 12, 2024
3847c1d
Change to align with the new CLI option
agileshaw Jan 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/get-started/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
Get started
===========

This section guides you through steps to prepare the environment and install the application.

Verify Access
-------------
To use **COU** you need to have access to a `Charmed OpenStack`_ cloud, which is deployed
Expand Down
2 changes: 2 additions & 0 deletions docs/help-woke.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
:orphan:

===================================
Inclusive language check exemptions
===================================
Expand Down
6 changes: 3 additions & 3 deletions docs/how-to/configure-connection.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,8 @@ is heavily used.
* **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::
.. code:: bash

$ COU_TIMEOUT=120 cou upgrade
COU_TIMEOUT=120 cou upgrade
14 changes: 7 additions & 7 deletions docs/how-to/different-model.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,24 +7,24 @@ different one, even on a different controller. There are two ways to choose the
model you want to operate on.

Using CLI argument
~~~~~~~~~~~~~~~~~~
------------------

.. code::
.. code:: bash

$ cou plan --model <model-name>
$ cou plan --model <controller>:<model-name>
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::
.. code:: bash

$ JUJU_DATA=./my-remote-cloud-juju-data cou plan
JUJU_DATA=./my-remote-cloud-juju-data cou plan


.. LINKS
Expand Down
22 changes: 9 additions & 13 deletions docs/how-to/interruption.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,9 @@ the process at any prompt.

Usage example:

.. code::
.. terminal::
:input: cou upgrade

$ cou upgrade
Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
Connected to 'test-model' ✔
Analyzing cloud... ✔
Expand All @@ -34,7 +34,6 @@ Usage example:
Check if the workload of 'keystone' has been upgraded

Would you like to start the upgrade? Continue (y/N): n
$

SIGINT or SIGTERM signals
-------------------------
Expand All @@ -50,24 +49,23 @@ the cloud may be left in an inconsistent state.

Exiting before running upgrade plan:

.. code::
.. terminal::
:input: cou upgrade - # ctrl+c is pressed while connecting to the controller

$ 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
:input: 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::
.. terminal::
:input: cou upgrade # ctrl+c is pressed once during the upgrade

$ 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... ✔
Expand All @@ -76,13 +74,12 @@ Safe cancel:
Running cloud upgrade...
Canceling upgrade... (Press ctrl+c again to stop immediately) ✔
charmed-openstack-upgrader has been stopped safely
$

Unsafe cancel:

.. code::
.. terminal::
:input: cou upgrade # ctrl+c is pressed twice during the upgrade

$ 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... ✔
Expand All @@ -91,4 +88,3 @@ Unsafe cancel:
Running cloud upgrade...
Canceling upgrade... (Press ctrl+c again to stop immediately) ✖
charmed-openstack-upgrader has been terminated without waiting
$
10 changes: 5 additions & 5 deletions docs/how-to/no-backup.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ By default, **COU** plans for and runs a backup step of the cloud database befor
proceeding to actual upgrade steps. This can be turned off with `--no-backup` flag.

Usage examples
~~~~~~~~~~~~~~
--------------

Plan:

.. code::
.. terminal::
:input: cou plan --no-backup

$ cou plan --no-backup
Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
Connected to 'test-model' ✔
Analyzing cloud... ✔
Expand All @@ -27,9 +27,9 @@ Plan:

Upgrade:

.. code::
.. terminal::
:input: cou upgrade --no-backup

$ cou upgrade --no-backup
Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
Connected to 'test-model' ✔
Analyzing cloud... ✔
Expand Down
12 changes: 6 additions & 6 deletions docs/how-to/plan-upgrade.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,16 @@ Plan an upgrade
The **plan** command is used to generate the upgrade plan; the result will be
printed on STDOUT.

.. code::
.. code:: bash
$ cou plan
cou plan
Usage example
~~~~~~~~~~~~~
-------------

.. code::
$ cou plan
.. terminal::
:input: cou plan

Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
Connected to 'test-model' ✔
Analyzing cloud... ✔
Expand Down
22 changes: 11 additions & 11 deletions docs/how-to/upgrade-cloud.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,16 @@ Use the **upgrade** command to automatically plan and execute the upgrade of you
cloud. This command runs upgrade in interactive mode by default, requiring the user
to confirm each step.

.. code::
.. code:: bash

$ cou upgrade
cou upgrade

Usage example
^^^^^^^^^^^^^
~~~~~~~~~~~~~

.. code::
.. terminal::
:input: cou upgrade

$ cou upgrade
Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211917.log'
Connected to 'test-model' ✔
Analyzing cloud... ✔
Expand Down Expand Up @@ -122,13 +122,13 @@ allows **COU** to be used by scripts or during upgrade testing. A quiet mode swi
is also offered, which will only output error logs and a completion message to STDOUT.

Usage examples
^^^^^^^^^^^^^^
~~~~~~~~~~~~~~

Non-interactive mode:

.. code::
.. terminal::
:input: cou upgrade --no-interactive
aieri marked this conversation as resolved.
Show resolved Hide resolved

$ cou upgrade --no-interactive
Full execution log: '/home/ubuntu/.local/share/cou/log/cou-20231215211717.log'
Connected to 'test-model' ✔
Analyzing cloud... ✔
Expand All @@ -145,7 +145,7 @@ Non-interactive mode:

Non-interactive and quiet mode:

.. code::

$ cou upgrade --no-interactive --quiet
.. terminal::
:input: cou upgrade --no-interactive --quiet
aieri marked this conversation as resolved.
Show resolved Hide resolved

Upgrade completed.
18 changes: 9 additions & 9 deletions docs/how-to/verbosity.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,28 @@ log level.
The default verbosity level is **error**.

Usage examples
~~~~~~~~~~~~~~
--------------

The warning level.

.. code::
.. code:: bash

$ cou upgrade -v
cou upgrade -v

The info level.

.. code::
.. code:: bash

$ cou upgrade -vv
cou upgrade -vv

The debug level for all messages except **python-libjuju** and **websockets**.

.. code::
.. code:: bash

$ cou upgrade -vvv
cou upgrade -vvv

The debug level for all messages including the **python-libjuju** and **websockets**.

.. code::
.. code:: bash

$ cou upgrade -vvvv
cou upgrade -vvvv
2 changes: 2 additions & 0 deletions docs/readme.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
:orphan:

Documentation starter pack
==========================

Expand Down
11 changes: 6 additions & 5 deletions docs/reference/commands.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ The **plan** command will analyse the cloud and output a human-readable represen
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
.. terminal::
:input: cou plan --help

Usage: cou plan [options]

Show the steps COU will take to upgrade the cloud to the next release.
Expand All @@ -35,8 +35,9 @@ 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
.. terminal::
:input: cou upgrade --help

Usage: cou upgrade [options]

Run the cloud upgrade.
Expand Down
2 changes: 2 additions & 0 deletions docs/setup-script.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
:orphan:

Setup script
============

Expand Down