JAAS: Using Terraform
=====================

Introduction
------------

In this how-to we will be showing you how to use Terraform with JAAS.

Prerequisites
-------------

For this how-to you will need the following:

- An identity provider that can be used to create OAuth2.0 client credentials.
- Client credentials (``client_id`` and ``client_secret``) generated by the above identity provider.
- A deployed JAAS configured to trust the identity provider. For instructions on 
  how to deploy JIMM read :doc:`../tutorial/deploy_jaas_microk8s`.
- A Juju controller added to JIMM that can be used to control your chosen cloud. For instructions
  on how to add one read :doc:`add_controller`.
- A Juju client.
- Cloud credentials for the chosen cloud (see `here <https://juju.is/docs/juju/manage-credentials>`_).
- Basic knowledge of Terraform, Juju Terraform provider and Juju.

Registering client credentials
------------------------------

Before we can use client credentials generated by your chosen identity provider we need
to register them.

1. Install the JAAS snap:

    ``sudo snap install jaas --channel latest/stable``

2. Register the cloud credential:

    ``juju add-service-account <client ID>``

3. Update cloud credentials for the service account:

    ``juju update-service-account-credentials <client ID> <cloud> <credential name>``


Juju Terraform provider
-----------------------

To authenticate with JIMM the provider section in your Terraform plan needs to include 
the ``client_id`` and ``client_secret`` generated by your identity provider. Please note that 
you need to use a version of the `Juju Terraform provider <https://registry.terraform.io/providers/juju/juju/latest/docs>`_
higher than ``0.12.0``.

For this how-to we will be deploying the ``juju-qa-test`` charm.

Let's create a temporary folder. Run:

    ``mkdir terraform_tutorial``

and:

    ``cd terraform_tutorial``

Now create a file called ``main.tf`` with the following content:

    .. code:: terraform

        terraform {
            required_providers {
                juju = {
                    version = "0.11.0"
                    source  = "juju/juju"
                }
            }
        }

        provider "juju" {
            controller_addresses = "<address of your controller>" # (e.g., "jimm:443")

            client_id     = "<clientID>"
            client_secret = "<clientSecret>"

            ca_certificate = "<CA certificate>"
        }

        resource "juju_model" "qa" {
            name = "qa"

            cloud {
                name = "localhost"
            }
        }

        resource "juju_application" "qa" {
            name = "qa"

            model = juju_model.qa.name

            charm {
                name = "juju-qa-test"
            }

            units = 1
        }


Run:

    ``terraform init``

Then:

    ``terraform plan``

and verify the proposed changes and run:

    ``terraform apply``

You can now switch to the created ``qa`` model and see the deployed ``qa`` application.

    .. code::

        Model  Controller           Cloud/Region         Version      SLA          Timestamp
        qa     localhost-localhost  localhost/localhost  3.5-beta1.1  unsupported  12:02:40+02:00

        App  Version  Status  Scale  Charm         Channel        Rev  Exposed  Message
        qa            active      1  juju-qa-test  latest/stable   25  no       hello

        Unit   Workload  Agent  Machine  Public address  Ports  Message
        qa/0*  active    idle   0        10.221.163.152         hello

        Machine  State    Address         Inst id        Base          AZ  Message

To destroy the created model, run:

    ``terraform destroy``