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

See: How to upgrade the Ubuntu series of a machine

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

See also: How to restore a controller from a backup

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.

Help improve this document in the forum.