Upgrading the operating system running on each of the machines is a multi-step process. Each of the operating systems must be upgraded, then each of the charms. We use the term “series” to refer to the OS version code listed by juju status.
Page contents
- Upgrading an application’s series or a model’s series
- Upgrading a machine’s series
- Upgrading the controller’s series
Upgrading an application's series or a model's series
To upgrade an application’s series, upgrade each the machines hosting its units. Every machine needs to be upgraded individually. Likewise, to upgrade a model’s series, perform the upgrade steps on each of its machines.
Update the model’s configuration to prefer the new series for newly-deployed charms:
juju model-config -m <model> default-series=<series>
Upgrading a machine's series
An overview of the series upgrade process:
- For each machine
m:
– Executejuju upgrade-series <m> prepare <new-series>
– Upgrade the operating system. For Ubuntu-based machines, this involves executingdo-upgrade-series
– Executejuju upgrade-series <m> complete
Clustered application?:
If your application relies on maintaining a quorum of a minimum number of nodes, add more units before running juju upgrade-series.
Let’s start with a base model that deploys AMQP implementation RabbitMQ with the rabbitmq-server charm.
$ juju add-model testing
$ juju deploy rabbitmq-server -n 3 --series xenial
$ juju config rabbitmq-server min-cluster-size=3
Preparation
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
Initiate upgrade series
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
Answering 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
Upgrading the operating system
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 do-release-upgrade command:
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.
Mark the series upgrade as complete
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
Repeat steps for other machines
Upgrade the series of any other machines. In this example, machines 1 and 2 require upgrading.
Remove any units needed for upgrade
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
Upgrading a controller machine
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 a new 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>
Migrate models to the new controller
Now migrate your 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=<series>
Destroy the old controller
Destroy the old controller when done:
juju destroy-controller aws-old