Added a how-to use terraform.

.wordlist.txt

@@ -47,3 +47,6 @@ UI
 UUID
 VM
 YAML
+Terraform
+OAuth
+qa

how-to/index.rst

@@ -41,5 +41,12 @@ After JIMM has been deployed, you need to configure it with your Juju-operated c
    :maxdepth: 1
 
    Add controller <add_controller>
-   Cross-Model Queries <cross_model_queries>
    Set up Route53 <route53>
+
+Terraform
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   Using Terraform <use_terraform>

how-to/use_terraform.rst

@@ -0,0 +1,133 @@
+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 client credentials
+- Client credentials (`client_id` and `client_secret`) generated by the above identity provider.
+- A deployed JIMM configured to trust the identity provider. For instructions on 
+  how to deploy JIMM read :doc:`deploy_jimm`.
+- A Juju 3.5 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 3.5 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 {
+            required_providers {
+                juju = {
+                version = "0.11.0"
+                source  = "juju/juju"
+                }
+            }
+        }
+
+        provider "juju" {
+            controller_addresses = "<address of your controller>"
+
+            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``