charm-deployment-guide/deploy-guide/source/upgrade-overview.rst

Upgrades overview

The purpose of the Upgrades section is to show how to upgrade Charmed OpenStack as a whole. This page provides a summary of the involved components and how they relate to each other. The upgrade of each of the components are distinct operations and are referred to as separate upgrade types. They are defined in this way:

Charms upgrade

An upgrade of the charms that are used to deploy and manage Charmed OpenStack. This includes charms that manage applications which are not technically part of the OpenStack project such as Ceph, RabbitMQ, and Vault.

OpenStack upgrade

An upgrade of the software deployed by the OpenStack charms. Each application is upgraded via its corresponding charm. This constitutes an upgrade from one major OpenStack version to the next (e.g. Xena to Yoga).

Series upgrade

An upgrade of the Ubuntu operating system (e.g. Focal to Jammy) on the cloud nodes. This includes containers.

Important

Once initiated, an upgrade type should be completed to its fullest extent across the cloud. Operating a cloud consisting of partially upgraded components is not tested nor supported.

Cloud topology

All upgrade procedures assume a specific hyperconverged cloud topology.

Caution

Any deviation from the described topology may require adjustments to the given procedural steps. In particular, look at differences in co-located principal applications.

The topology is defined in this way:

• Only compute and storage charms (and their subordinates) are co-located.
• Third-party charms either do not exist or have been thoroughly tested for all three upgrade types.
• The following services run in LXD containers:
  • all API applications
  • the database application (percona-cluster or mysql-innodb-cluster)
  • the rabbitmq-server application
  • the ceph-mon application
• All applications, where possible, are under high availability, whether natively (e.g. ceph-mon, rabbitmq-server) or via hacluster (e.g. keystone).

Development notes

This section includes charm development information that will better prepare the administrator for the task of upgrading Charmed OpenStack.

• It is possible for a charm to gain new functionality that is only supported starting with a specific OpenStack version (e.g. gnocchi S3 support with Stein).
• A charm may occasionally only support a maximum or minimum series (e.g. percona-cluster ending with eoan and mysql-innodb-cluster starting with focal). This is normally due to upstream limitations (e.g Percona XtraDB Cluster no longer supported on Focal).

Note

A charm's limitations concerning OpenStack versions and application features are stated in its README file.

Charm types

There are two general types of OpenStack charms: one that does use channels and one that does not (legacy).

Note

For an overview of how charms are consumed by the end-user see Charm delivery.

Channels

With the channels type, a channel is dedicated to a single OpenStack release (release N-1 will be technically supported to assist with upgrades). This means that a charm that works for a recent series-openstack combination will generally not work on an older combination. Furthermore, there is a need to switch to a different channel in order to upgrade to a new OpenStack version - but not to a new series.

The most recent supported series-openstack combination is focal-yoga. Channels however are available for many older combinations.

Legacy

For the legacy charms, unless stated otherwise, each new revision of a charm includes all the functionality of the previous revision. This means that a charm that works for a recent series-openstack combination will also work on an older combination.

The development of legacy charms has stopped at the 21.10 release of OpenStack Charms (and at the 21.06 release of Trilio Charms). The last supported series-openstack combination is focal-xena.

Software release cycles

Each software component has a predictable release cycle.

Software release cycles

Software	Cycle (months)	Schedule
OpenStack Charms	6	https://docs.openstack.org/charm-guide/latest/release-schedule.html
OpenStack	6	https://releases.openstack.org
Ubuntu	6	https://wiki.ubuntu.com/Releases

Ubuntu LTS releases

One out of every four Ubuntu releases is an LTS release (i.e. 2 year cycle). Charmed OpenStack must be LTS-based as OpenStack upgrades are dependent upon the Ubuntu Cloud Archive (UCA), which only supports LTS releases.

The below graphic shows the release schedule of Ubuntu LTS releases and upstream OpenStack versions. The Ubuntu project and the OpenStack project have deliberately synchronised their respective release cycles.

For example, a deployment can begin on Ubuntu 20.04 LTS (that supports OpenStack Ussuri in its default package archive) and have the ability, over time, to upgrade OpenStack through versions V, W, X, and Y.

Note

Charmed OpenStack on non-LTS Ubuntu releases is supported but should be considered for testing purposes only.

Upgrade order

The order in which to upgrade the different software components is critical. The generic upgrade order is:

1. charms (to latest stable revision for the current charm type)
2. OpenStack (to latest stable version on the current series)
3. series
4. OpenStack (to desired stable version on the new series)

An upgrade type can occur without the need for it to be followed by another upgrade type. For instance, the charms can be upgraded without the necessity of performing an OpenStack upgrade.

However the inverse is not true: in order to achieve an upgrade type there is a requisite upgrade type that needs to be fulfilled. For instance, in order to upgrade a series one needs to ensure that OpenStack has been upgraded to the most recent available version on the current series.

Note

Irrespective of OpenStack or series upgrades, the charms should be upgraded before making topological changes to the cloud, conducting charm application migrations, or submitting bug reports.

Two example scenarios are provided next.

target: a specific Ubuntu release

• Current state: OpenStack Xena on Ubuntu 20.04 LTS
• Goal state: Ubuntu 22.04 LTS

Upgrade path:

1. Upgrade charms to latest stable revision for the current charm type
2. Upgrade OpenStack from Xena to Yoga
3. Upgrade series from focal to jammy

Final result: OpenStack Yoga on Ubuntu 22.04 LTS

target: a specific OpenStack version

• Current state: OpenStack Ussuri on Ubuntu 18.04 LTS
• Goal state: OpenStack Victoria

Upgrade path:

1. Upgrade charms to latest stable revision for the current charm type
2. Upgrade series from bionic to focal
3. Upgrade OpenStack from Ussuri to Victoria

Final result: OpenStack Victoria on Ubuntu 20.04 LTS

Disable automatic hook retries

For all upgrade types it is recommended to disable automatic hook retries within the model containing the cloud. This will prevent the charms from attempting to resolve any encountered problems, thus providing an early opportunity for the operator to respond accordingly.

Assuming the cloud model is the current working model turn off hook retries in this way:

juju model-config automatically-retry-hooks=false

This change should normally be reverted once the upgrade is completed.

Next steps

Each upgrade type is broken down into more detail on the following pages:

• Charms upgrade <upgrade-charms>
• OpenStack upgrade <upgrade-openstack>
• Series upgrade <upgrade-series>