New 2.5 feature: Machine series upgrades


Now that 2.5 is released I’d like to call out some of the new features for
those who haven’t been following the development this cycle.

In this post I’ll be covering machine series upgrades.

Rework of machine series upgrades

With v.2.5 a new command makes its appearance: upgrade-series. By design,
the bulk of the underlying operating system is upgraded manually by the user by
way of standard tooling (e.g. do-release-upgrade).

The usefulness is that workload machines can now have their series updated
natively. In previous versions the recommended approach was to add a new unit
and remove the old one.

Here, we’ll be upgrading a machine (with an ID of ‘1’) to Ubuntu 18.04 LTS

juju upgrade-series 1 prepare bionic

This causes Juju to perform a few internal changes but for the most part the
machine remains the same. We now manually upgrade the machine via SSH:

juju ssh 1
$ do-release-upgrade
<any other custom care the machine may need>

When done we inform Juju:

juju upgrade-series 1 complete

Note that the upgrade of machines hosting controllers is not supported and the
documented method of creating a new controller and migrating models is still
the recommended procedure.

See documentation Upgrading a machine series for details.


The charms.reactive framework also has support for allowing the charm to manage the application during the series upgrade process, which is documented in OS Series Upgrades. In summary, the behavior is as follows:

When the prepare step is invoked, the framework will set the flag, which the charm will have one (and only one) chance to react to, by at least stopping the application service for the duration of the upgrade. After this, no hooks or reactive handlers will be run until after the upgrade is complete. Once the admin has performed the series upgrade and invoked the complete step, the Python virtual environment used by the charm will be automatically rebuilt and the wheelhouse reinstalled, and then the flag will be removed, indicating that the charm should perform any necessary migrations or changes and then bring the application back up.


Nice! Thank you. I will consider linking from the documentation.

Incidentally, the command syntax provided on OS Series Upgrades needs updating. It should be

juju upgrade-series <machine> prepare <target series>
juju upgrade-series <machine> complete


Thanks for the catch! Fixed in PR #203.