Upgrading a machine series

Starting with Juju v.2.5.0, to upgrade the series of a machine, the upgrade-series command is used.

The upgrade-series command does not support upgrading a controller. An error will be emitted if you attempt to do so. See below section Upgrading a controller machine for how to do that using an alternate method.

Upgrading a workload machine

Here is an overview of the process:

  1. The user initiates the upgrade.
    1. The machine is no longer available for charm deployments or for hosting new containers.
    2. Juju prepares the machine for the upcoming OS upgrade.
    3. All units on the machine are taken into account.
  2. The user manually performs the upgrade of the operating system and makes any other necessary changes. This should be accompanied by a maintenance window managed by the user.
  3. The user informs Juju that the machine has been successfully upgraded. The machine becomes available for charm deployments.

At no time does Juju take any action to prevent the machine from servicing workload client requests.

In the examples that follow, the machine in question has an ID of '1', has one unit of 'apache2' deployed, and will be upgraded from Ubuntu 16.04 LTS (Xenial) to Ubuntu 18.04 LTS (Bionic).

Initiating the upgrade

You initiate the upgrade with the machine ID, the prepare sub-command, and the target series:

juju upgrade-series 1 prepare bionic

You will be asked to confirm the procedure. Use the -y option to avoid this prompt.

Then output will be shown, such as:

machine-1 started upgrade series from "xenial" to "bionic"
apache2/1 pre-series-upgrade hook running
apache2/1 pre-series-upgrade hook not found, skipping
machine-1 binaries and service files written

Juju is now ready for the series to be updated.
Perform any manual steps required along with "do-release-upgrade".
When ready, run the following to complete the upgrade series process:

juju upgrade-series 1 complete

All charms associated with the machine must support the target series in order for the command to complete successfully. An error will be emitted otherwise. There is a --force option available but it should be used with caution.

The deployed charms will be inspected for a 'pre-series-upgrade' hook. If such a hook exists, it will be run. In our example, such a hook was not found in the charm.

A machine in "prepare mode" will be noted as such in the output to the status (or machines) command:

Machine  State    DNS            Inst id        Series  AZ  Message
1        started  juju-573842-0  xenial      Series upgrade: prepare completed

Upgrading the operating system

One important step in upgrading the operating system is the upgrade of all software packages. To do this, log in to the machine via SSH and apply the standard do-release-upgrade command:

juju ssh 1
$ do-release-upgrade

As a resource, use the Ubuntu Server Guide. Also be sure to read the Release Notes of the target version.

Make any other required changes now, before moving on to the next step.

Completing the upgrade

You should now verify that the machine has been successfully upgraded. Once that's done, tell Juju that the machine is ready:

juju upgrade-series 1 complete

Sample output:

machine-1 complete phase started
machine-1 started unit agents after series upgrade
apache2/0 post-series-upgrade hook running
apache2/0 post-series-upgrade hook not found, skipping
machine-1 series upgrade complete

Upgrade series for machine "1" has successfully completed

Deployed charms will be inspected for a 'post-series-upgrade' hook. If such a hook exists, it will be run. In our example, such a hook was not found in the charm.

You're done. The machine is now fully upgraded and is an active Juju machine.

Upgrading a controller machine

At this time Juju does not support the series upgrade of a controller. A new controller will be needed, after which a migration of models from the old controller to the new one must be performed.

Create the new controller now. Here, we're using AWS and have called the new controller 'aws-new':

juju bootstrap aws aws-new

The controller itself will be deployed using Ubuntu 18.04 LTS (Bionic). Use option bootstrap-series to select something else.

Now migrate existing models by following the Migrating models page.

To ensure that all new machines will run the new series (like the controller, we'll use 'bionic') set the default series at the model level. For each migrated model:

juju model-config -m <model name> default-series=bionic

Destroy the old controller when done:

juju destroy-controller aws-old