How to manage models

See also: Model

Contents:

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.

See more: juju add-model

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 models command:

juju models

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.

See more: juju models

Switch to a different model

Identify the current model. To identify the current model, run the switch command with no arguments:

juju switch

This will show the current controller, user, and model in a <controller>:<user>/<model> format.

Expand to see a sample output
localhost-localhost:admin/test

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 <controller>:<user>/<model> format:

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.

See more: juju switch

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 status command:

juju status
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.

See more: juju status

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.

See more: juju show-model

Configure a model

See also: Model 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 controller model during control creation, use the bootstrap command with the --config option 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-model command with the --config flag followed by the desired configuration:
juju add-model mymodel --config image-stream=daily
  • To set it for any model – whether controller or otherwise – after the model has already been created, use the model-config command 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.

See more: juju bootstrap --config ..., juju add-model ... --config, juju 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:

juju model-config

By using various flags of this command you can also target a specific model or key, choose a different output format, etc.

See more: juju model-config

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 bootstrap command with the --model-defaults flag followed by the desired configuration(s), for example, as below. This will affect the controller model 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.

See more: juju bootstrap --model-defaults ...

  • To set model configuration defaults after controller creation, use the model-defaults command 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 --reset).

See more: juju model-defaults

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:

juju model-defaults

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.

See more: juju model-defaults

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 controller model (that is, to both controller and non-controller machines, if present) during controller creation, run the bootstrap command with the --constraints option. Below we use it to ensure that every machine has 4GiB memory.
juju bootstrap --constraints mem=4G aws

See more: juju bootstrap --constraints

  • To set constraints for a model, run the set-model-constraints command 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= ).

See more: juju set-model-constraints

Get values. To view machine constraints for a model, run the model-constraints command, as below:

juju model-constraints

By using various flags, you can specify a model (e.g., -m controller, to view constraints for the controller model), an output file, etc.

See more: juju model-constraints

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

See more: juju disable-command

View a list of the disabled commands. To see which command groups have been disabled for a model, run the disabled-commands command:

 juju disabled-commands

See more: juju disabled-commands

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

See more: juju enable-command

Upgrade a model

See more: 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 (juju status).

Then, perform the upgrade. How you upgrade a model depends on whether you’d be crossing patch versions (e.g., v.2.9.25v.2.9.26) or rather minor (e.g., v.2.7v.2.8) or major versions (v.2v.3).

  • To upgrade the current model across patch versions, use the upgrade-model command:
juju upgrade-model

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.

See more: juju upgrade-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

Are you upgrading from Juju 2.9 to 3.x? See How to upgrade your deployment from 2.9 to 3.x.

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 controllers output) 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

See more: List of controller configuration keys > agent-ratelimit-rate, agent-ratelimit-max, migration-agent-wait-time

  • 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 status command:

juju status -m <destination-controller>:<model>

See more: juju migrate

Destroy a model

See also: 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).

See more: juju destroy-model

Add a model

To add a model, create a resource of the juju_model type with your desired resource label and a model name. For example, below we create a model called machinetest backed a Terraform resource labelled testmodel.

resource "juju_model" "testmodel" {
  name = "machinetest"
}

See more: Terraform Provider Juju | juju_model (resource)

Migrate a model to another controller

  1. Perform the model migration with the Juju CLI:

See: juju CLI | How to migrate a workload model to another controller

  1. Reconfigure your Terraform client’s juju provider to point to the destination controller.

See more: How to manage the client > Configure the client’s juju provider


Contributors: @hmlanigan, @pedroleaoc, @pmatulis, @serdarvural80, @timclicks, @tmihoc

Add a model

A Juju controller provides websocket endpoints for itself and each of its models. In order to do anything useful, the juju lib must connect to one of these endpoints.

Connecting to the controller endpoint is useful if you want to programmatically create a new model. If the model you want to use already exists, you can connect directly to it (see Models).

Connect to the currently active Juju controller:

from juju.controller import Controller

controller = Controller()
await controller.connect()

With this controller object, you can call add_model to create your model:

await controller.add_model("test-model")

See more: Python-libjuju Controller.add_model(), juju_model (module), juju_controller (model)


View all the models available on a controller

With a connected controller object, you can call Controller.list_models() function to list all the available models to work with:

await controller.list_models()

See more: Controller.list_models(),


Switch to a different model

In python-libjuju, switching to a different model means simply connecting to the model you want to work with. You can either disconnect() your Model object, or create a new one to connect to whichever model you want to use:

from juju.model import Model

model = Model()
await model.connect() # will connect to the "current" model

await model.connect(model_name="test-model") # will connect to the model named "test-model"

See more: Model.connect(),


Destroy a model

With a connected controller object, you can call Controller.destroy_model() function to remove any models you have permissions to administrate:

await controller.destroy_model("test-model")

See more: Controller.destroy_model()


Last updated 2 days ago. Help improve this document in the forum.