Update command.rst to include newly proposed CLI options (#317)

- New explanation page for upgrade groups
- Add upgrade group sub-commands
- Update plan and upgrade help messages
- Add mutual exclusion warning for machine and az

cou/commands.py

@@ -171,17 +171,19 @@ def get_hypervisors_common_opts_parser() -> argparse.ArgumentParser:
         "--machine",
         "-m",
         help="Specify machine id(s) to upgrade.\nThis option accepts a single machine id as well "
-        "as a stringified\ncomma-separated list of ids, and can be repeated multiple times.",
+        "as a stringified\ncomma-separated list of ids, and can be repeated multiple times.\n"
+        "This option cannot be used together with [--availability-zone/--az].",
         dest="machines",
         action=SplitArgs,
         type=str,
     )
     hypervisors_filters.add_argument(
         "--availability-zone",
         "--az",
-        help="Specify availability zone(s) to upgrade.\nThis option accepts a single "
+        help="Specify Juju availability zone(s) to upgrade.\nThis option accepts a single "
         "availability zone as well as a\nstringified comma-separated list of AZs, "
-        "and can be repeated\nmultiple times.",
+        "and can be repeated\nmultiple times. This option cannot be used together with\n"
+        "[--machine/-m]",
         action=SplitArgs,
         dest="availability_zones",
         type=str,
@@ -240,14 +242,15 @@ def create_plan_subparser(
     )
     plan_subparser.add_parser(
         HYPERVISORS,
-        description="Show the steps for upgrading nova-compute machines.\nThis is possible "
-        "only if control-plane has been fully upgraded,\notherwise an error will be thrown.\n\n"
-        "Note that only principal applications colocated with nova-compute units\nthat support "
-        "action-managed upgrades are within the scope of this command.\nOther principal "
-        "applications (e.g. ceph-osd) and subordinates\ncan be upgraded via the data-plane "
-        "subcommand.",
-        help="Show the steps for upgrading nova-compute machines.\nThis is possible "
-        "only if control-plane has been fully upgraded,\notherwise an error will be thrown.",
+        description="Show the steps for upgrading machines with nova-compute and\n"
+        "colocated services. This is possible only if control-plane\nhas been fully upgraded, "
+        "otherwise an error will be thrown.\n\nNote that only principal applications colocated "
+        "with nova-compute units\nthat support action-managed upgrades are within the scope of "
+        "this command.\nOther principal applications (e.g. ceph-osd) and subordinates\ncan be "
+        "upgraded via the data-plane subcommand.",
+        help="Show the steps for upgrading machines with nova-compute and\ncolocated services. "
+        "This is possible only if control-plane\nhas been fully upgraded, otherwise an error "
+        "will be thrown.",
         usage="cou plan hypervisors [options]",
         parents=[subcommand_common_opts_parser, hypervisors_parser],
         formatter_class=CapitalizeHelpFormatter,
@@ -297,7 +300,7 @@ def create_upgrade_subparser(
         "control-plane",
         description="Run upgrade for the control-plane components.",
         help="Run upgrade for the control-plane components.",
-        usage="cou plan control-plane [options]",
+        usage="cou upgrade control-plane [options]",
         parents=[subcommand_common_opts_parser, upgrade_args_parser],
         formatter_class=CapitalizeHelpFormatter,
     )
@@ -307,19 +310,19 @@ def create_upgrade_subparser(
         "control-plane has been fully upgraded,\notherwise an error will be thrown.",
         help="Upgrade all data-plane components.\nThis is possible only if "
         "control-plane has been fully upgraded,\notherwise an error will be thrown.",
-        usage="cou plan data-plane [options]",
+        usage="cou upgrade data-plane [options]",
         parents=[subcommand_common_opts_parser, upgrade_args_parser],
         formatter_class=CapitalizeHelpFormatter,
     )
     upgrade_subparser.add_parser(
         HYPERVISORS,
-        description="Upgrade nova-compute machines.\nThis is possible "
+        description="Upgrade machines with nova-compute and colocated services.\nThis is possible "
         "only if control-plane has been fully upgraded,\notherwise an error will be thrown.\n\n"
         "Note that only principal applications colocated with nova-compute units\nthat support "
         "action-managed upgrades are within the scope of this command.\nOther principal "
         "applications (e.g. ceph-osd) and subordinates\ncan be upgraded via the data-plane "
         "subcommand.",
-        help="Upgrade nova-compute machines.\nThis is possible "
+        help="Upgrade machines with nova-compute and colocated services.\nThis is possible "
         "only if control-plane has been fully upgraded,\notherwise an error will be thrown.",
         usage="cou upgrade hypervisors [options]",
         parents=[

docs/.custom_wordlist.txt

@@ -1,4 +1,5 @@
 OpenStack
+openstack
 Upgrader
 ussuri
 Github
@@ -21,4 +22,23 @@ yaml
 backoff
 BACKOFF
 websockets
-enablement
+enablement
+az
+VMs
+ceph
+osd
+mon
+octavia
+ovn
+api
+manila
+fs
+radosgw
+aodh
+ganesha
+ceilometer
+rabbitmq
+barbican
+mysql
+innodb
+colocated

docs/explanation/index.rst

@@ -11,3 +11,4 @@ and known issues.
    analysis
    planning
    upgrade
+   upgrade-groups

docs/explanation/upgrade-groups.rst

@@ -0,0 +1,77 @@
+==============
+Upgrade Groups
+==============
+
+In the process of planning or executing an upgrade for an OpenStack cloud, users have the
+capability to target a specific group of applications based on their services responsibilities.
+
+**Note:** COU will upgrade **openstack-dashboard** and **octavia** at the end of the
+**control-plane** upgrade (before upgrading **control-plane** subordinate applications
+and **data-plane** services) due to the desired upgrade group splits. This is slightly
+different from the `upstream upgrade documentation`_.
+
+Control Plane
+-------------
+
+The **control-plane** includes services tasked with making decisions related to data management,
+routing, and processing. Services considered as **control-plane** in OpenStack and in scope
+of COU are (following their upgrade order):
+
+- rabbitmq-server
+- ceph-mon
+- keystone
+- aodh
+- barbican
+- ceilometer
+- ceph-fs
+- ceph-radosgw
+- cinder
+- designate
+- designate-bind
+- glance
+- gnocchi
+- heat
+- manila
+- manila-ganesha
+- neutron-api
+- neutron-gateway
+- ovn-dedicated-chassis
+- ovn-central
+- placement
+- nova-cloud-controller
+- openstack-dashboard
+- octavia
+- additional principal applications that contribute to the formation of the OpenStack cloud 
+  (typically **mysql-innodb-cluster**)
+- **control-plane** subordinate applications
+
+
+Data Plane
+----------
+
+On the other hand, the **data-plane** is composed of services that handle the actual data
+transfer. Services considered as **data-plane** in OpenStack and in scope of COU are (following
+their upgrade order):
+
+- nova-compute
+- any **control-plane** services colocated on the same machines with the **nova-compute**
+  application (typically **cinder**)
+- ceph-osd
+- **data-plane** subordinate applications
+
+**Note:** It's essential to complete the upgrade of the **control-plane** components before
+proceeding to any **data-plane** components to ensure cloud functionality.
+
+Hypervisors
+-----------
+
+Within the data-plane are **hypervisors**. In COU they represent machines hosting the hypervisor
+service (**nova-compute**), which facilitate the distribution of compute and memory resources
+among virtual machines (VMs), and other services colocated on the same nodes.
+
+**Note:** Since **hypervisors** comprise a subset of **data-plane** components, it is
+also necessary to complete the upgrade of the **control-plane** components before
+proceeding to **hypervisors** upgrades.
+
+.. LINKS:
+.. _upstream upgrade documentation: https://docs.openstack.org/charm-guide/latest/admin/upgrades/charms.html#upgrade-order

docs/reference/commands.rst

@@ -17,17 +17,38 @@ output below for a description of all allowed options.
     Usage: cou plan [options]
 
     Show the steps COU will take to upgrade the cloud to the next release.
+    If upgrade-group is unspecified, plan upgrade for the whole cloud.
 
     Options:
-    -h, --help        	Show this help message and exit.
-    --model MODEL_NAME	Set the model to operate on.
+      -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
+      --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.
+      --force               Force the plan/upgrade of non-empty hypervisors.
+      --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 groups:
+      {control-plane,data-plane,hypervisors}
+                            Run 'cou plan <upgrade-group> -h' for more info about an upgrade group.
+        control-plane       Show the steps for upgrading the control-plane components.
+        data-plane          Show the steps for upgrading all data-plane components.
+                            This is possible only if control-plane has been fully upgraded,
+                            otherwise an error will be thrown.
+        hypervisors         Show the steps for upgrading machines with nova-compute and
+                            colocated services. This is possible only if control-plane
+                            has been fully upgraded, otherwise an error will be thrown.
+
+By default, COU plans upgrade for the entire OpenStack cloud with `cou plan`. However, the
+upgrade process can be tailored to target a specific group through a sub-command for more
+granular control. For further details, please see the `Upgrade Groups`_ section.
 
 Upgrade
 -------
@@ -41,16 +62,144 @@ upgrade phase. Refer to the output below for a description of all available opti
     Usage: cou upgrade [options]
 
     Run the cloud upgrade.
+    If upgrade-group is unspecified, upgrade the whole cloud.
+
+    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.
+      --force               Force the plan/upgrade of non-empty hypervisors.
+      --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.
+
+    Upgrade group:
+      {control-plane,data-plane,hypervisors}
+                            Run 'cou upgrade <upgrade-group> -h' for more info about an upgrade group
+        control-plane       Run upgrade for the control-plane components.
+        data-plane          Upgrade all data-plane components.
+                            This is possible only if control-plane has been fully upgraded,
+                            otherwise an error will be thrown.
+        hypervisors         Upgrade machines with nova-compute and colocated services.
+                            This is possible only if control-plane has been fully upgraded,
+                            otherwise an error will be thrown.
+
+By default COU upgrades the entire OpenStack cloud with `cou upgrade`. However, the upgrade
+process can be tailored to target a specific group through a sub-command for more granular
+control. For further details, please see the `Upgrade Groups`_ section.
+
+Upgrade Groups
+--------------
+
+In COU, users can choose to selectively target only certain components in OpenStack cloud
+for planning and executing upgrades, grouped by their roles. The available upgrade groups
+are **control-plane**, **data-plane**, and **hypervisors**.
+
+The options available for **control-plane** upgrade are:
+
+.. terminal:: 
+    :input: cou upgrade control-plane --help
+
+    Usage: cou upgrade control-plane [options]
+
+    Run upgrade for the control-plane components.
+
+    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.
+      --force               Force the plan/upgrade of non-empty hypervisors.
+      --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.
+
+The available options for a **data-plane** upgrade align closely with those offered for a
+**control-plane** upgrade.
+
+.. terminal:: 
+    :input: cou upgrade data-plane --help
+
+    Usage: cou upgrade data-plane [options]
+
+    Upgrade all data-plane components.
+    This is possible only if control-plane has been fully upgraded,
+    otherwise an error will be thrown.
 
     Options:
-    -h, --help        	Show this help message and exit.
-    --model MODEL_NAME	Set the model to operate on.
+      -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
+      --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.
+      --force               Force the plan/upgrade of non-empty hypervisors.
+      --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.
+
+For upgrading **hypervisors**, in addition to the common options also found in
+**data-plane** upgrades, users can specify either **--machine** or **--az** to
+narrow the upgrade to a particular subset of nodes.
 
+.. terminal:: 
+    :input: cou upgrade hypervisors --help
+
+    Usage: cou upgrade hypervisors [options]
+
+    Upgrade machines with nova-compute and colocated services.
+    This is possible only if control-plane has been fully upgraded,
+    otherwise an error will be thrown.
+
+    Note that only principal applications colocated with nova-compute units
+    that support action-managed upgrades are within the scope of this command.
+    Other principal applications (e.g. ceph-osd) and subordinates
+    can be upgraded via the data-plane subcommand.
+
+    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.
+      --force               Force the plan/upgrade of non-empty hypervisors.
+      --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.
+      --machine MACHINES, -m MACHINES
+                            Specify machine id(s) to upgrade.
+                            This option accepts a single machine id as well as a stringified
+                            comma-separated list of ids, and can be repeated multiple times.
+                            This option cannot be used together with [--availability-zone/--az].
+      --availability-zone AVAILABILITY_ZONES, --az AVAILABILITY_ZONES
+                            Specify Juju availability zone(s) to upgrade.
+                            This option accepts a single availability zone as well as a
+                            stringified comma-separated list of AZs, and can be repeated
+                            multiple times. This option cannot be used together with
+                            [--machine/-m]
+      --auto-approve        Automatically approve and continue with each upgrade step without prompt.