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

Charms upgrade

The Juju command to use is upgrade-charm. For extra guidance see Upgrading applications in the Juju documentation.

Please read the following before continuing:

• the Upgrades overview <upgrade-overview> page
• the OpenStack Charms Release Notes
• the Special charm procedures <upgrade-special> page
• the Upgrade issues <upgrade-issues> page
• the Various issues <various-issues> page

Note

A charm upgrade affects all corresponding units; upgrading on a per-unit basis is not currently supported.

Upgrade order

There is no special order in which to upgrade the charms. The order described here is based on the upgrade order for OpenStack upgrades <openstack_upgrade_order>, which, in turn, is the order used by internal testing.

Note

Although it may be possible to upgrade some charms concurrently it is recommended that charm upgrades be performed sequentially (i.e. one at a time). Verify a charm upgrade before moving on to the next.

The general order is:

1. all principle charms
2. all subordinate charms

The precise order within the group of principle charms is shown in the below table.

Principle charms

Order	Charm
1	percona-cluster or mysql-innodb-cluster
2	rabbitmq-server
3	ceph-mon
4	keystone
5	aodh
6	barbican
7	ceilometer
8	ceph-fs
9	ceph-radosgw
10	cinder
11	designate
12	designate-bind
13	glance
14	gnocchi
15	heat
16	manila
17	manila-generic
18	neutron-api
19	neutron-gateway or ovn-central
20	placement
21	nova-cloud-controller
22	openstack-dashboard
23	nova-compute
24	ovn-dedicated-chassis
25	ceph-osd
26	swift-proxy
27	swift-storage

Upgrade testing for subordinate charms does not follow a prescribed order. Once all the principle charms have been processed all the subordinate charms can then be upgraded in any order.

Perform the upgrade

Prior to upgrading a charm, say keystone, a (partial) output to juju status may look like:

App       Version  Status   Scale  Charm     Store       Rev  OS      Notes
keystone  15.0.0   active       1  keystone  jujucharms  306  ubuntu

Unit             Workload  Agent  Machine  Public address  Ports      Message
keystone/0*      active    idle   3/lxd/1  10.248.64.69    5000/tcp   Unit is ready

Here, as deduced from the Keystone service version of '15.0.0', the cloud is running Stein. The 'keystone' charm however shows a revision number of '306'. Upon charm upgrade, the service version will remain unchanged but the charm revision is expected to increase in number.

So to upgrade this 'keystone' charm (to the most recent promulgated version in the Charm Store):

juju upgrade-charm keystone

The upgrade progress can be monitored via juju status. Any encountered problem will surface as a message in its output. This sample (partial) output reflects a successful upgrade:

App       Version  Status   Scale  Charm     Store       Rev  OS      Notes
keystone  15.0.0   active       1  keystone  jujucharms  309  ubuntu

Unit             Workload  Agent  Machine  Public address  Ports      Message
keystone/0*      active    idle   3/lxd/1  10.248.64.69    5000/tcp   Unit is ready

This shows that the charm now has a revision number of '309' but Keystone itself remains at '15.0.0'.

Caution

Any software changes that may have (exceptionally) been made to a charm currently running on a unit will be overwritten by the target charm during the upgrade.

Upgrade target revisions

By default the upgrade-charm command will upgrade a charm to its latest stable revision (a possible multi-step upgrade). This means that intervening revisions can be conveniently skipped. Use the --revision option to specify a target revision.

The current revision can be discovered via juju status output (see column 'Rev'). For the ceph-mon charm:

App       Version  Status  Scale  Charm     Store       Rev  OS      Notes
ceph-mon  13.2.8   active      3  ceph-mon  jujucharms   48  ubuntu

The latest available stable revision of a charm can be obtained by querying the Charm Store with the charm snap:

sudo snap install charm --classic
charm pull ceph-mon

Sample output:

cs:ceph-mon-48

Based on the above, the ceph-mon charm does not require an upgrade.

Important

As stated earlier, any kind of upgrade should first be tested in a pre-production environment. OpenStack charm upgrades have been tested for single-step upgrades only (N+1).