Manage models

Migrate a model to JAAS

This section describes how to migrate a model to JAAS from an existing Juju controller.

Prerequisites

• A standalone Juju controller with a model (optionally with a running application).

• A basic understanding of Juju model migrations, see the docs .

• A running JAAS, see the the tutorial.

• Administrator permissions for JAAS, see our how-to.

1. Create a new Juju controller

This is only necessary if you have a Juju controller that does not have the login-token-refresh-url config option set to point to JIMM. Use the following command to check if your controller is already using JAAS.

juju switch <controller-name>
juju controller-config login-token-refresh-url

If the value is empty, we must first bootstrap a new Juju controller.

In order to use models with JAAS, the models must be running on a Juju controller that is properly configured. The necessary config values cannot be set after bootstrap time, so any existing models must be migrated to a new controller.

The process of creating a Juju controller that is properly configured is described in Add a Juju controller.

Once a Juju controller configured to communicate with JAAS has been created, move onto the next step.

2. Create user mapping file

When migrating a model to JAAS, local users are replaced with external users.

What this means is clearer if we take a look at a model’s full name with juju show-model. The full model name is <model-owner>/<model-name> where <model-owner> represents a Juju user like “admin”. In order to migrate a model to JAAS, we must create a yaml file where we provide a mapping of local users to external users (users that come from an identity provider). This is important for 2 reasons:

1. Across controllers, multiple models can exist with the same name. By changing the model owner during import, we avoid conflicts importing many models with the same name, owned by the same user, e.g. the “admin” user.

2. When a controller is connected to JAAS, all application-offers are authorised by JAAS - see our authorization doc for more details on how JAAS authorises access to resources. This impacts any existing cross-model relations.

An example mapping is below:

admin: [email protected]
alice: [email protected]

The file must provide, at minimum, an entry mapping the existing model owner to a new external user.

The mapping is also consulted when Juju relations are periodically validated.

I.e. if an offer was previously consumed by the local Juju user “alice”, when JIMM validates the relation it will map user “alice” to “alice@canonical.com ” to authorise access to the offer. Revoking access from “alice@canonical.com ” will result in the relation encountering an error.

It may not be possible to know all users that have have consumed offers when you wish to migrate a model, but using juju show-offer will help to see all users that currently have access to an offer. This list should help determine which users to specify in the user mapping file.

With a user mapping created, we can move onto the next step.

3. Validate cloud-credentials

Next we must check that we have a valid cloud-credential for the incoming model. Run juju show-model and look for the credential field which should resemble the below:

  credential:
    name: lxd-creds
    owner: admin
    cloud: localhost
    validity-check: valid

The new model owner must have a cloud-credential with the same name and for the same cloud.

Using the credential details above as an example - if model admin/foo is being migrated and the user mapping contains the row admin: joe@canonical then joe@canonical must have a credential (juju show-credentials --controller) named lxd-creds for cloud localhost in JIMM.

If you do not see a matching cloud-credential, you can add one by following the instructions in managing cloud-credentials .

3. Migrate desired models

Once you have identified which models to migrate, created a user mapping file and validated that the new owner has a valid cloud-credential, we can begin the process of model migration.

We will assume a model called admin/my-model is currently hosted on a controller called my-controller and a controller called workload-lxd is connected to JIMM, where JIMM is known to the CLI as jimm.

A user mapping file called test-mapping.yaml is created and placed in ~/snap/juju/common/ to avoid Snap permission issues.

juju switch my-controller:admin/my-model
juju jaas migrate admin/my-model jimm --backing-controller=workload-lxd --user-mapping="/home/user/snap/juju/common/test-mapping.yaml"
juju status --watch 2s
# Wait for model migration to complete.
juju switch jimm
juju models

At this point we should see the model has been migrated. If the model migration fails, juju debug-log should contain more info and the migration will be aborted, leaving the model on the original controller.

After a successful migration, it is now possible to grant other users access to the model. See Juju documentation for more info .

Migrate a model within JAAS

This document briefly covers how to migrate a model between two controllers within JAAS.

JIMM can have multiple controllers connected to it, where more than 1 controller has access to the same cloud. When a model is requested on such a cloud, JIMM will randomly select an appropriate controller.

The below is useful if you want to move the model to a specific controller.

Prerequisites

• A basic understanding of Juju model migrations, see the docs .

• A running JAAS with with multiple controllers attached, see the the tutorial for deploying JAAS.

• Administrator permissions for JAAS, so our Add a Juju controller.

Connecting multiple controllers to JAAS can be accomplished adding LXD controllers as described in Add a Juju controller.

1. Identify the new controller

JIMM does not currently expose information about which underlying controller hosts a specific model. This information is stored in JIMM’s database but the controller info returned when running juju show-model <model-name> is JIMM’s UUID and name, hiding the underlying controller information.

The following command will show you all the controllers connected to JIMM.

juju list-controllers --managed

Currently to identify where the model is hosted, you must have access to the controllers connected to JIMM and switch to those controllers in turn, and run juju models until you identify the correct controller.

Identify the controller you want to migrate to, only the name is necessary.

2. Migrate your model

The following command will migrate a model named my-model to the desired controller, in this case called my-controller.

MODEL_NAME=my-model
MODEL_UUID=$(juju show-model $MODEL_NAME --format yaml | yq .$MODEL_NAME.model-uuid)
juju jaas migrate my-controller $MODEL_UUID

This will start the model migration process. You can now monitor the progress of the migration with juju status and juju debug-log.

Once the model has been successfully migrated, run the following command to update JIMM with the new controller information for the model.

juju update-migrated-model my-controller $MODEL_UUID

This will update JIMM’s internal state to locate the model on the specified controller.

At this point you can run juju status to see the model info.

3. Handling failed migration

If the model migration fails, then no further user input is required and the model should continue to exist on the original controller.

To inspect the reason for failure, consult the output from juju debug-log and juju status.

Control user access to a model

To grant a (collection of) user(s) access to a model, add a reader, writer, or administrator permission between the user(s) and the model. For example:

For example:

# Make Alice model admin:
juju add-permission [email protected] administrator cloud-mycloud

# Let all users with role myrole have read access to model mymodel:
juju add-permission role-myrole#assignee reader model-mycontroller/mymodel

See more: Manage permissions