diff --git a/deploy-guide/source/placement-charm-upgrade-to-train.rst b/deploy-guide/source/placement-charm-upgrade-to-train.rst new file mode 100644 index 0000000..9504e60 --- /dev/null +++ b/deploy-guide/source/placement-charm-upgrade-to-train.rst @@ -0,0 +1,48 @@ +:orphan: + +=========================================== +placement charm: OpenStack upgrade to Train +=========================================== + +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 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 +placment 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 + +.. LINKS +.. _placement: https://jaas.ai/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 2a3c0f0..ddf2d4c 100644 --- a/deploy-guide/source/upgrade-charms.rst +++ b/deploy-guide/source/upgrade-charms.rst @@ -10,6 +10,8 @@ Please read the following before continuing: * the :doc:`Upgrades overview ` page * the OpenStack charms `Release Notes`_ for the corresponding current and target versions of OpenStack +* the :doc:`Special charm procedures ` page +* the :doc:`Upgrade issues ` page .. note:: diff --git a/deploy-guide/source/upgrade-issues.rst b/deploy-guide/source/upgrade-issues.rst index 8c9fe44..60bfd0d 100644 --- a/deploy-guide/source/upgrade-issues.rst +++ b/deploy-guide/source/upgrade-issues.rst @@ -2,8 +2,8 @@ Known upgrade issues ==================== -This section documents known issues that may apply to either of the three -upgrade types (charms, OpenStack, series). +This section documents known issues (software limitations/bugs) that may apply +to either of the three upgrade types (charms, OpenStack, series). DNS HA with the focal series ---------------------------- @@ -116,43 +116,6 @@ 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. -Placement charm and nova-cloud-controller: upgrading from Stein to Train ------------------------------------------------------------------------- - -As of 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 requires some coordination to transition to the new API endpoints. - -Prior to upgrading nova-cloud-controller to Train, the placement charm must be -deployed for Train and related to the Stein-based nova-cloud-controller. 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's an example of the steps just described where `nova-cloud-controller/0` -is the leader: - -.. code-block:: none - - juju deploy --series bionic --config openstack-origin=cloud:bionic-train cs:placement - juju run-action nova-cloud-controller/0 pause - juju add-relation placement mysql - juju add-relation placement keystone - juju add-relation placement nova-cloud-controller - openstack endpoint list # ensure placement endpoints are listening on new placment IP address - juju run-action nova-cloud-controller/0 resume - -Only after these steps have been completed can nova-cloud-controller be -upgraded. Here we upgrade all units simultaneously but see the -ref:`paused-single-unit ` service upgrade method for a more -controlled approach: - -.. code-block:: none - - juju config nova-cloud-controller openstack-origin=cloud:bionic-train - Neutron LBaaS: upgrading from Stein to Train -------------------------------------------- diff --git a/deploy-guide/source/upgrade-openstack.rst b/deploy-guide/source/upgrade-openstack.rst index 295737d..d812723 100644 --- a/deploy-guide/source/upgrade-openstack.rst +++ b/deploy-guide/source/upgrade-openstack.rst @@ -14,6 +14,7 @@ Please read the following before continuing: * the :doc:`Upgrades overview ` page * the OpenStack charms `Release Notes`_ for the corresponding current and target versions of OpenStack +* the :doc:`Special charm procedures ` page * the :doc:`Upgrade issues ` page .. note:: diff --git a/deploy-guide/source/upgrade-series.rst b/deploy-guide/source/upgrade-series.rst index f1600ab..6866c77 100644 --- a/deploy-guide/source/upgrade-series.rst +++ b/deploy-guide/source/upgrade-series.rst @@ -12,6 +12,7 @@ Please read the following before continuing: * the :doc:`Upgrades overview ` page * the OpenStack charms `Release Notes`_ for the corresponding current and target versions of OpenStack +* the :doc:`Special charm procedures ` page * the :doc:`Upgrade issues ` page Once this document has been studied the administrator will be ready to graduate diff --git a/deploy-guide/source/upgrade-special.rst b/deploy-guide/source/upgrade-special.rst index 1ce22d9..cfa68b3 100644 --- a/deploy-guide/source/upgrade-special.rst +++ b/deploy-guide/source/upgrade-special.rst @@ -1,15 +1,14 @@ -================================ -Special charm upgrade procedures -================================ +======================== +Special charm procedures +======================== The OpenStack charms are designed to accommodate every supported series and -OpenStack release wherever possible. However, upgrades may occasionally -introduce unavoidable challenges for a deployed charm. For instance, it could -be that a charm is replaced by an entirely new charm on the new series. This -can happen due to development policy concerning the charms themselves or due to -reasons independent of the charms (e.g. the workload software is no longer -supported on the new operating system). Any core OpenStack charms affected in -this way will be documented here: +OpenStack release wherever possible. However, 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 here: * :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 `