Upgrading a machine’s series affects the series (release) of the underlying operating system of a Juju machine, including a controller.
Upgrading the operating system running on each of the machines is a multi-step process. Each of the machines’ operating systems must be upgraded, then each of the charms.
- Upgrading a model’s series
- Upgrading an application’s series
- Upgrading a workload machine
- Upgrading a controller machine
To upgrade an existing model’s series (so that any new additional deployment gets the new series), you need to change the
default-series of the model.
juju model-config -m <model> default-series=<series>
Juju uses the term “series” to refer to the OS release. Ubuntu OS releases are currently referred to via their codenames, whilst other OS (Windows, Centos and MacOS) use their official names.
To upgrade an application’s series, Juju first needs to upgrade each individual machine hosting the application units. Likewise, to upgrade a model’s series, you first need to perform the upgrade steps on each of its machines.
Upgrade-series allows users to perform a managed upgrade of the underlying operating system of the machine. The upgrade is broken down into two steps: prepare and complete.
Upgrading a machine is a manual process and the commands notify Juju about the step at which the upgrade is.
The “prepare” step notifies Juju that a series upgrade is taking place for a given machine and as such Juju guards that machine against operations that would interfere with the upgrade process.
The “complete” step notifies Juju that the managed upgrade has been successfully completed.
Once the prepare command is issued, there is no way to cancel or abort the process. Once you commit to prepare, you must complete the process; otherwise you will end up with an unusable machine!
An overview of the series upgrade process:
- The user initiates the upgrade.
- The machine is no longer available for charm deployments or for hosting new containers.
- Juju prepares the machine for the upcoming OS upgrade.
- All units on the machine are taken into account.
- 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.
- 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.
If your application relies on maintaining a quorum of a minimum number of nodes, add more units before running
$ juju add-model testing $ juju deploy rabbitmq-server -n 3 --series xenial $ juju config rabbitmq-server min-cluster-size=3
As RabbitMQ will cease to function if one of its nodes becomes unavailable due to an upgrade, we can temporarily add more capacity:
$ juju add-unit -n 2 rabbitmq-server
Now we indicate to Juju that we’re intending on upgrading the series of the machines.
$ juju upgrade-series 0 prepare bionic WARNING: This command will mark machine "0" as being upgraded to series "bionic". This operation cannot be reverted or canceled once started. Units running on the machine will also be upgraded. These units include: rabbitmq-server/0 Leadership for the following applications will be pinned and not subject to change until the "complete" command is run: rabbitmq-server Continue [y/N]? y
y at this point initiates the upgrade process.
machine-0 started upgrade series from "xenial" to "bionic" rabbitmq-server/0 pre-series-upgrade hook running rabbitmq-server/0 pre-series-upgrade completed machine-0 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 0 complete
One important step in upgrading the operating system is the upgrade of all software packages. To do this on Ubuntu-based machines, log in to the machine via SSH and execute the
juju ssh 0 $ do-release-upgrade
This step typically requires interaction. The upgrade process may need assistance to indicate how to handle changed configuration files, for example.
Juju now needs to run the “complete” phase of the
upgrade-series command. This gives charms the chance to execute any code that they need to when the operating system changes.
juju upgrade-series 0 complete
Upgrade the series of any other machines. In this example, machines
2 require upgrading.
If necessary, remove any units created to maintain a quorum should be removed:
juju remove-unit rabbitmq-server/3 juju remove-unit rabbitmq-server/4
To upgrade the series of a controller, create a new controller using the preferred series, then migrate to it and delete the old controller:
Create the new controller with the
juju bootstrap command. Here, we’re using AWS and have called the new controller ‘aws-new’:
juju bootstrap aws aws-new --bootstrap-series=<series>
Now migrate your existing models by following the How to migrate a model 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=<series>
Destroy the old controller when done:
juju destroy-controller aws-old