See also: Model
- Add a model
- View all the models available on a controller
- Switch to a different model
- View the status of a model
- View details about a model
- Configure a model
- Manage machine constraints for a model
- Restrict commands on a model
- Upgrade a model
- Migrate a workload model to another controller
- Destroy a model
Add a model
To add a model to the current controller using the default credential and switch to this model, run the
add-model command followed by the name of the model. For example:
juju add-model mymodel
You can also pass various options to choose a different controller or credential, specify a configuration, designate a different model
owner, not switch to the newly create model, etc.
If you have multiple credentials: Be careful which one you use for the new model. Any machines subsequently on the model will be associated with this credential. As such, make sure you’re not spending resources for the wrong cloud account!
View all the models available on a controller
To get a list of all the models in the current controller, use the
The current model will be denoted with an asterisk.
Expand to see a sample output
Controller: localhost-localhost Model Cloud/Region Type Status Machines Units Access Last connection controller localhost/localhost lxd available 1 1 admin 1 minute ago prod* localhost/localhost lxd available 0 - admin never connected test localhost/localhost lxd available 0 - admin 2 minutes ago
By passing various options you can filter by controller, get a time stamp, output to a specific format, etc.
Switch to a different model
Identify the current model. To identify the current model, run the
switch command with no arguments:
This will show the current controller, user, and model in a
Expand to see a sample output
You can also identify the current model by running
juju models – your current model is the model with an asterisk!
Switch to a different model. To change from the current model to a different model, use the
switch command followed by the target model name in a
juju switch <controller>:<admin>/<model>
The command also allows you to specify the target controller in an abbreviated form by omitting one or more of the components.
For important operations we recommend you specify the model in the unambiguous form shown above.
View the status of a model
To see the status of a model and everything inside of it, run the
Expand to see a sample output
Model Controller Cloud/Region Version SLA Timestamp test localhost-localhost localhost/localhost 3.1.0 unsupported 16:07:52+01:00 Model "admin/test" is empty.
By passing various options you can also specify a model, see the output in color formatting or with additional sections for relations or storage, watch the status for a given duration, etc.
View details about a model
To view detailed information about a specific model, use the
show-model command followed by the model name. For example:
juju show-model test
Expand to see a sample output for an empty model called 'test'
test: name: admin/test short-name: test model-uuid: 3850c8cc-0cd0-4d53-8a6d-591b63024141 model-type: iaas controller-uuid: f06afa86-3461-42bb-86ed-6c2f5d7b0ac7 controller-name: localhost-localhost is-controller: false owner: admin cloud: localhost region: localhost type: lxd life: alive status: current: available since: 5 hours ago users: admin: display-name: admin access: admin last-connection: 2 minutes ago sla: unsupported agent-version: 3.1.0 credential: name: localhost owner: admin cloud: localhost validity-check: valid supported-features: - name: juju description: the version of Juju used by the model version: 3.1.0
By passing options you can also specify a format, an output file, etc.
Configure a model
See also: Configuration, List of model configuration keys
The procedure for how to configure a model differs slightly depending on whether you are interested in the configuration of a specific model or rather of all the models on a controller.
A specific model
Set values. You can set the configuration for a model both while you are creating the model and later.
- To set it for the
controllermodel during control creation, use the
bootstrapcommand with the
--configoption followed by the desired configuration, for example:
juju bootstrap --config image-stream=daily localhost lxd-daily
- To set it for any other (workload) model while creating it, use the
add-modelcommand with the
--configflag followed by the desired configuration:
juju add-model mymodel --config image-stream=daily
- To set it for any model – whether
controlleror otherwise – after the model has already been created, use the
model-configcommand followed by the desired configuration, for example:
juju model-config no-proxy=jujucharms.com
Juju does not currently check that the provided key is a valid setting, so make sure you spell it correctly.
In all cases, the configuration can be passed in the form of a space-separated list of key-value pairs or in the form of a YAML configuration file, and you can also use it to overwrite (e.g., with a null value) or to reset existing values, among other things.
If you’re trying to pass multiple configurations using the
--config flag, make sure to repeat the flag for every configuration.
juju bootstrap --config ...,
juju add-model ... --config,
Get values. You can get the configuration of a model at any time by running the
model-config command without any argument, as below:
By using various flags of this command you can also target a specific model or key, choose a different output format, etc.
All the models on a controller
Set values. You can set the default configuration values for all the models on a controller either during controller creation or after.
- To set model configuration defaults during controller creation, use the
bootstrapcommand with the
--model-defaultsflag followed by the desired configuration(s), for example, as below. This will affect the
controllermodel and any subsequent (workload) model during controller creation.
juju bootstrap microk8s uk8s \ --model-defaults logging-config="<root>=WARNING; unit=DEBUG" \ --model-defaults update-status-hook-interval="60m"
By passing various flags you can also target a specific cloud or cloud region, pass the configuration(s) in the form of a yaml file, reset keys, etc.
juju bootstrap --model-defaults ...
- To set model configuration defaults after controller creation, use the
model-defaultscommand followed by the desired configuration. This willl affect any models created from that point onwards.
juju model-defaults ftp-proxy=10.0.0.1:8000
These defaults can be overridden, on a per-model basis, during the invocation of the
add-model command (option
--config) as well as by resetting specific options to their original defaults through the use of the
model-config command (option
Get values. At any point, you can get the default configuration values for all the models on a controller by running the
model-defaults command, as below:
Just as before, by using various flags you can filter by a specific cloud or cloud region, or see the value for a specific key, etc.
Manage machine constraints for a model
See also: Constraint
Set values. You can set machine constraints for the
controller model during controller creation or to regular models at any other point.
To set constraints for just the controller machines in the
controller model: Use the
bootstrap command with the
--bootstrap-constraints flag. See more: How to manage constraints for a controller.
- To apply a constraint to all the machines in the
controllermodel (that is, to both controller and non-controller machines, if present) during controller creation, run the
bootstrapcommand with the
--constraintsoption. Below we use it to ensure that every machine has 4GiB memory.
juju bootstrap --constraints mem=4G aws
juju bootstrap --constraints
- To set constraints for a model, run the
set-model-constraintscommand followed by the desired key-value pair, as in the example below. This will affect any new machines in the model.
juju set-model-constraints mem=4G
Pro tip: To reset a constraint key to its default value, run the command with the value part empty (e.g.,
juju set-model-constraints mem= ).
Get values. To view machine constraints for a model, run the
model-constraints command, as below:
By using various flags, you can specify a model (e.g.,
-m controller, to view constraints for the controller model), an output file, etc.
Restrict commands on a model
Disable commands. To disable commands for the current model, run the
disable-command followed by the name of the command group that you want to restrict and, optionally, a message. For example, the code below disables the ability to destroy the model and its controller:
juju disable-command destroy-model ""Check with SA before destruction.""
View a list of the disabled commands. To see which command groups have been disabled for a model, run the
Enable commands. To lift command restrictions, run
enable-command followed by the command group that you want to enable. For example, the code below re-allows people to destroy the model and its controller.
juju enable-command destroy-model
Upgrade a model
juju upgrade-model, Upgrading things
A model upgrade affects the version of Juju (Juju machine and unit agents) on all the Juju machines in the model.
First, prepare for the upgrade:
- Ensure the controller has already been upgraded. See more: How to upgrade a controller
- Ensure the models that are to be upgraded are in good working order (
Then, perform the upgrade. How you upgrade a model depends on whether you’d be crossing patch versions (e.g.,
v.2.9.26) or rather minor (e.g.,
v.2.8) or major versions (
- To upgrade the current model across patch versions, use the
By using various flags, you can specify an agent stream, agent version, etc., or you can even perform a dry run, to simulate what would happen if you upgraded.
This procedure can also be used to upgrade a controller model.
- To upgrade a model across minor or major versions, use model migration.
This procedure cannot be used to upgrade a controller model.
See more: How to migrate a workload model to another controller
When you’re done, verify that the model has been succesful by running the
status command. If the output looks wrong, you will have to do some investigation.
See more: How to troubleshoot a model upgrade
Migrate a workload model to another controller
Model migration is the movement of a model from one controller to another. The same configuration of machines, units, and their relations will be replicated on the destination controller, while your applications continue uninterrupted. Migration is used to upgrade models across minor or major versions. Migration is also useful for load balancing: If a controller hosting multiple models reaches capacity, you can move the busiest models to a new controller, reducing load without affecting your applications.
A controller model cannot be migrated.
Prepare for migration.
- Verify that the source and destination controllers are both known to the Juju client (i.e., they show up in the
juju controllersoutput) and located in the same cloud environment.
- Verify that the version of Juju running on the destination controller is the same or newer than the version on the source controller.
- Verify that the destination controller does not have any model with the same name as the name of the model you want to migrate to it.
- Back up the source controller.
- If the destination controller is on a different region or VPC: Ensure that the destination controller has direct connectivity to the source controller.
- If the model is large: Configure the destination controller to throttle the reconnection rate for the agents running for each machine and unit in the model and increase the migration agent timeout time. For example:
juju controller-config agent-ratelimit-rate=50ms juju controller-config agent-ratelimit-max=100 juju controller-config migration-agent-wait-time=30m
- If the model has multiple users: Ensure that all the users have been set up on the destination controller. The operation will be aborted, and an advisory message displayed, if this is not the case.
If the model contains secrets: Set up the target controller to use the same secret bank end as the source controller. For example, for a backend called
myvault, as below. This will ensure that any secrets are correctly migrated with the model.
$ juju switch sourcecontroller $ juju show-secret-backend myvault myvault: backend: vault config: endpoint: http://10.0.0.77:8200 secrets: 0 status: active id: 63c8ad37c906eb278540e942 $ juju switch targetcontroller $ juju add-secret-backend --config /path/to/backendcfg.yaml --import-id 63c8ad37c906eb278540e942
Migrate the model. To migrate a model on the current controller to a destination controller, use the
migrate command followed by the name of the model and the name of the destination controller, as below:
juju migrate <model> <destination controller>
You can monitor progress from the output of the
status command run against the source model. You may want to use a command such as
watch to automatically refresh the status output, rather than manually running status each time:
watch --color -n 1 juju status --color
In the output, a ‘Notes’ column is appended to the model overview line at the top of the output. The migration will step through various states, from ‘starting’ to ‘successful’.
The ‘status’ section in the output from the
show-model command also includes details on the current or most recently run migration. It adds extra information too, such as the migration start time, and is a good place to start if you need to determine why a migration has failed.
This section will look similar to the following after starting a migration:
status: current: available since: 23 hours ago migration: uploading model binaries into destination controller migration-start: 21 seconds ago
Migration time depends on the complexity of the model, the resources it uses, and the capabilities of the backing cloud.
If failure occurs during the migration process, the model, in its original state, will be reverted to the original controller.
When the migration has completed successfully, the model will no longer reside on the source controller. It, and its applications, machines and units, will be running on the destination controller.
Inspect the migrated model with the
juju status -m <destination-controller>:<model>
Destroy a model
juju destroy-model, Removing things
To remove a model, along with any associated machines and applications, use the
destroy-model command followed by the name of the model:
juju destroy-model <model>
The command has a variety of flags that you can use to skip the confirmation, to rush through the destruction without waiting for each step to complete, to release or destroy any persistant storage on the model, etc., or even to force destroy the model, ignoring any errors (not recommended as it might leave behind unresolved issues).