From 278f3d826bfda8f6cb5298e65cb9970ad7c68994 Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Tue, 24 May 2022 15:14:59 -0400 Subject: [PATCH] Add dedicated OpenStack upgrade path pages Add dedicated OpenStack upgrade migration path pages to make it clearer for upgraders. Doing so also removes non-relevant text from the general upgrade-issues page. Add a redirect to account for the deleted placement charm special procedure page. Closes-Bug: #1970272 Change-Id: Ibd09e9e0d66a6f9e152f37c6ac675eed35c97bde --- deploy-guide/source/_extra/.htaccess | 1 + deploy-guide/source/upgrade-issues.rst | 140 ------------------ .../source/upgrade-mitaka-to-newton.rst | 23 +++ .../source/upgrade-newton-to-ocata.rst | 65 ++++++++ deploy-guide/source/upgrade-openstack.rst | 11 ++ .../source/upgrade-queens-to-rocky.rst | 35 +++++ deploy-guide/source/upgrade-special.rst | 1 - ...o-train.rst => upgrade-stein-to-train.rst} | 42 +++++- .../source/upgrade-ussuri-to-victoria.rst | 25 ++++ deploy-guide/test/redirect-tests.txt | 1 + 10 files changed, 200 insertions(+), 144 deletions(-) create mode 100644 deploy-guide/source/upgrade-mitaka-to-newton.rst create mode 100644 deploy-guide/source/upgrade-newton-to-ocata.rst create mode 100644 deploy-guide/source/upgrade-queens-to-rocky.rst rename deploy-guide/source/{placement-charm-upgrade-to-train.rst => upgrade-stein-to-train.rst} (57%) create mode 100644 deploy-guide/source/upgrade-ussuri-to-victoria.rst diff --git a/deploy-guide/source/_extra/.htaccess b/deploy-guide/source/_extra/.htaccess index 711eae3..9e864e3 100644 --- a/deploy-guide/source/_extra/.htaccess +++ b/deploy-guide/source/_extra/.htaccess @@ -23,6 +23,7 @@ RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/nfv.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/pci-passthrough.html$ /charm-guide/$1/admin/compute/pci-passthrough.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/nova-cells.html$ /charm-guide/$1/admin/compute/nova-cells.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/ironic.html$ /charm-guide/$1/admin/compute/ironic.html +RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/placement-charm-upgrade-to-train.html$ /project-deploy-guide/charm-deployment-guide/$1/uprade-stein-to-train.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/app-ceph-rbd-mirror.html$ /charm-guide/$1/admin/storage/ceph-rbd-mirror.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/ceph-erasure-coding.html$ /charm-guide/$1/admin/storage/ceph-erasure-coding.html RedirectMatch 301 ^/project-deploy-guide/charm-deployment-guide/([^/]+)/rgw-multisite.html$ /charm-guide/$1/admin/storage/ceph-rgw-multisite.html diff --git a/deploy-guide/source/upgrade-issues.rst b/deploy-guide/source/upgrade-issues.rst index 2bc263a..f3ceca7 100644 --- a/deploy-guide/source/upgrade-issues.rst +++ b/deploy-guide/source/upgrade-issues.rst @@ -115,117 +115,6 @@ auto-negotiation. See bug `LP #1825999`_. -neutron-gateway charm: upgrading from Mitaka to Newton -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Between the Mitaka and Newton OpenStack releases, the ``neutron-gateway`` charm -added two options, ``bridge-mappings`` and ``data-port``, which replaced the -(now) deprecated ``ext-port`` option. This was to provide for more control over -how ``neutron-gateway`` can configure external networking. Unfortunately, the -charm was only designed to work with either ``ext-port`` (no longer -recommended) *or* ``bridge-mappings`` and ``data-port``. - -See bug `LP #1809190`_. - -cinder/ceph topology change: upgrading from Newton to Ocata -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If cinder is directly related to ceph-mon rather than via cinder-ceph then -upgrading from Newton to Ocata will result in the loss of some block storage -functionality, specifically live migration and snapshotting. To remedy this -situation the deployment should migrate to using the cinder-ceph charm. This -can be done after the upgrade to Ocata. - -.. warning:: - - Do not attempt to migrate a deployment with existing volumes to use the - cinder-ceph charm prior to Ocata. - -The intervention is detailed in the below three steps. - -Step 0: Check existing configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Confirm existing volumes are in an RBD pool called 'cinder': - -.. code-block:: none - - juju run --unit cinder/0 "rbd --name client.cinder -p cinder ls" - -Sample output: - -.. code-block:: none - - volume-b45066d3-931d-406e-a43e-ad4eca12cf34 - volume-dd733b26-2c56-4355-a8fc-347a964d5d55 - -Step 1: Deploy new topology -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Deploy the ``cinder-ceph`` charm and set the 'rbd-pool-name' to match the pool -that any existing volumes are in (see above): - -.. code-block:: none - - juju deploy --config rbd-pool-name=cinder cinder-ceph - juju add-relation cinder cinder-ceph - juju add-relation cinder-ceph ceph-mon - juju remove-relation cinder ceph-mon - juju add-relation cinder-ceph nova-compute - -Step 2: Update volume configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The existing volumes now need to be updated to associate them with the newly -defined cinder-ceph backend: - -.. code-block:: none - - juju run-action cinder/0 rename-volume-host currenthost='cinder' \ - newhost='cinder@cinder-ceph#cinder.volume.drivers.rbd.RBDDriver' - -Keystone and Fernet tokens: upgrading from Queens to Rocky -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting with OpenStack Rocky only the Fernet format for authentication tokens -is supported. Therefore, prior to upgrading Keystone to Rocky a transition must -be made from the legacy format (of UUID) to Fernet. - -Fernet support is available upstream (and in the keystone charm) starting with -Ocata so the transition can be made on either Ocata, Pike, or Queens. - -A keystone charm upgrade will not alter the token format. The charm's -``token-provider`` option must be used to make the transition: - -.. code-block:: none - - juju config keystone token-provider=fernet - -This change may result in a minor control plane outage but any running -instances will remain unaffected. - -The ``token-provider`` option has no effect starting with Rocky, where the -charm defaults to Fernet and where upstream removes support for UUID. See -`Keystone Fernet Token Implementation`_ for more information. - -Neutron LBaaS: upgrading from Stein to Train -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As of Train, support for Neutron LBaaS has been retired. The load-balancing -services are now provided by `Octavia LBaaS`_. There is no automatic migration -path, please review the `Octavia LBaaS`_ page for more information. - -Designate: upgrading from Stein to Train -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When upgrading Designate to Train, there is an encoding issue between the -designate-producer and memcached that causes the designate-producer to crash. -See bug `LP #1828534`_. This can be resolved by restarting the memcached service. - -.. code-block:: none - - juju run --application=memcached 'sudo systemctl restart memcached' - Ceph BlueStore mistakenly enabled during OpenStack upgrade ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -236,15 +125,6 @@ Queens). Problems will occur if storage is scaled out without first disabling BlueStore (set ceph-osd charm option ``bluestore`` to 'False'). See bug `LP #1885516`_ for details. -Placement: endpoints not updated in Keystone service catalog -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When the placement charm is deployed during the upgrade to OpenStack Train (as -described in :doc:`placement charm: OpenStack upgrade to Train -`) the Keystone service catalog is not -updated accordingly. This issue is tracked in bug `LP #1928992`_, which also -includes an explicit workaround (comment #4). - .. _ceph-require-osd-release: Ceph: option ``require-osd-release`` @@ -277,18 +157,6 @@ new release. Here the new release is Octopus: The charms should be able to respond intelligently to these two situations. Bug `LP #1929254`_ is for tracking this effort. -FWaaS: upgrading from Ussuri to Victoria -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Firewall-as-a-Service (`FWaaS v2`_) OpenStack project is retired starting -with OpenStack Victoria. Consequently, the neutron-api charm will no longer -make this service available starting with that OpenStack release. See the -`21.10 Release Notes`_ on this topic. - -Prior to upgrading to Victoria users of FWaaS should remove any existing -firewall groups to avoid the possibility of orphaning active firewalls (see the -`FWaaS v2 CLI documentation`_). - Octavia ~~~~~~~ @@ -327,27 +195,19 @@ error can be resolved with: .. _Ubuntu Cloud Archive: https://wiki.ubuntu.com/OpenStack/CloudArchive .. _Upgrades: https://docs.openstack.org/operations-guide/ops-upgrades.html .. _Update services: https://docs.openstack.org/operations-guide/ops-upgrades.html#update-services -.. _Keystone Fernet Token Implementation: https://specs.openstack.org/openstack/charm-specs/specs/rocky/implemented/keystone-fernet-tokens.html -.. _Octavia LBaaS: app-octavia.html .. _Various issues: various-issues.html .. _Special charm procedures: upgrade-special.html .. _vault charm: https://opendev.org/openstack/charm-vault/src/branch/master/src/README.md#unseal-vault .. _manila exporting shares after restart: https://bugs.launchpad.net/charm-manila-ganesha/+bug/1889287 -.. _21.10 Release Notes: https://docs.openstack.org/charm-guide/latest/2110.html -.. _FWaaS v2: https://docs.openstack.org/neutron/ussuri/admin/fwaas.html -.. _FWaaS v2 CLI documentation: https://docs.openstack.org/python-neutronclient/ussuri/cli/osc/v2/firewall-group.html .. _Rotating amphora images: https://docs.openstack.org/octavia/latest/admin/guides/operator-maintenance.html#rotating-the-amphora-images .. _ceph-radosgw charm change: https://review.opendev.org/c/openstack/charm-ceph-radosgw/+/835827 .. BUGS .. _LP #1825999: https://bugs.launchpad.net/charm-nova-compute/+bug/1825999 -.. _LP #1809190: https://bugs.launchpad.net/charm-neutron-gateway/+bug/1809190 .. _LP #1853173: https://bugs.launchpad.net/charm-openstack-dashboard/+bug/1853173 -.. _LP #1828534: https://bugs.launchpad.net/charm-designate/+bug/1828534 .. _LP #1882508: https://bugs.launchpad.net/charm-deployment-guide/+bug/1882508 .. _LP #1885516: https://bugs.launchpad.net/charm-deployment-guide/+bug/1885516 .. _LP #1886083: https://bugs.launchpad.net/vault-charm/+bug/1886083 .. _LP #1890106: https://bugs.launchpad.net/vault-charm/+bug/1890106 .. _LP #1912638: https://bugs.launchpad.net/charm-rabbitmq-server/+bug/1912638 -.. _LP #1928992: https://bugs.launchpad.net/charm-deployment-guide/+bug/1928992 .. _LP #1929254: https://bugs.launchpad.net/charm-ceph-osd/+bug/1929254 diff --git a/deploy-guide/source/upgrade-mitaka-to-newton.rst b/deploy-guide/source/upgrade-mitaka-to-newton.rst new file mode 100644 index 0000000..f48e393 --- /dev/null +++ b/deploy-guide/source/upgrade-mitaka-to-newton.rst @@ -0,0 +1,23 @@ +:orphan: + +========================= +Upgrade: Mitaka to Newton +========================= + +This page contains notes specific to the Mitaka to Newton upgrade path. See the +main :doc:`upgrade-openstack` page for full coverage. + +neutron-gateway charm options +----------------------------- + +Between the Mitaka and Newton OpenStack releases, the neutron-gateway charm +added two options, ``bridge-mappings`` and ``data-port``, which replaced the +(now) deprecated ``ext-port`` option. This was to provide for more control over +how ``neutron-gateway`` can configure external networking. Unfortunately, the +charm was only designed to work with either ``ext-port`` (no longer +recommended) *or* ``bridge-mappings`` and ``data-port``. + +See bug `LP #1809190`_. + +.. BUGS +.. _LP #1809190: https://bugs.launchpad.net/charm-neutron-gateway/+bug/1809190 diff --git a/deploy-guide/source/upgrade-newton-to-ocata.rst b/deploy-guide/source/upgrade-newton-to-ocata.rst new file mode 100644 index 0000000..4747763 --- /dev/null +++ b/deploy-guide/source/upgrade-newton-to-ocata.rst @@ -0,0 +1,65 @@ +:orphan: + +======================== +Upgrade: Newton to Ocata +======================== + +This page contains notes specific to the Newton to Ocata upgrade path. See the +main :doc:`upgrade-openstack` page for full coverage. + +cinder/ceph topology change +--------------------------- + +If cinder is directly related to ceph-mon rather than via cinder-ceph then +upgrading from Newton to Ocata will result in the loss of some block storage +functionality, specifically live migration and snapshotting. To remedy this +situation the deployment should migrate to using the cinder-ceph charm. This +can be done after the upgrade to Ocata. + +.. warning:: + + Do not attempt to migrate a deployment with existing volumes to use the + cinder-ceph charm prior to Ocata. + +The intervention is detailed in the below three steps. + +Step 0: Check existing configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Confirm existing volumes are in an RBD pool called 'cinder': + +.. code-block:: none + + juju run --unit cinder/0 "rbd --name client.cinder -p cinder ls" + +Sample output: + +.. code-block:: none + + volume-b45066d3-931d-406e-a43e-ad4eca12cf34 + volume-dd733b26-2c56-4355-a8fc-347a964d5d55 + +Step 1: Deploy new topology +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Deploy the ``cinder-ceph`` charm and set the 'rbd-pool-name' to match the pool +that any existing volumes are in (see above): + +.. code-block:: none + + juju deploy --config rbd-pool-name=cinder cinder-ceph + juju add-relation cinder cinder-ceph + juju add-relation cinder-ceph ceph-mon + juju remove-relation cinder ceph-mon + juju add-relation cinder-ceph nova-compute + +Step 2: Update volume configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The existing volumes now need to be updated to associate them with the newly +defined cinder-ceph backend: + +.. code-block:: none + + juju run-action cinder/0 rename-volume-host currenthost='cinder' \ + newhost='cinder@cinder-ceph#cinder.volume.drivers.rbd.RBDDriver' diff --git a/deploy-guide/source/upgrade-openstack.rst b/deploy-guide/source/upgrade-openstack.rst index cdef5ae..bbef710 100644 --- a/deploy-guide/source/upgrade-openstack.rst +++ b/deploy-guide/source/upgrade-openstack.rst @@ -98,6 +98,17 @@ 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. + +* :doc:`Ussuri to Victoria ` +* :doc:`Stein to Train ` +* :doc:`Queens to Rocky ` +* :doc:`Newton to Ocata ` +* :doc:`Mitaka to Newton ` + Manual intervention ~~~~~~~~~~~~~~~~~~~ diff --git a/deploy-guide/source/upgrade-queens-to-rocky.rst b/deploy-guide/source/upgrade-queens-to-rocky.rst new file mode 100644 index 0000000..9c719f6 --- /dev/null +++ b/deploy-guide/source/upgrade-queens-to-rocky.rst @@ -0,0 +1,35 @@ +:orphan: + +======================== +Upgrade: Queens to Rocky +======================== + +This page contains notes specific to the Queens to Rocky upgrade path. See the +main :doc:`upgrade-openstack` page for full coverage. + +Keystone and Fernet tokens +-------------------------- + +Starting with OpenStack Rocky only the Fernet format for authentication tokens +is supported. Therefore, prior to upgrading Keystone to Rocky a transition must +be made from the legacy format (of UUID) to Fernet. + +Fernet support is available upstream (and in the keystone charm) starting with +Ocata so the transition can be made on either Ocata, Pike, or Queens. + +A keystone charm upgrade will not alter the token format. The charm's +``token-provider`` option must be used to make the transition: + +.. code-block:: none + + juju config keystone token-provider=fernet + +This change may result in a minor control plane outage but any running +instances will remain unaffected. + +The ``token-provider`` option has no effect starting with Rocky, where the +charm defaults to Fernet and where upstream removes support for UUID. See +`Keystone Fernet Token Implementation`_ for more information. + +.. LINKS +.. _Keystone Fernet Token Implementation: https://specs.openstack.org/openstack/charm-specs/specs/rocky/implemented/keystone-fernet-tokens.html diff --git a/deploy-guide/source/upgrade-special.rst b/deploy-guide/source/upgrade-special.rst index fb9ee31..88e8502 100644 --- a/deploy-guide/source/upgrade-special.rst +++ b/deploy-guide/source/upgrade-special.rst @@ -19,7 +19,6 @@ Procedures * :doc:`LVM support in cinder charm: migration to cinder-lvm ` * :doc:`percona-cluster charm: series upgrade to focal ` -* :doc:`placement charm: OpenStack upgrade to Train ` * :doc:`ceph charm: migration to ceph-mon and ceph-osd ` * :doc:`All charms: migration to channels ` diff --git a/deploy-guide/source/placement-charm-upgrade-to-train.rst b/deploy-guide/source/upgrade-stein-to-train.rst similarity index 57% rename from deploy-guide/source/placement-charm-upgrade-to-train.rst rename to deploy-guide/source/upgrade-stein-to-train.rst index d588d12..a869f88 100644 --- a/deploy-guide/source/placement-charm-upgrade-to-train.rst +++ b/deploy-guide/source/upgrade-stein-to-train.rst @@ -1,8 +1,14 @@ :orphan: -=========================================== -placement charm: OpenStack upgrade to Train -=========================================== +======================= +Upgrade: Stein to Train +======================= + +This page contains notes specific to the Stein to Train upgrade path. See the +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 @@ -45,6 +51,36 @@ method for a more controlled approach: 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). + +Neutron LBaaS retired +--------------------- + +As of Train, support for Neutron LBaaS has been retired. The load-balancing +services are now provided by Octavia LBaaS. There is no automatic migration +path, please review the :doc:`app-octavia` page for more information. + +Designate encoding issue +------------------------ + +When upgrading Designate to Train, there is an encoding issue between the +designate-producer and memcached that causes the designate-producer to crash. +See bug `LP #1828534`_. This can be resolved by restarting the memcached service. + +.. code-block:: none + + 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/upgrade-ussuri-to-victoria.rst b/deploy-guide/source/upgrade-ussuri-to-victoria.rst new file mode 100644 index 0000000..1395a23 --- /dev/null +++ b/deploy-guide/source/upgrade-ussuri-to-victoria.rst @@ -0,0 +1,25 @@ +:orphan: + +=========================== +Upgrade: Ussuri to Victoria +=========================== + +This page contains notes specific to the Ussuri to Victoria upgrade path. See +the main :doc:`upgrade-openstack` page for full coverage. + +FWaaS project retired +--------------------- + +The Firewall-as-a-Service (`FWaaS v2`_) OpenStack project is retired starting +with OpenStack Victoria. Consequently, the neutron-api charm will no longer +make this service available starting with that OpenStack release. See the +`21.10 release notes`_ on this topic. + +Prior to upgrading to Victoria users of FWaaS should remove any existing +firewall groups to avoid the possibility of orphaning active firewalls (see the +`FWaaS v2 CLI documentation`_). + +.. LINKS +.. _21.10 release notes: https://docs.openstack.org/charm-guide/latest/2110.html +.. _FWaaS v2: https://docs.openstack.org/neutron/ussuri/admin/fwaas.html +.. _FWaaS v2 CLI documentation: https://docs.openstack.org/python-neutronclient/ussuri/cli/osc/v2/firewall-group.html diff --git a/deploy-guide/test/redirect-tests.txt b/deploy-guide/test/redirect-tests.txt index 911187a..79d297c 100644 --- a/deploy-guide/test/redirect-tests.txt +++ b/deploy-guide/test/redirect-tests.txt @@ -25,6 +25,7 @@ /project-deploy-guide/charm-deployment-guide/latest/app-pci-passthrough-gpu.html 301 /project-deploy-guide/charm-deployment-guide/latest/pci-passthrough.html /project-deploy-guide/charm-deployment-guide/latest/app-erasure-coding.html 301 /project-deploy-guide/charm-deployment-guide/latest/ceph-erasure-coding.html /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 ## charm guide /project-deploy-guide/charm-deployment-guide/latest/app-managing-power-events.html 301 /charm-guide/latest/admin/managing-power-events.html