How to upgrade a model

[system]

See also: Upgrading things, Model

This document demonstrates how to upgrade a model. A model upgrade acts on all the machine and unit agents running on all the machines in the model.

Notes:

• Upgrades must be applied to the ‘controller’ model before upgrading other models. An error will be emitted if this is not done.
• By default, the latest stable version will be selected.
• Juju machines request the new agent software from the controller. If the latter’s cache cannot satisfy the request, the controller will attempt a download from the internet.
• A controller admin can upgrade any model within that controller.
• A model owner can upgrade that model.

See Notes on upgrading Juju software for upgrading details, including what to do when the controller lacks internet access.

Contents:

• Prepare for a model upgrade
• Perform a model upgrade
• Verify a model upgrade
• Troubleshoot a model upgrade

Prepare for a model upgrade

Some pre-upgrade tasks that should be considered:

• Perform a backup (see How to back up a controller).
• Ensure the models that are to be upgraded are in good working order by applying the status command to them.
• See what version is currently running with juju model-config agent-version or juju status.

Perform a model upgrade

This section contains examples on upgrading a model, starting with the ‘controller’ model.

To upgrade the ‘controller’ model for the ‘aws’ controller with the latest stable version:

juju upgrade-controller -c aws

To upgrade the current model by specifying the version:

juju upgrade-model --agent-version 2.4.1

To upgrade the current model by specifying the agent stream:

juju upgrade-model --agent-stream proposed

Verify a model upgrade

To verify that the upgrade has been successful, run the status command. Assuming we have a controller called aws, our controller model has the default name controller, and we want to verify an upgrade to the controller model, we can do this as below:

juju status -m aws:controller

If this command does not complete properly or if there are errors displayed in its output then proceed to the next section.

Troubleshoot a model upgrade

A model upgrade that does not lead to 100% success will require attention. See Troubleshooting model upgrades.

[camille.rodriguez1 (Camille Rodriguez)]

What about upgrading the controller ? If I upgrade the controller, will it automatically upgrade the juju version in all the models too ?

[pmatulis (Peter Matulis)]

The newish upgrade-controller command upgrades model ‘controller’. You need to upgrade other models with the upgrade-model command, on a per model basis. The controller model needs to be upgraded first I’m pretty sure.

[heitor]

Are there any compatibility issues if the controller version is newer than the other models?

[hmlanigan (Heather Lanigan)]

There should be compatibility issues in this case, due to api versioning. If one is found, please file a bug.