Update applying terraform documentation for Terraform Cloud

terraform/docs/applying-terraform.md

@@ -7,60 +7,49 @@ The EKS cluster is deployed via Terraform in two stages. See [adr-3] for backgro
 
 ## Prerequisites
 
-1. Some of the deployments below require external [tfvars
-files](../terraform/deployments/variables). To create a new environment, you
-will need to copy the variables directory for an existing environment (e.g.
-[integration](../deployments/variables/integration)) and modify as
-appropriate.
-    1. `cluster-infrastructure` deployment assumes that there is a Fastly CDN service
-       and requires a value (`www_dns_validation_rdata`) for creating the DNS validation of the Fastly domain. You can
-       either use a dummy value or look at setting up the [CDN service](../../docs/setting-up-content-delivery-network.md)
-1. Each of the deployments (except `ecr`) requires a [backend config
-file](https://www.terraform.io/docs/language/settings/backends/configuration.html#partial-configuration)
-You can use an existing backend file as a template.
-1. `cluster-services` deployment requires some [prerequisite secrets](../../docs/prerequisite-secrets.md)
+1. `cluster-infrastructure` deployment assumes that there is a Fastly CDN service
+   and requires a value (`www_dns_validation_rdata`) for creating the DNS validation of the Fastly domain. You can
+   either use a dummy value or look at setting up the [CDN service](../../docs/setting-up-content-delivery-network.md)
+2. `cluster-services` deployment requires some [prerequisite secrets](../../docs/prerequisite-secrets.md)
 which are not generated automatically. Create these secrets before running
-`terraform apply` for the first time.
+the Terraform apply for the first time.
 
 ## Deployment
 
-**We no longer have any deployment automation for Terraform** (since the demise of Big Concourse).
-
-For testing before merging to `main`, we can run Terraform locally against the test account.
+All terraform modules in this repository are now deployed via Terraform Cloud.
+To test changes before merging into main, open a PR and a plan will automatically
+start for your branch.
 
 When turning up from scratch, deploy the root modules in this order:
 
-1. [`terraform-lock`](../deployments/terraform-lock): creates the
-   DynamoDB table which Terraform uses to control concurrent access to the
-   state files in S3.
-1. [`ecr`](../deployments/ecr) (test and production accounts only): creates the ECR container registry from
+1. [`tfc-bootstrap`](../deployments/tfc-bootstrap): bootstraps Terraform Cloud and creates `tfc-configuration`
+workspace which is used to manage the other Terraform module workspaces.
+2. [`tfc-configuration`](../deployments/tfc-configuration): creates TFC workspaces for each terraform module and environment.
+3. [`ecr`](../deployments/ecr) (test and production accounts only): creates the ECR container registry from
    which the cluster pull container images. There is a single registry for all
    of the environments (to avoid consistency problems with image tags and
    having to copy images between registries), so this module is not deployed
    per-environment.
-1. [`cluster-infrastructure`](../deployments/cluster-infrastructure): creates the AWS resources for the cluster.
-1. Delete the `aws-auth` configmap by running `gds aws govuk-${ENV?}-admin -- aws eks update-kubeconfig --name govuk && kubectl -n kube-system delete cm aws-auth`. This is a workaround for the problem that one of the AWS-managed EKS addons creates a default aws-auth configmap which then either needs to be imported into Terraform or deleted.
-1. [`govuk-publishing-infrastructure`](../deployments/govuk-publishing-infrastructure): creates AWS resources specific to the GOV.UK apps where we are not yet
+4. [`cluster-infrastructure`](../deployments/cluster-infrastructure): creates the AWS resources for the cluster.
+5. Delete the `aws-auth` configmap by running `gds aws govuk-${ENV?}-admin -- aws eks update-kubeconfig --name govuk && kubectl -n kube-system delete cm aws-auth`. This is a workaround for the problem that one of the AWS-managed EKS addons creates a default aws-auth configmap which then either needs to be imported into Terraform or deleted.
+6. [`govuk-publishing-infrastructure`](../deployments/govuk-publishing-infrastructure): creates AWS resources specific to the GOV.UK apps where we are not yet
 able to manage those resources via Kubernetes.
-1. [`cluster-services`](../deployments/cluster-services): deploys the base services into the cluster.
-
-### `cluster-infrastructure`, `cluster-services` or `govuk-publishing-infrastructure` modules
+7. [`cluster-services`](../deployments/cluster-services): deploys the base services into the cluster.
 
-```sh
-ENV=test  # or integration, staging, production
-cd terraform/deployments/cluster-infrastructure  # or cluster-services or govuk-publishing-infrastructure
+### Bootstrapping Terraform Cloud
 
-gds aws govuk-${ENV?}-admin -- terraform init -backend-config=${ENV?}.backend -reconfigure -upgrade
-gds aws govuk-${ENV?}-admin -- terraform apply -var-file ../variables/common.tfvars -var-file ../variables/${ENV?}/common.tfvars
-```
+1. [Configure an OIDC connection between each AWS environment and Terraform Cloud](https://developer.hashicorp.com/terraform/cloud-docs/workspaces/dynamic-provider-credentials/aws-configuration).
+2.  Create an IAM role named `terraform-cloud` in each AWS environment.
+    * See example [permissions policy](./example-tfc-role-policy.json) and [trust policy](./example-tfc-trust-policy.json).
+3. Apply the [`tfc-bootstrap`](../deployments/tfc-bootstrap) module locally. This will create the `tfc-configuration` workspace, which will
+   create all of the remaining workspaces.
 
 ### Other modules
 
 See the README.md for the module:
 
 * [`ecr`](../deployments/ecr/README.md) (test and production accounts only)
 * [`github`](../deployments/github/README.md)
-* [`terraform-lock`](../deployments/terraform-lock/README.md)
 
 ## Running kubectl
 

terraform/docs/example-tfc-role-policy.json

@@ -0,0 +1,54 @@
+{
+  "Statement": [
+      {
+          "Action": [
+              "acm:*",
+              "apigateway:*",
+              "autoscaling:*",
+              "cloudfront:*",
+              "cloudwatch:*",
+              "ec2:*",
+              "ecr:*",
+              "eks:*",
+              "elasticache:*",
+              "elasticloadbalancing:*",
+              "elasticfilesystem:*",
+              "es:*",
+              "events:*",
+              "iam:*",
+              "kms:*",
+              "lambda:*",
+              "logs:*",
+              "mq:*",
+              "rds:*",
+              "route53:*",
+              "s3:*",
+              "secretsmanager:*",
+              "sns:*",
+              "sqs:*",
+              "wafv2:*"
+          ],
+          "Effect": "Allow",
+          "Resource": "*"
+      },
+      {
+          "Action": [
+              "aws-marketplace:*",
+              "aws-marketplace-management:*",
+              "aws-portal:*",
+              "budgets:*",
+              "config:*",
+              "directconnect:*",
+              "ec2:*Purchase*",
+              "ec2:*ReservedInstances*",
+              "iam:*Login*",
+              "iam:*Group*",
+              "iam:*PermissionsBoundary*",
+              "iam:CreateServiceLinkedRole"
+          ],
+          "Effect": "Deny",
+          "Resource": "*"
+      }
+  ],
+  "Version": "2012-10-17"
+}

terraform/docs/example-tfc-trust-policy.json

@@ -0,0 +1,20 @@
+{
+  "Version": "2012-10-17",
+  "Statement": [
+      {
+          "Effect": "Allow",
+          "Principal": {
+              "Federated": "arn:aws:iam::$AWS_ACCOUNT_ID:oidc-provider/app.terraform.io"
+          },
+          "Action": "sts:AssumeRoleWithWebIdentity",
+          "Condition": {
+              "StringEquals": {
+                  "app.terraform.io:aud": "aws.workload.identity"
+              },
+              "StringLike": {
+                  "app.terraform.io:sub": "organization:govuk:project:*:workspace:*:run_phase:*"
+              }
+          }
+      }
+  ]
+}