Migrate models how-to

how-to/add_controller.rst

@@ -78,9 +78,6 @@ LXD Controller
 
 The following section provides guidance on how to connect a controller bootstrapped on LXD to your JIMM running in MicroK8s.
 
-The steps will be similar to those for adding a MicroK8s hosted controller but because we are traversing from the isolated network
-of the container through to LXD's network, there will be additional steps.
-
 Run the following commands to bootstrap a LXD based controller:
 
 .. code:: bash
@@ -103,24 +100,11 @@ The set of commands will do the following:
 - The Cloud-init script will add the CA cert in ``/usr/local/share/ca-certificates/jimm-test.crt`` to the machine. If you've placed JIMM's CA cert elsewhere, please update this file location.
 - Finally the bash script will bootstrap Juju and configure it to communicate with JIMM.
 
-Next, we will create a network relay to forward traffic from our host network through to the Juju server running in a LXC container.
-
-.. note::
-    The network relay relies on the ``socat`` application running in the background.  
-    The application will need to be run again between system reboots.
-
-.. code:: bash
-
-    JUJU_ADDRESS=$(juju show-controller workload-lxd --format yaml | yq .workload-lxd.details.api-endpoints.[0])
-    socat tcp-listen:8001,reuseaddr,fork tcp:$JUJU_ADDRESS
-
-To test the relay is working run the following command which should return a HTTP 400 response code.
-
-.. code:: bash
-
-    curl -ki https://localhost:8001
+Next, it is helpful to understand that we are traversing from the isolated network of the container through to 
+the host's network and to the LXD container where our Juju controller resides. This is possible thanks to the ``host-access``
+add-on in MicroK8s which allows containers to access the host network through a fixed IP address.
 
-Finally, we can connect our new controller to JIMM.
+Connect our new controller to JIMM.
 
 .. code:: bash
 

how-to/index.rst

@@ -18,13 +18,14 @@ Here are instructions on how to deploy JIMM.
 JIMM Configuration
 ------------------
 
-After JIMM has been deployed, you need to configure it with your Juju-operated cluster.
+After JIMM has been deployed, you need to configure it with your Juju operated cluster.
 
 .. toctree::
    :maxdepth: 1
 
-   Add controller to JIMM <add_controller>
    Bootstrap permissions <bootstrap_permissions>
+   Add a controller to JIMM <add_controller>
+   Migrate models <migrate_models>
    Set up Route53 <route53>
 
 Terraform

how-to/migrate_models.rst

@@ -0,0 +1,77 @@
+JAAS: Model Migration
+=====================
+
+In many scenarios it is necessary to migrate models from existing Juju controllers
+to an environment that includes JAAS.
+
+Prerequisites
+-------------
+
+- A standalone Juju controller with a model (optionally with a running application).
+- A basic understanding of Juju model migrations, see the `docs <https://juju.is/docs/juju/manage-models>`__.
+- A running JAAS, see the :doc:`tutorial <../tutorial/deploy_jaas_microk8s>`.
+- Administrator permissions for JAAS, so our :doc:`how-to <./bootstrap_permissions>`.
+
+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 
+at a running JIMM instance. Use the following command to check if your controller is configured.
+
+.. code:: bash
+
+    juju switch <controller-name>
+    juju controller-config login-token-refresh-url
+
+An empty value indicates that a new controller is necessary.
+
+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 local Juju controller that is properly configured is described in :doc:`this how-to <./add_controller>`.
+
+Once a Juju controller that is configured to communicate with JIMM has been created, move onto the next step.
+
+2. Migrate desired models
+-------------------------
+
+Once you have identified which models to migrate, we will begin the process of model migration.
+
+We will assume a model called ``my-model`` is currently hosted on a controller called ``prod-controller`` and moving to a new controller 
+called ``workload-lxd`` (``workload-lxd`` should be connected to JIMM).
+
+.. code:: bash
+
+    juju switch prod-controller:my-model
+    juju migrate my-model workload-lxd
+    juju status --watch 2s
+    # Wait for model migration to complete.
+    juju switch workload-lxd
+    juju models
+
+At this point we should see the model has been migrated.
+
+3. Import the model into JIMM
+-----------------------------
+
+Finally we will import the model into JIMM using ``jimmctl``. 
+We first need the model UUID then we can import the model.
+
+.. code:: bash
+
+    MODEL_NAME="my-model"
+    juju switch workload-lxd:$MODEL_NAME
+    MODEL_UUID=$(juju show-model $MODEL_NAME --format yaml | yq .$MODEL_NAME.model-uuid)
+    juju switch jimm-k8s
+    # Replace <user-email> below with your email address
+    jimmctl import-model workload-lxd $MODEL_UUID --owner <username>
+    juju models
+    # The new model should now be visible
+
+With that the model should now be visible in JIMM. The purpose of the ``--owner`` flag is to tell JIMM who 
+the new model owner should be. Models created on Juju controllers use local users while JIMM requires external
+identities for all users.
+
+At this point you can grant other users access to the model.
+
+

tutorial/deploy_jaas_microk8s.rst

@@ -58,7 +58,7 @@ To begin, run the following commands to setup MicroK8s.
     # Create the 'microk8s' group:
     newgrp snap_microk8s
     # Enable the necessary MicroK8s addons:
-    sudo microk8s enable hostpath-storage dns ingress
+    sudo microk8s enable hostpath-storage dns ingress host-access
     # Setup the metallb add-on for the identity bundle later
     sudo microk8s enable metallb:10.64.140.43-10.64.140.100
     # Set up a short alias for the Kubernetes CLI:
@@ -352,10 +352,10 @@ Using Your JIMM Deployment
 
 Now that you have JIMM running you can browse our additional guides to setup an admin user, add controllers and migrate existing workloads.
 
-- Setup your initial JIMM admin and configure permissions.
+- :doc:`Setup your initial JIMM admin and configure permissions<../how-to/bootstrap_permissions>`.
 - :doc:`Learn how to add a new controller to JIMM.<../how-to/add_controller>`
-- Learn how to migrate models from existing controllers to JIMM.
-- Understand the difference between the ``juju``, ``jaas`` and ``jimmctl`` CLI tools.
+- :doc:`Learn how to migrate models from existing controllers to JIMM <../how-to/migrate_models>`.
+- :doc:`Understand the difference between the available CLI tools <../explanation/cli_tools>`.
 
 Common Issues
 -------------