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
This commit is contained in:
Peter Matulis 2022-05-24 15:14:59 -04:00
parent 70a2ebe80f
commit 278f3d826b
10 changed files with 200 additions and 144 deletions

View File

@ -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

View File

@ -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
<placement-charm-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

View File

@ -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

View File

@ -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'

View File

@ -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 <upgrade-ussuri-to-victoria>`
* :doc:`Stein to Train <upgrade-stein-to-train>`
* :doc:`Queens to Rocky <upgrade-queens-to-rocky>`
* :doc:`Newton to Ocata <upgrade-newton-to-ocata>`
* :doc:`Mitaka to Newton <upgrade-mitaka-to-newton>`
Manual intervention
~~~~~~~~~~~~~~~~~~~

View File

@ -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

View File

@ -19,7 +19,6 @@ Procedures
* :doc:`LVM support in cinder charm: migration to cinder-lvm <cinder-lvm-migration>`
* :doc:`percona-cluster charm: series upgrade to focal <percona-series-upgrade-to-focal>`
* :doc:`placement charm: OpenStack upgrade to Train <placement-charm-upgrade-to-train>`
* :doc:`ceph charm: migration to ceph-mon and ceph-osd <ceph-charm-migration>`
* :doc:`All charms: migration to channels <charmhub-migration>`

View File

@ -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

View File

@ -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

View File

@ -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