How to upgrade your Juju deployment from 2.9 to 3.x
See also: Juju
3.0
release notes, Upgrading things, How to upgrade a controller across minor or major versions
This document gives the steps for how to upgrade your Juju deployment from 2.9
to 3.x
.
Contents:
- Ensure that your models are
2.9.37
or greater - Ensure that your workload machines are Ubuntu
focal
or later - Upgrade the client to
3.x
- Bootstrap a
3.x
controller - Clone your old controller configuration into the
3.x
controller - Help users connect to the
3.x
controller - Migrate your models to the
3.x
controller - Upgrade your models to match the agent version of the
3.x
controller
Ensure that your models are 2.9.37
or greater
See also: How to upgrade a model
The only way to upgrade a 2.9
controller to 3.x
is to bootstrap a new 3.x
controller. This means that the only way to connect your 2.9
models to it is to migrate them to the 3.x
controller. Now, the migration path is set such that your models must already be 2.9.37
or later. Thus, before you begin, make sure that your model is at least 2.9.37
by running the code below:
juju upgrade-model <model>
Ensure that your workload machines are Ubuntu focal
or later
See also: Ubuntu Wiki | Releases
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 machines comply, by removing any Windows machines or upgrading any Ubuntu machines to focal
or later, and also that any new machines will comply as well, by making sure that the charms in your deployment support Ubuntu focal
or later and, for all the applications deployed by them, setting the application base to Ubuntu focal
or later.
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
Make new machines Ubuntu focal
or later
See also: How to upgrade an application’s charm
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'.
Upgrade the client to 3.x
See: How to upgrade
juju
To bootstrap a 3.x
controller, you will need a 3.x
client. To upgrade your client to 3.x
, do:
snap refresh juju --channel 3.0/stable
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
See also: How to create a 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
).
Clone your old controller configuration into the 3.x
controller
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.
The procedure documented below is currently supported only for machine (non-Kubernetes) controllers.
Create a backup of the 2.9
controller
See also: How to create a controller backup
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
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
See also: How to manage users
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.
Migrate your models to the 3.x
controller
See also: How to migrate a model
To migrate your 2.9.37+
models to the 3.x
controller, run:
juju migrate <model> <3.x controller>
Upgrade your models to match the agent version of the 3.x
controller
See also: How to upgrade a model
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>
Congratulations, you have upgraded your deployment to 3.x
!
Last updated 21 days ago.