See also: Juju Roadmap & Releases
This document shows how to upgrade your deployment – the general logic and order, whether you upgrade in whole or in part, whether you are on Kubernetes or machines.
You can usually also update the various components (client, controller and model agents, machines, charms) separately. However, make sure to check the controller - model - client compatibility matrix. Also be aware that Juju 3 no longer supports workload machines running on Windows or Ubuntu series older than focal. Finally, some charms may require a specific minimum Juju version to work correctly – make sure to visit their page on Charmhub.
See more: Upgrading things, Juju version compatibility matrix
Contents:
- Upgrade your client
- Upgrade your controller
- Upgrade your models
- (If on a machine cloud:) Upgrade your machines
- Upgrade your charms
Upgrade your client
To upgrade your client, refresh its snap to the desired target channel. For example:
snap refresh juju --channel 3/stable
Upgrade your controller
The procedure depends on whether you’re upgrading your controller’s patch version (e.g. 2.9.25 → 2.9.48) or rather its minor or major version (e.g. 2.9 → 3.0 or 3.1 → 3.4).
Upgrade your controller’s patch version
To upgrade your controller’s patch version, on the target controller, use the juju upgrade-controller command with the --agent-version flag followed by the desired patch version (of the same major and minor):
juju upgrade-controller --agent-version <current major. current minor.target patch>
For example, assuming a controller version 3.0.0, to upgrade to 3.0.2:
juju upgrade-controller --agent-version 3.0.2
Upgrade your controller’s minor or major versions
To upgrade your controller’s minor or major version:
- Upgrade your controller to the latest patch version.
See above.
(This is to ensure a successful model migration – something that will make sense in the next, model upgrade step.)
- Use an upgraded client to bootstrap a new controller:
juju bootstrap <cloud> <new controller's name>
- Clone your old controller’s configuration into the new controller.
We do not currently support this procedure for Kubernetes controllers. You will have to configure the target controller manually.
# Create a backup of the old controller
# and make note of the path to the backup file:
juju create-backup -m <old controller model>:controller
# Sample output:
# >>> ...
# >>> Downloaded to juju-backup-20221109-090646.tar.gz
# Download the stand-alone juju-restore tool:
wget https://github.com/juju/juju-restore/releases/latest/download/juju-restore
chmod +x juju-restore
# Switch to the new controller's controller model:
juju switch controller
# Copy the juju-restore tool 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 <old version> controller config has been cloned into your <new version> controller.
See more: How to manage controllers > Back up
- Help users connect to the new controller.
# Make sure you're on the new controller:
juju switch <new controller name>
# Reset the users' password:
juju change-user-password <user> --reset
# >>> Password for "<user>" 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 > Manage a user’s login details
Upgrade your models
Upgrade your models’ patch version
To upgrade your workload models’ patch version, for each model, run:
juju upgrade-model <model>
See more: How to manage models > Upgrade
Upgrade your models’ minor or major version
To upgrade your models’ minor or major version, for each model:
- Upgrade the model’s patch version to the latest patch version of the old minor.
juju upgrade-model <model>
(This is to ensure a successful model migration – something that will make sense in the immediately next step.)
- Migrate the model from the old controller to the new controller.
# On the old controller, run:
juju migrate <model> <new controller>
- Upgrade the model to the exact current version of the new controller.
# 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 manage models > Upgrade
(If on a machine cloud:) Upgrade your machines
See also: Ubuntu Wiki | Releases
- Upgrade existing machines to the desired base.
See more: How to upgrade a workload machine
2.Ensure that any newly provisioned machines will be of the desired base.
# 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 your charms
To upgrade a charm, refresh it to the desired channel or revision or resource etc. For example:
juju refresh <charm> --channel <track/risk>
See more: How to update a charm
Contributors: @massigori, @tmihoc, @wallyworld