diff --git a/how-to/add_controller.rst b/how-to/add_controller.rst index 2ed8fb8..262b8b3 100644 --- a/how-to/add_controller.rst +++ b/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 diff --git a/how-to/index.rst b/how-to/index.rst index b89b6e0..1265bd1 100644 --- a/how-to/index.rst +++ b/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 Bootstrap permissions + Add a controller to JIMM + Migrate models Set up Route53 Terraform diff --git a/how-to/migrate_models.rst b/how-to/migrate_models.rst new file mode 100644 index 0000000..9a28411 --- /dev/null +++ b/how-to/migrate_models.rst @@ -0,0 +1,91 @@ +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 `__. +- 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 + 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 ``my-controller`` and moving to a new controller +called ``workload-lxd`` (``workload-lxd`` should be connected to JIMM). + +.. code:: bash + + juju switch my-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``. + +First we must check that we have a cloud-credential for the cloud where the desired model is running. +This is simply a pre-check performed when importing a model to ensure that the user has credentials for the cloud. + +Check with the following, + +.. code:: bash + + juju switch jimm + juju list-credentials --controller + +If you do not see a cloud-credential for the desired cloud, you can add one by following the instructs on +`managing cloud-credentials `__. + +We then need the model UUID to 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 below with your email address + jimmctl import-model workload-lxd $MODEL_UUID --owner + 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. + + diff --git a/tutorial/deploy_jaas_microk8s.rst b/tutorial/deploy_jaas_microk8s.rst index bb4a9cb..f874880 100644 --- a/tutorial/deploy_jaas_microk8s.rst +++ b/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 -------------