See also: Deployment, Juju
3.0release notes, Upgrading things, How to upgrade a controller’s minor or major versions
This document gives the steps for how to upgrade your Juju deployment from 2.9 to 3.x.
The steps are the same across machine and Kubernetes deployment, with two exceptions:
- Ensure that your workload machines are Ubuntu
focalor later is only required for machines. - Clone your old controller configuration into the
3.xcontroller is only supported for machines.
Contents:
- Ensure your controller is at the latest patch release of
2.9 - Ensure your models are at the latest patch release of
2.9 - Ensure that your workload machines are Ubuntu
focalor later - Upgrade the client to
3.x - Bootstrap a
3.xcontroller - Clone your old controller configuration into the
3.xcontroller - Help users connect to the
3.xcontroller - Migrate your models to the
3.xcontroller - Upgrade your models to match the agent version of the
3.xcontroller
Ensure your controller is at the latest patch release of 2.9
The only way to upgrade a 2.9 controller to 3.x is to use the 3.x client to bootstrap a new 3.x controller, and then migrate your models from the old controller to the new one. Now, if your 2.9 controller’s patch version is too old, your 3.x client might not be able to talk to it. To avoid that, upgrade your controller to the latest patch version of 2.9, as below:
juju upgrade-controller <controller>
Ensure your models are at the latest patch release of 2.9
Since the only way to upgrade a 2.9 controller to 3.x is to bootstrap a new 3.x controller, the only way to connect your 2.9 models to the new controller is to migrate them to it. Now, if your model’s version is too old, the migration might be rejected. To avoid that – as well as to ensure your model has picked up all the latest bug fixes – upgrade your models to the latest patch release of 2.9, as below:
juju upgrade-model <model>
See more: How to upgrade a model
Ensure that your workload machines are Ubuntu focal or later
See also: Ubuntu Wiki | Releases
If your deployment is on Kubernetes: Skip ahead to the next step.
A 3.x controller no longer supports workload machines running on Windows or Ubuntu series older than focal. Before you begin your upgrade, make sure that all your existing or new machines comply.
If your charm doesn’t support Ubuntu focal or later, you will have to either
(a) provide a charm revision that does yourself or
(b) remove the charm from your deployment.
Make existing machines Ubuntu focal or later
If you have any Windows machines, you must remove them. If you have machines running on Ubuntu bionic (18.04) or older, you must upgrade them:
# Ask juju to take the machine out of circulation,
# in preparation for the upgrade:
juju upgrade-machine <machine number> prepare <target upgrade series>
# If you get an error that your charms don't support the target Ubuntu series,
# you will have to either
# (a) provide a charm revision that does yourself or
# (b) remove the charm from your deployment.
# SSH into the machine:
juju ssh <machine number>
# Initiate system upgrade:
do-release-upgrade
# Stand by as you'll have to confirm ('y' or ENTER) various steps.
# Ask juju to put the machine back in circulation as the upgrade is complete:
juju upgrade-machine <machine number> complete
See more: How to upgrade a workload machine
Make new machines Ubuntu focal or later
For each application in your deployment, refresh its charm to the latest revision and check if it supports Ubuntu focal or later, then set the application base to Ubuntu focal or later.
# Upgrade the charm to the latest revision, to get the latest supported bases:
juju refresh <charm>
# Check the supported bases:
juju info <charm>
# The supported bases are listed under `supports`.
# If your charm doesn't support Ubuntu focal or later, you will have to either
# (a) provide a charm revision that does yourself or
# (b) remove the charm from your deployment.
# Set the base of applications deployed from this charm to one of the supported bases:
juju set-application-base <charm> <base>
# Formerly, 'juju set-series'.
See more: How to upgrade an application
Upgrade the client to 3.x
To bootstrap a 3.x controller, you will need a 3.x client. To upgrade your client to 3.x, refresh the snap. For example, for juju v.3.1, do:
snap refresh juju --channel 3.1/stable
See more: How to upgrade
juju
While you need a 3.x client to bootstrap a 3.x controller, you can technically continue to manage a 3.x controller with a 2.9 client, at least until Juju release 3.1. On Linux, you can do that via parallel snap installs:
(a) enable the experimental parallel-install feature: sudo snap set system experimental.parallel-instances=true;
(b) reboot; and
(c) parallel-install juju 3.0: snap install --channel 3.0/stable juju_30,
where your juju_30 is your juju 3.0 client’s name.
Bootstrap a 3.x controller
Now, use the 3.x client to bootstrap a 3.x controller.
juju bootstrap <cloud> <3.x controller name>
If you’ve chosen to parallel-install a 3.0 client (instead of upgrading), run juju_30 bootstrap <cloud> <3.x controller name>. Once you’re done bootstrapping, you can continue to manage this controller with the 2.9 client (just juju instead of juju_30).
See more: How to upgrade a controller’s minor or major version
Clone your old controller configuration into the 3.x controller
If your deployment is on Kubernetes: We do not currently support cloning for Kubernetes controllers. You will have to configure the target controller manually.
Your old 2.9 controller was already configured to your liking. To retrieve all this knowledge of clouds, cloud configurations, users, user credentials, user permissions, etc., back up the old 2.9 controller and then use the stand-alone juju-restore tool to clone its configuration from the backup into the new 3.0 controller.
Create a backup of the 2.9 controller
To create a backup of the 2.9 controller model, run:
juju create-backup -m <2.9 controller>:controller
# Sample output:
# >>> ...
# >>> Downloaded to juju-backup-20221109-090646.tar.gz
See more: How to create a controller backup
Copy the configuration of the 2.9 controller into the new 3.x controller
To clone the configuration of the 2.9 controller into the 3.x controller, you must download the stand-alone juju-restore tool, switch to the 3.x controller, copy this along with the 2.9 controller backup file to the primary controller machine, and then run ./juju-restore with the --copy-controller command:
# Download the latest release binary (Linux, AMD64):
wget https://github.com/juju/juju-restore/releases/latest/download/juju-restore
chmod +x juju-restore
# Switch to the controller model:
juju switch controller
# Copy juju-restore to the primary controller machine:
juju scp juju-restore 0:
# Copy the backup file to the primary controller machine:
juju scp <path-to-backup> 0:
# SSH into the primary controller machine:
juju ssh 0
# Start the restore with the '--copy-controller' flag:
./juju-restore --copy-controller <path-to-backup>
# Congratulations, your 2.9.37+ controller config has been cloned into your 3.0 controller.
Help users connect to the 3.x controller
Your 2.9 controller likely had other users connected to it. To help these users connect to the new 3.x controller, reset their password from the new controller and send them the new registration string. Then they’ll be able register the new 3.0 controller on their client.
# Make sure you're on the 3.x controller:
juju switch <3.x controller name>
# Reset the users' password:
juju change-user-password <user> --reset
# >>> Password for "bob" has been reset.
# >>> Ask the user to run:
# >>> juju register
# >>> MEcTA2JvYjAWExQxMC4xMzYuMTM2LjIxNToxNzA3MAQgJCOhZjyTflOmFjl-mTx__qkvr3bAN4HAm7nxWssNDwETBnRlc3QyOQAA
# When they use this registration string, they will be prompted to create a login for the new controller.
See more: How to manage users
Migrate your models to the 3.x controller
To migrate your 2.9.x models to the 3.x controller, run:
juju migrate <model> <3.x controller>
See more: How to migrate a workload model to another controller
Upgrade your models to match the agent version of the 3.x controller
To upgrade your migrated models to match the agent version of the 3.x controller, run:
# Find out the exact current version of the controller by inspecting the output of
# 'juju status' or 'juju show-controller <3.x controller>'.
# Upgrade the model to that version:
juju upgrade-model <model> --agent-version=<the version of the 3.x controller>
See more: How to upgrade a model
Congratulations, you have upgraded your deployment to 3.x!
Contributors: @wallyworld