How to upgrade your deployment

doc
1

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:

  1. Upgrade your client
  2. Upgrade your controller
  3. Upgrade your models
  4. (If on a machine cloud:) Upgrade your machines
  5. 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

See: How to install and manage the client > Upgrade

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, run:

juju upgrade-controller <controller>

See more: How to upgrade a controller’s patch version

Upgrade your controller’s minor or major versions

To upgrade your controller’s minor or major version:

  1. Upgrade your controller to the latest patch version.
juju upgrade-controller <controller>

(This is to ensure a successful model migration – something that will make sense in the next, model upgrade step.)

  1. Use an upgraded client to bootstrap a new controller:
juju bootstrap <cloud> <new controller's name>
  1. Clone your old controller’s configuration into the new controller.
If your deployment is on Kubernetes:

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

  1. 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:

  1. 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.)

  1. Migrate the model from the old controller to the new controller.
# On the old controller, run:
juju migrate <model> <new controller>
  1. 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

  1. 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

2
3
4

–agent-version=3.0.0 or the like is required here, otherwise the upgrade won’t find it - it’ll be looking for newer versions of 2.9 by default.

1 Like
5

Updated, thanks! (I had this in an earlier version of the doc and then lost it somehow.)

6

Its mentioned a tool here “the stand-alone juju-restore tool” but there is no link to it which makes the documentation somewhat incomplete.

I’ll try find it.

7

Thanks for catching this, @erik-lonroth, I’ve added a link now. It’s this one here: https://github.com/juju/juju-restore

1 Like
8

This page is titled “from 2.9 to 3.x” but it seems you can’t actually easily upgrade from 2.9 to 3.1. This is maybe alluded to with the note of

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 ."

If you switch to 3.1, bootstrap a controller, once you switch back to the 2.9.42 controller it won’t connect so you have to downgrade back to the 2.9 client at least.

If the intended path is truly 2.9->3.0->3.1 then the page should be updated to reflect that explicitly, especially now that 3.1 is out.

1 Like
9

Hi @lathiat, thanks for your feedback. Insofar as I know, you should be able to upgrade from 2.9.x to 3.1 in one step. But I will double-check.

10

Hi,

after spinning a new 3.1 controller and importing all data from a 2.9.42 controller i cannot import models into the new controller.

infact when i issue a migrate command the migration starts but than hangs saying (json output):

“model-status”: { “current”: “available”, “message”: “migrating: aborted, removing model from target controller: model data transfer failed, failed to import model into target controller: remote-applications: version 3 not valid (not val id)”, “since”: “14 Apr 2023 17:24:57+02:00” },

what am i missing?

11

forgot to add: i’m using juju 2.9 client as when trying to use the 3.1 version it stops immediately

ERROR juju client with major version 3 used with a controller having major version 2 not supported

update your juju client to match the version running on the controller

12

There are some migration issues with importing to juju 3.1.0 which are fixed in the current 3.1 candidate. We’ll have to see if this is one of them. I don’t have a release date, but soon.

1 Like
13

The other thing would be nice to have in this guide are steps to get the current model in a clean state. Particularly, I have seen cases where the user needs to run mongo purge before re-trying a failed migration, and increasing agent-ratelimit-max that always make model migrations to fail.

14

The See more: How to upgrade a model link points to a archived link, which I was able to seen only after login. I believe the new link is How to manage models

1 Like
15

Fixed, thanks!

1 Like
16

Step 4 says to upgrade juju client to 3.x but then juju create-backup fails

juju create-backup -m ...
ERROR juju client with version 3.1 used with a controller having major version 2 not supported
re-install your juju client to match the version running on the controller

Another thing is backing up container controller

$ juju create-backup -m ...
ERROR Juju command "create-backup" not supported on container controllers

There is a note saying If your deployment is on Kubernetes: You will have to replicate this logic manually. but no details, like what to backup.

17

Hello @tmihoc,

Could you help us to solve how to backup for if the deployment is on K8s?

Many thanks.

18

Hi @marosg & @amo-mycena,

We currently don’t support backups on Kubernetes. There is a bit of enablement work we need to do to have this supported. At the moment we don’t advertise Kubernetes controllers as a production support Juju because of this and our ability to not provide HA.

The steps above for manually cloning a controller is different and not a backup. The steps involved logging into the Mongo database container and exporting several collections and then importing these into the new Database.

I will have a talk with @wallyworld and we will get these written in a formal manner for someone to follow.

1 Like
19

Hi,

It is great now that we have the Juju roadmap and release schedule, but I think some extra clarity would be great regarding upgrade paths now that we have some more minor versions, and 3.5 (LTS) is soon to be released, so I’m basically getting back to the question from @lathiat one year ago.

It is clear that minor versions (3.1->3.2, 3.2->3.3 and so on) can’t be carried out without model migration, but when migrating from 2.9 to 3.latest with as few migrations as possible, can we expect LTS->LTS to work, i.e. 2.9->3.5 directly or will certain stops in between be required?

Thanks in advance!

20

Hi @hallback , this doc might help: https://juju.is/docs/juju/juju-version-compatibility-matrix Do let me know if if it still has issues (e.g., missing info or unclear) and I’ll work to improve it.

1 Like