How to upgrade a model

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.


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


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.


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

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.

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

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