doc: provide the documentation for the deployment to prodstack (#9)

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to IAM bundle Terraform module
+# Contributing to Identity Platform Juju bundle Terraform module
 
 ## Development environment
 
@@ -64,3 +64,14 @@ the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) to
 create commit messages. This facilitates the usage of the
 [Release Please Action](https://github.com/google-github-actions/release-please-action)
 for automated releases of the Terraform module.
+
+## Releasing
+
+This repository leverages
+the [release-please GitHub action](https://github.com/google-github-actions/release-please-action)
+to help release. After releasing a new version of the module, create a merge
+request to update
+the [module version](https://git.launchpad.net/canonical-terraform-plans/tree/identity/environments/staging/main.tf#n2)
+in
+the [canonical-terraform-plans](https://launchpad.net/canonical-terraform-plans)
+launchpad repository. Invite the IS team to review and merge the changes.

MODULE_SPECS.md

@@ -1,7 +1,7 @@
 # Terraform Module Specifications
 
-This documentation shows the detailed specifications of the IAM bundle
-Terraform module.
+This documentation shows the detailed specifications of the Identity Platform
+Juju bundle Terraform module.
 
 <!-- BEGIN_TF_DOCS -->
 ## Providers
@@ -19,8 +19,7 @@ Terraform module.
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| <a name="input_model"></a> [model](#input\_model) | The name of the Juju model to deploy to. | `string` | `"iam-bundle"` | no |
-| <a name="input_cloud"></a> [cloud](#input\_cloud) | The Juju cloud information. | <pre>object({<br>    name   = string<br>    region = string<br>  })</pre> | <pre>{<br>  "name": "microk8s",<br>  "region": "localhost"<br>}</pre> | no |
+| <a name="input_model"></a> [model](#input\_model) | The name of the Juju model to deploy to. | `string` | `"identity-platform"` | no |
 | <a name="input_hydra"></a> [hydra](#input\_hydra) | The configurations of the Hydra application. | <pre>object({<br>    units   = optional(number, 1)<br>    channel = optional(string, "edge")<br>    series  = optional(string, "jammy")<br>    trust   = optional(string, true)<br>    config  = optional(map(string), {})<br>  })</pre> | `{}` | no |
 | <a name="input_kratos"></a> [kratos](#input\_kratos) | The configurations of the Kratos application. | <pre>object({<br>    units   = optional(number, 1)<br>    channel = optional(string, "edge")<br>    series  = optional(string, "jammy")<br>    trust   = optional(string, true)<br>    config  = optional(map(string), {})<br>  })</pre> | `{}` | no |
 | <a name="input_login_ui"></a> [login\_ui](#input\_login\_ui) | The configurations of the Identity Platform Login UI application. | <pre>object({<br>    units   = optional(number, 1)<br>    trust   = optional(bool, true)<br>    config  = optional(map(string), {})<br>    channel = optional(string, "edge")<br>    series  = optional(string, "jammy")<br>  })</pre> | `{}` | no |

Makefile

@@ -18,7 +18,7 @@ validate:
 
 ## plan:     Plan the changes.
 plan: verify-var-file-set
-	@terraform plan -var-files=${VAR_FILE}
+	@terraform plan -var-file=${VAR_FILE}
 
 verify-var-file-set:
 ifndef VAR_FILE

README.md

@@ -1,4 +1,4 @@
-# IAM Bundle Terraform Module
+# Identity Platform Juju Bundle Terraform Module
 
 [![Build](https://img.shields.io/github/actions/workflow/status/wood-push-melon/iam-bundle-test/pull_request.yaml?label=Build)](https://github.com/canonical/iam-bundle-integration/actions/workflows/pull_request.yaml)
 [![Latest Release](https://img.shields.io/github/release/canonical/iam-bundle-integration.svg?label=Release)](https://github.com/canonical/iam-bundle-integration/releases/latest)
@@ -7,8 +7,8 @@
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196.svg)](https://conventionalcommits.org)
 [![License](https://img.shields.io/github/license/canonical/iam-bundle-integration?label=License)](https://github.com/canonical/iam-bundle-integration/blob/main/LICENSE)
 
-This IAM bundle Terraform module aims to deploy
-the [IAM Bundle](https://github.com/canonical/iam-bundle) via Terraform.
+This Identity Platform Juju bundle Terraform module aims to deploy
+the [Identity Platform Juju Bundle](https://github.com/canonical/iam-bundle) via Terraform.
 
 ## Getting started
 
@@ -23,15 +23,23 @@ in the local environment.
 
 ### Deploy locally with Terraform
 
-Because the IAM bundle uses an external Idp provider (e.g. Microsoft Azure),
+Create a target Juju model:
+
+```shell
+$ juju add-model <juju model>
+```
+
+Because the bundle uses an external Idp provider (e.g. Microsoft Azure),
 it needs to provide additional variables for the module to run. More
 information about the Idp provider configuration can be
 found [here](https://github.com/canonical/kratos-external-idp-integrator/blob/main/config.yaml).
 Please create a Terraform variable definition (`.tfvars`) file in the root
 directory as follows.
 
 ```shell
-# idp_provider.tfvars
+# vars.tfvars
+model = <juju model>
+
 idp_provider_config = {
   client_id           = <client id>
   provider            = <provider name>
@@ -44,23 +52,24 @@ idp_provider_credentials = {
 }
 ```
 
-Run the following commands to deploy the IAM bundle.
+Run the following commands to deploy the bundle.
 
 ```shell
 $ terraform init
-$ terraform apply -var-files="./idp_provider.tfvars"
+$ terraform apply -var-file="./vars.tfvars"
 ```
 
-Run `juju switch iam-bundle` to use the created Juju model.
+Run `juju switch <juju model>` to switch to the target Juju model.
 
 ```shell
 # Observe the status of the applications and integrations
 $ juju status --relations
 ```
 
-### Deploy to the Canonical Cloud
+### Deploy to the ProdStack 6 Cloud
 
-TBD.
+Please refer to the [deployment documentation](docs/DEPLOYMENT.md) to learn
+how to deploy the module to the ProdStack Cloud.
 
 ## Terraform Module Specifications
 

applications.tf

@@ -1,34 +1,34 @@
 module "postgresql" {
   source = "./modules/postgresql"
 
-  model = juju_model.iam_bundle.name
+  model = var.model
   name  = "postgresql"
 }
 
 module "public_ingress" {
   source = "./modules/ingress"
 
-  model = juju_model.iam_bundle.name
+  model = var.model
   name  = "public-ingress"
 }
 
 module "admin_ingress" {
   source = "./modules/ingress"
 
-  model = juju_model.iam_bundle.name
+  model = var.model
   name  = "admin-ingress"
 }
 
 module "kratos_external_idp_integrator" {
   source = "./modules/external_idp_integrator"
 
-  model  = juju_model.iam_bundle.name
+  model  = var.model
   name   = "kratos-external-idp-integrator"
   config = merge(var.idp_provider_config, var.idp_provider_credentials)
 }
 
 resource "juju_application" "kratos" {
-  model = juju_model.iam_bundle.name
+  model = var.model
   name  = "kratos"
   trust = var.kratos.trust
   units = var.kratos.units
@@ -41,7 +41,7 @@ resource "juju_application" "kratos" {
 }
 
 resource "juju_application" "hydra" {
-  model = juju_model.iam_bundle.name
+  model = var.model
   name  = "hydra"
   trust = var.hydra.trust
   units = var.hydra.units
@@ -54,7 +54,7 @@ resource "juju_application" "hydra" {
 }
 
 resource "juju_application" "login_ui" {
-  model = juju_model.iam_bundle.name
+  model = var.model
   name  = "login-ui"
   trust = var.login_ui.trust
   units = var.login_ui.units

docs/DEPLOYMENT.md

@@ -0,0 +1,149 @@
+# How to Deploy to ProdStack 6 Cloud
+
+## Prerequisites
+
+Before deploying the Identity Platform Juju Bundle Terraform module to ProdStack
+6 Cloud, you need to prepare the followings:
+
+- A service environment has been provisioned in the ProdStack 6 Cloud. If not,
+  please refer to [this section](#how-to-deploy-a-service-environment).
+- Submit [a request to IS for SSH key update](https://portal.admin.canonical.com/requests/new)
+and invite two team member to approve it.
+- Set up and connect to the
+  company-wide [VPN](https://wiki.canonical.com/InformationInfrastructure/IS/HowTo/CompanyOpenVPN).
+
+## How to deploy the module
+
+### Deploy the module
+
+IS team provisioned a bastion server for Identity team to use for accessing the
+service environment.
+You can use the generated ssh private key to log into the server by running the
+following command:
+
+```shell
+$ ssh -i <path-to-private-key> <username>@identity-bastion-ps6.internal
+```
+
+**Note:** the username should be your launchpad id.
+
+Once you logged in, list all the service environments created using the
+following command:
+
+```shell
+$ pe -n
+
+sudo -iu stg-iam-bundle se stg-iam-bundle # (0) [LIVE][PS6][K8S] Testing environment for IAM bundle
+```
+
+Run the following to switch to the target service environment:
+
+```shell
+$ pe stg-iam-bundle
+
+This model is managed by Terraform. Please don't make manual changes using
+the Juju CLI except in an emergency.
+
+This environment is defined by plan: "placeholder/environments/stg"
+
+To use Terraform, run:
+
+  cd ~/plan && git pull
+  load_creds s3
+  terraform plan
+
+See https://wiki.canonical.com/InformationInfrastructure/IS/Terraform
+for more details.
+```
+
+Initialize the remote Terraform backend for the module. **Note:** You don't
+need to run the following command unless this is the first time that the module
+is to be deployed.
+
+```shell
+$ bootstrap_backend
+```
+
+As per the outputs of the `pe` command above, run the following commands:
+
+```shell
+# Fetch the latest canonical-terraform-plans repository if necessary
+$ cd ~/plan && git pull
+
+# Load the credentials for the S3 bucket from Vault server
+$ load_creds s3
+```
+
+Prepare a Terraform variable definition (`.tfvars`) file if not exists:
+
+```shell
+# vars.tfvars
+model = <juju model, e.g. 'stg-iam-bundle'>
+
+idp_provider_config = {
+  client_id           = <client id>
+  provider            = <provider name>
+  provider_id         = <provider id>
+  microsoft_tenant_id = <tenant id> # if using Microsoft Azure
+}
+
+idp_provider_credentials = {
+  client_secret = <client secret>
+}
+```
+
+> :rotating_light: **Note:**
+>
+> - A variable file had been created in the home directory,
+    e.g. `/home/stg-iam-bundle/vars.tfvars`. Make changes if necessary.
+> - There is no secret management solution yet to allow users to manage their
+    own secrets.
+
+Then run the following commands to deploy:
+
+```shell
+# Initialize the working directory
+$ https_proxy=http://squid.internal:3128 NO_PROXY=radosgw.ps6.canonical.com terraform init
+
+# Create and preview an execution plan
+$ terraform plan -var-file=<path-to-var-file>
+
+# Execute the plan
+$ terraform apply -var-file=<path-to-var-file>
+```
+
+Monitor the status of the deployment:
+
+```shell
+$ watch -n1 juju status --relations
+```
+
+### Clean up
+
+If you no longer need the deployed module, run the following command to clean up
+the provisioned resources:
+
+```shell
+$ terraform destroy
+```
+
+## How to deploy a service environment
+
+If a new service environment is needed, you need to make changes to the root
+module where the service environments used by Identity team are declared. Use
+the [service_environment](https://git.launchpad.net/canonical-terraform-modules/tree/prodstack/common/service_environment/README.md)
+Terraform module to create a service environment. Create a merge request and
+invite the IS team to review and deploy it.
+
+```shell
+$ git clone lp:canonical-terraform-plans
+
+$ cd prodstack/ps6/environments/identity/<stage, e.g. 'staging' or 'production'>
+
+$ vim main.tf
+```
+
+## References
+
+- [Canonical Terraform Plans](https://launchpad.net/canonical-terraform-plans)
+- [Canonical Terraform Modules](https://launchpad.net/canonical-terraform-modules)

integrations.tf

@@ -76,7 +76,7 @@ resource "juju_integration" "integration" {
     for idx, integration in local.integrations : idx => integration
   }
 
-  model = juju_model.iam_bundle.name
+  model = var.model
 
   application {
     name     = each.value.provider

variables.tf

@@ -1,19 +1,7 @@
 variable "model" {
   description = "The name of the Juju model to deploy to."
   type        = string
-  default     = "iam-bundle"
-}
-
-variable "cloud" {
-  description = "The Juju cloud information."
-  type = object({
-    name   = string
-    region = string
-  })
-  default = {
-    name   = "microk8s"
-    region = "localhost"
-  }
+  default     = "identity-platform"
 }
 
 variable "hydra" {