From 5952bd9da6904298c5da5d44e3e574ab0758d33d Mon Sep 17 00:00:00 2001
From: alesstimec <ales.stimec@canonical.com>
Date: Fri, 12 Apr 2024 13:22:54 +0200
Subject: [PATCH] Added a how-to use terraform.

---
 .custom_wordlist.txt     |   3 +
 how-to/index.rst         |   9 ++-
 how-to/use_terraform.rst | 133 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 144 insertions(+), 1 deletion(-)
 create mode 100644 how-to/use_terraform.rst

diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt
index 8b15291..f038fb6 100644
--- a/.custom_wordlist.txt
+++ b/.custom_wordlist.txt
@@ -82,3 +82,6 @@ VM
 webhook
 Xbox
 YAML
+Terraform
+OAuth
+OAuth2
\ No newline at end of file
diff --git a/how-to/index.rst b/how-to/index.rst
index 1ea62d4..62ffd4b 100644
--- a/how-to/index.rst
+++ b/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>
\ No newline at end of file
diff --git a/how-to/use_terraform.rst b/how-to/use_terraform.rst
new file mode 100644
index 0000000..e8a4986
--- /dev/null
+++ b/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``
\ No newline at end of file