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 for the corresponding current and target versions of OpenStack
• the Special charm procedures <upgrade-special> page
• the Upgrade issues <upgrade-issues> page

Note

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

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

Subordinate charms are upgraded as normal, and, in theory, their upgrade order in relation to their principal charm is not important. Internal testing however does upgrade the principal charm first.

In terms of the upgrade order, begin with 'keystone'. After that, the rest of the charms can be upgraded in any order.

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.

Before upgrading, 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'.

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).