From 021ca3ebf204eade2e817f61a6fabc649e818c79 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Mon, 1 Aug 2022 22:25:37 -0400 Subject: [PATCH] Refactor issues and procedures Centralise all noteworthy issues and procedures into a single page. This will make it much simpler for users to find important information and will reduce the necessity to include multiple links in many pages. Move the placement charm procedure to its own special charm procedure page and link to it from the stein:train upgrade path page. The new page is currently in the Upgrades section but this is temporary. It will soon be migrated to the charm-guide where it will be placed under the Project section. Include an HTML redirect (and test) for the former upgrade-special page. Change-Id: I3a8abe0d6b82447ca6d2883065cb1a2ce6d906b9 --- deploy-guide/source/_extra/.htaccess | 1 + deploy-guide/source/index.rst | 3 +- deploy-guide/source/issues-and-procedures.rst | 67 +++++++++++++++++++ deploy-guide/source/ovn-migration.rst | 7 +- deploy-guide/source/placement-charm.rst | 54 +++++++++++++++ deploy-guide/source/upgrade-charms.rst | 8 +-- deploy-guide/source/upgrade-issues.rst | 12 +++- deploy-guide/source/upgrade-openstack.rst | 31 ++------- deploy-guide/source/upgrade-overview.rst | 6 +- deploy-guide/source/upgrade-series.rst | 9 +-- deploy-guide/source/upgrade-special.rst | 24 ------- .../source/upgrade-stein-to-train.rst | 58 +++------------- deploy-guide/source/various-issues.rst | 18 ++--- deploy-guide/test/redirect-tests.txt | 1 + 14 files changed, 165 insertions(+), 134 deletions(-) create mode 100644 deploy-guide/source/issues-and-procedures.rst create mode 100644 deploy-guide/source/placement-charm.rst delete mode 100644 deploy-guide/source/upgrade-special.rst diff --git a/deploy-guide/source/_extra/.htaccess b/deploy-guide/source/_extra/.htaccess index a38d5c7..af605b5 100644 --- a/deploy-guide/source/_extra/.htaccess +++ b/deploy-guide/source/_extra/.htaccess @@ -14,6 +14,7 @@ RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/app-pci- RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/app-erasure-coding.html$ /project-deploy-guide/charm-deployment-guide/$1/ceph-erasure-coding.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/app-manila-ganesha.html$ /project-deploy-guide/charm-deployment-guide/$1/manila-ganesha.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/app-ovn.html#migration-from-neutron-ml2-ovs-to-ml2-ovn$ /project-deploy-guide/charm-deployment-guide/$1/ovn-migration.html +RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/upgrade-special.html$ /project-deploy-guide/charm-deployment-guide/$1/issues-and-procedures.html # Migration to charm-guide RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/app-managing-power-events.html$ /charm-guide/$1/admin/managing-power-events.html diff --git a/deploy-guide/source/index.rst b/deploy-guide/source/index.rst index ad22a9b..f70ff1b 100644 --- a/deploy-guide/source/index.rst +++ b/deploy-guide/source/index.rst @@ -29,8 +29,7 @@ OpenStack Charms usage. To help improve it you can `file an issue`_ or upgrade-charms upgrade-openstack upgrade-series - upgrade-special - upgrade-issues + issues-and-procedures .. LINKS .. _file an issue: https://bugs.launchpad.net/charm-deployment-guide/+filebug diff --git a/deploy-guide/source/issues-and-procedures.rst b/deploy-guide/source/issues-and-procedures.rst new file mode 100644 index 0000000..f962739 --- /dev/null +++ b/deploy-guide/source/issues-and-procedures.rst @@ -0,0 +1,67 @@ +===================================================== +Issues, charm procedures, and OpenStack upgrade notes +===================================================== + +This page centralises all software issues, special charm procedures, and +OpenStack upgrade path notes. + +.. important:: + + The documentation of issues and procedures are not duplicated amid the + below-mentioned pages. For instance, an issue related to a specific + OpenStack upgrade path is not repeated in the + :ref:`upgrade_issues_openstack_upgrades` section of the Upgrade issues page + (an upgrade issue can potentially affect multiple OpenStack upgrade paths). + +Software issues +--------------- + +Software issues mentioned here can be related to the charms or upstream +OpenStack. Both upgrade and various non-upgrade (but noteworthy) issues are +documented. Note that an upgrade issue can affect either of the three types of +upgrades (charms, OpenStack, series). The following pages document the most +important unresolved software issues in Charmed OpenStack: + +.. toctree:: + :maxdepth: 1 + + upgrade-issues + various-issues + +Special charm procedures +------------------------ + +During the lifetime of a cloud, the evolution of the upstream software or that +of the charms will necessitate action on the part of the cloud administrator. +This often involves replacing existing charms with new charms. For example, a +charm may become deprecated and be superseded by a new charm, resulting in a +recommendation (or a requirement) to use the new charm. The following is the +list of documented special charm procedures: + +.. toctree:: + :maxdepth: 1 + + ceph-charm-migration + percona-series-upgrade-to-focal + placement-charm + cinder-lvm-migration + charmhub-migration + ovn-migration + +OpenStack upgrade path notes +---------------------------- + +Occasionally, a specific OpenStack upgrade path will require particular +attention. These upgrade notes typically contain software issues. If a special +charm procedure is pertinent however, it will be mentioned. It is important to +study the page that may apply to your upgrade scenario. The following is the +list of documented OpenStack upgrade path notes: + +.. toctree:: + :maxdepth: 1 + + upgrade-ussuri-to-victoria + upgrade-stein-to-train + upgrade-queens-to-rocky + upgrade-newton-to-ocata + upgrade-mitaka-to-newton diff --git a/deploy-guide/source/ovn-migration.rst b/deploy-guide/source/ovn-migration.rst index f42710d..d898edf 100644 --- a/deploy-guide/source/ovn-migration.rst +++ b/deploy-guide/source/ovn-migration.rst @@ -18,8 +18,8 @@ with these charms: * ovn-chassis (or ovn-dedicated-chassis) * neutron-api-plugin-ovn charms -Post-migration, the :doc:`cg:admin/networking/ovn` page in the Charm Guide -includes information on configuration and usage. +Post-migration, the :doc:`cg:admin/networking/ovn/index` page in the Charm +Guide includes information on configuration and usage. MTU considerations ------------------ @@ -201,7 +201,8 @@ of the actual migration. 5. Unseal Vault (see the `vault charm`_), set up TLS certificates (see `Managing TLS certificates`_), and validate that the services on ovn-central units are running as expected. Please refer to the OVN - :doc:`cg:admin/networking/ovn` page in the Charm Guide for more information. + :doc:`cg:admin/networking/ovn/index` page in the Charm Guide for more + information. Perform the migration --------------------- diff --git a/deploy-guide/source/placement-charm.rst b/deploy-guide/source/placement-charm.rst new file mode 100644 index 0000000..14a6e7a --- /dev/null +++ b/deploy-guide/source/placement-charm.rst @@ -0,0 +1,54 @@ +=========================================== +placement charm: OpenStack upgrade to Train +=========================================== + +.. note:: + + This page describes a procedure that is required when performing an upgrade + of an OpenStack cloud. Please read the more general :doc:`upgrade-overview` + before attempting any of the instructions given here. + +As of OpenStack Train, the Placement API is managed by the new `placement`_ +charm and is no longer managed by the nova-cloud-controller charm. The upgrade +to Train therefore involves some coordination to transition to the new API +endpoints. + +Prior to upgrading nova-cloud-controller services to Train, the placement charm +must be deployed for Train and related to the Stein-based nova-cloud-controller +application. It is important that the nova-cloud-controller unit leader is +paused while the API transition occurs (paused prior to adding relations for +the placement charm) as the placement charm will migrate existing placement +tables from the nova_api database to a new placement database. Once the new +placement endpoints are registered, nova-cloud-controller can be resumed. + +Here are example commands for the process just described: + +.. code-block:: none + + juju deploy --series bionic --config openstack-origin=cloud:bionic-train cs:placement + juju run-action --wait nova-cloud-controller/leader pause + juju add-relation placement percona-cluster + juju add-relation placement keystone + juju add-relation placement nova-cloud-controller + +List endpoints and ensure placement endpoints are now listening on the new +placement IP address. Follow this up by resuming nova-cloud-controller: + +.. code-block:: none + + openstack endpoint list + juju run-action --wait nova-cloud-controller/leader resume + +Finally, upgrade the nova-cloud-controller services. Below all units are +upgraded simultaneously but see the `paused-single-unit`_ service upgrade +method for a more controlled approach: + +.. code-block:: none + + juju config nova-cloud-controller openstack-origin=cloud:bionic-train + +The Compute service (nova-compute) should then be upgraded. + +.. LINKS +.. _placement: https://charmhub.io/placement +.. _paused-single-unit: upgrade-openstack.html#paused-single-unit diff --git a/deploy-guide/source/upgrade-charms.rst b/deploy-guide/source/upgrade-charms.rst index cf2693f..cfeb9e8 100644 --- a/deploy-guide/source/upgrade-charms.rst +++ b/deploy-guide/source/upgrade-charms.rst @@ -7,11 +7,9 @@ The Juju command to use is :command:`upgrade-charm`. For extra guidance see Please read the following before continuing: -* the :doc:`Upgrades overview ` page -* the OpenStack Charms `Release Notes`_ -* the :doc:`Special charm procedures ` page -* the :doc:`Upgrade issues ` page -* the :doc:`Various issues ` page +* :doc:`upgrade-overview` +* :doc:`cg:release-notes/index` +* :doc:`issues-and-procedures` .. note:: diff --git a/deploy-guide/source/upgrade-issues.rst b/deploy-guide/source/upgrade-issues.rst index f3ceca7..da2bd23 100644 --- a/deploy-guide/source/upgrade-issues.rst +++ b/deploy-guide/source/upgrade-issues.rst @@ -5,10 +5,10 @@ Upgrade issues This page documents upgrade issues and notes. These may apply to either of the three upgrade types (charms, OpenStack, series). -The items on this page are distinct from those found on the following pages: +.. important:: -* the `Various issues`_ page -* the `Special charm procedures`_ page + It is recommended to read the :doc:`issues-and-procedures` page before + continuing. The issues are organised by upgrade type: @@ -17,6 +17,8 @@ The issues are organised by upgrade type: :depth: 2 :backlinks: top +.. _upgrade_issues_charm_upgrades: + Charm upgrades -------------- @@ -100,6 +102,8 @@ modified (remove the trailing slash) with native OpenStack tooling: openstack endpoint list --service product-streams openstack endpoint set --url +.. _upgrade_issues_openstack_upgrades: + OpenStack upgrades ------------------ @@ -168,6 +172,8 @@ post-upgrade task. Reasons for doing this include: See the upstream documentation on `Rotating amphora images`_. +.. _upgrade_issues_series_upgrades: + Series upgrades --------------- diff --git a/deploy-guide/source/upgrade-openstack.rst b/deploy-guide/source/upgrade-openstack.rst index 641d3e3..4392441 100644 --- a/deploy-guide/source/upgrade-openstack.rst +++ b/deploy-guide/source/upgrade-openstack.rst @@ -10,8 +10,7 @@ Charmed OpenStack cloud. Upgrading an OpenStack cloud is not risk-free. The procedures outlined in this guide should first be tested in a pre-production environment. -Please read the :doc:`Upgrades overview ` page before -continuing. +Please read the :doc:`upgrade-overview` page before continuing. .. note:: @@ -98,36 +97,15 @@ versions of OpenStack must be consulted for any special instructions. In particular, pay attention to services and/or configuration options that may be retired, deprecated, or changed. -Upgrade path notes -~~~~~~~~~~~~~~~~~~ - -Any notes relevant to a specific upgrade path are recorded here. - -.. toctree:: - :maxdepth: 1 - - Ussuri to Victoria - Stein to Train - Queens to Rocky - Newton to Ocata - Mitaka to Newton - Manual intervention ~~~~~~~~~~~~~~~~~~~ By design, the latest stable charms will support the software changes related to the OpenStack services being upgraded. During the upgrade, the charms will also strive to preserve the existing configuration of their associated -services. - -However, there are still times when intervention on the part of the operator -may be needed, such as when an OpenStack service is removed/added/replaced or -when a software bug (in the charms or in upstream OpenStack) affecting the -upgrade is present. The below resources cover these topics: - -* :doc:`Special charm procedures ` -* :doc:`Upgrade issues ` -* :doc:`Various issues ` +services. Upstream OpenStack is also designed to support N+1 upgrades. However, +there may still be times when intervention on the part of the operator is +needed. The :doc:`issues-and-procedures` page covers this topic. Ensure cloud node software is up to date ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -605,7 +583,6 @@ The :doc:`OpenStack upgrade example ` page shows the explicit steps used to upgrade a basic cloud. .. LINKS -.. _Release Notes: https://docs.openstack.org/charm-guide/latest/release-notes.html .. _Ubuntu Cloud Archive: https://wiki.ubuntu.com/OpenStack/CloudArchive .. _Upgrades: https://docs.openstack.org/operations-guide/ops-upgrades.html .. _Percona strict mode: https://www.percona.com/doc/percona-xtradb-cluster/LATEST/features/pxc-strict-mode.html diff --git a/deploy-guide/source/upgrade-overview.rst b/deploy-guide/source/upgrade-overview.rst index 95d760b..17e83d1 100644 --- a/deploy-guide/source/upgrade-overview.rst +++ b/deploy-guide/source/upgrade-overview.rst @@ -244,9 +244,9 @@ Next steps Each upgrade type is broken down into more detail on the following pages: -* :doc:`Charms upgrade ` -* :doc:`OpenStack upgrade ` -* :doc:`Series upgrade ` +* :doc:`upgrade-charms` +* :doc:`upgrade-openstack` +* :doc:`upgrade-series` .. LINKS .. _Ubuntu Cloud Archive: https://wiki.ubuntu.com/OpenStack/CloudArchive diff --git a/deploy-guide/source/upgrade-series.rst b/deploy-guide/source/upgrade-series.rst index 260c3e9..f303383 100644 --- a/deploy-guide/source/upgrade-series.rst +++ b/deploy-guide/source/upgrade-series.rst @@ -9,11 +9,9 @@ entirely new version. Please read the following before continuing: -* the :doc:`Upgrades overview ` page -* the OpenStack Charms `Release Notes`_ -* the :doc:`Special charm procedures ` page -* the :doc:`Upgrade issues ` page -* the :doc:`Various issues ` page +* :doc:`upgrade-overview` +* :doc:`cg:release-notes/index` +* :doc:`issues-and-procedures` Once this document has been studied the administrator will be ready to graduate to the :doc:`Series upgrade OpenStack ` guide that @@ -353,7 +351,6 @@ the :doc:`Series upgrade OpenStack ` page. .. LINKS .. _Ubuntu releases wiki page: https://wiki.ubuntu.com/Releases -.. _Release Notes: https://docs.openstack.org/charm-guide/latest/release-notes.html .. _Charms upgrade: upgrade-charms.html .. _OpenStack upgrade: upgrade-openstack.html .. _Known OpenStack upgrade issues: upgrade-issues.html diff --git a/deploy-guide/source/upgrade-special.rst b/deploy-guide/source/upgrade-special.rst deleted file mode 100644 index 0a243c9..0000000 --- a/deploy-guide/source/upgrade-special.rst +++ /dev/null @@ -1,24 +0,0 @@ -======================== -Special charm procedures -======================== - -Upgrades, of either of the three types, may occasionally introduce unavoidable -challenges. For instance, it could be that a charm is replaced by an entirely -new charm on a new series or a new charm is needed to accommodate a new service -on a new OpenStack release. These kinds of special procedures are documented on -this page. - -See the :doc:`upgrade-overview` page for general upgrade information. - -Procedures ----------- - -.. toctree:: - :maxdepth: 1 - - cinder-lvm-migration - percona-series-upgrade-to-focal - ceph-charm-migration - charmhub-migration - ovn-migration - diff --git a/deploy-guide/source/upgrade-stein-to-train.rst b/deploy-guide/source/upgrade-stein-to-train.rst index d9cf277..78912b4 100644 --- a/deploy-guide/source/upgrade-stein-to-train.rst +++ b/deploy-guide/source/upgrade-stein-to-train.rst @@ -8,54 +8,16 @@ main :doc:`upgrade-openstack` page for full coverage. New placement charm ------------------- -As of OpenStack Train, the Placement API is managed by the new `placement`_ -charm and is no longer managed by the nova-cloud-controller charm. The upgrade -to Train therefore involves some coordination to transition to the new API -endpoints. +This upgrade path requires the inclusion of a new charm. Please see special +charm procedure :doc:`placement-charm`. -Prior to upgrading nova-cloud-controller services to Train, the placement charm -must be deployed for Train and related to the Stein-based nova-cloud-controller -application. It is important that the nova-cloud-controller unit leader is -paused while the API transition occurs (paused prior to adding relations for -the placement charm) as the placement charm will migrate existing placement -tables from the nova_api database to a new placement database. Once the new -placement endpoints are registered, nova-cloud-controller can be resumed. +Placement endpoints not updated in Keystone service catalogue +------------------------------------------------------------- -Here are example commands for the process just described: - -.. code-block:: none - - juju deploy --series bionic --config openstack-origin=cloud:bionic-train cs:placement - juju run-action --wait nova-cloud-controller/leader pause - juju add-relation placement percona-cluster - juju add-relation placement keystone - juju add-relation placement nova-cloud-controller - -List endpoints and ensure placement endpoints are now listening on the new -placement IP address. Follow this up by resuming nova-cloud-controller: - -.. code-block:: none - - openstack endpoint list - juju run-action --wait nova-cloud-controller/leader resume - -Finally, upgrade the nova-cloud-controller services. Below all units are -upgraded simultaneously but see the `paused-single-unit`_ service upgrade -method for a more controlled approach: - -.. code-block:: none - - juju config nova-cloud-controller openstack-origin=cloud:bionic-train - -The Compute service (nova-compute) should then be upgraded. - -Placement endpoints not updated in Keystone service catalog ------------------------------------------------------------ - -When the placement charm is deployed during the upgrade to Train (as described -above) the Keystone service catalog is not updated accordingly. This issue is -tracked in bug `LP #1928992`_, which also includes an explicit workaround -(comment #4). +When the placement charm is deployed during the upgrade to Train (as per the +above section) the Keystone service catalogue is not updated accordingly. This +issue is tracked in bug `LP #1928992`_, which also includes an explicit +workaround (comment #4). Neutron LBaaS retired --------------------- @@ -76,10 +38,6 @@ See bug `LP #1828534`_. This can be resolved by restarting the memcached service juju run --application=memcached 'sudo systemctl restart memcached' -.. LINKS -.. _placement: https://charmhub.io/placement -.. _paused-single-unit: upgrade-openstack.html#paused-single-unit - .. BUGS .. _LP #1828534: https://bugs.launchpad.net/charm-designate/+bug/1828534 .. _LP #1928992: https://bugs.launchpad.net/charm-deployment-guide/+bug/1928992 diff --git a/deploy-guide/source/various-issues.rst b/deploy-guide/source/various-issues.rst index 1ca652a..9272f7c 100644 --- a/deploy-guide/source/various-issues.rst +++ b/deploy-guide/source/various-issues.rst @@ -1,5 +1,3 @@ -:orphan: - ============== Various issues ============== @@ -7,13 +5,13 @@ Various issues This page documents various issues (software limitations/bugs) that may apply to a Charmed OpenStack cloud. These are still-valid issues that have arisen during the development cycles of past OpenStack Charms releases. The most -recently discovered issues are documented in the `Release notes`_ of the latest -version of the OpenStack Charms. +recently discovered issues are documented in the :doc:`cg:release-notes/index` +of the latest version of the OpenStack Charms. -The items on this page are distinct from those found on the following pages: +.. important:: -* `Upgrade issues`_ -* `Special charm procedures`_ + It is recommended to read the :doc:`issues-and-procedures` page before + continuing. Lack of FQDN for containers on physical MAAS nodes may affect running services ------------------------------------------------------------------------------ @@ -34,7 +32,7 @@ order for the new backend to be registered. This issue is tracked in bug `LP #1914819`_. OVN and SR-IOV: servicing external DHCP and metadata requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------------------- When instances are deployed with SR-IOV networking in an OVN deployment a change of configuration may be required to retain servicing of DHCP and @@ -49,7 +47,7 @@ for L3 routers and external services differently, and is tracked in bug `LP #1946456`_. Ceph RBD Mirror and Ceph Octopus -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------- Due to an unresolved permission issue the ceph-rbd-mirror charm will stay in a blocked state after configuring mirroring for pools when connected to a Ceph @@ -57,8 +55,6 @@ Octopus cluster. See bug `LP #1879749`_ for details. .. LINKS .. _Release notes: https://docs.openstack.org/charm-guide/latest/release-notes.html -.. _Upgrade issues: upgrade-issues.html -.. _Special charm procedures: upgrade-special.html .. BUGS .. _LP #1896630: https://bugs.launchpad.net/charm-layer-ovn/+bug/1896630 diff --git a/deploy-guide/test/redirect-tests.txt b/deploy-guide/test/redirect-tests.txt index dd62195..71398bc 100644 --- a/deploy-guide/test/redirect-tests.txt +++ b/deploy-guide/test/redirect-tests.txt @@ -27,6 +27,7 @@ /project-deploy-guide/charm-deployment-guide/latest/app-manila-ganesha.html 301 /project-deploy-guide/charm-deployment-guide/latest/manila-ganesha.html /project-deploy-guide/charm-deployment-guide/latest/placement-charm-upgrade-to-train.html 301 /project-deploy-guide/charm-deployment-guide/latest/uprade-stein-to-train.html /project-deploy-guide/charm-deployment-guide/latest/app-ovn.html#migration-from-neutron-ml2-ovs-to-ml2-ovn 301 /project-deploy-guide/charm-deployment-guide/latest/ovn-migration.html +/project-deploy-guide/charm-deployment-guide/latest/upgrade-special.html 301 /project-deploy-guide/charm-deployment-guide/latest/issues-and-procedures.html # Migration to charm-guide /project-deploy-guide/charm-deployment-guide/latest/app-managing-power-events.html 301 /charm-guide/latest/admin/managing-power-events.html