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.

Last updated 18 days ago.