Review apps: add Terraform in support of forms-runner review apps

.github/workflows/review_apps_on_pr_change.yml

@@ -0,0 +1,110 @@
+name: "Review apps: on PR change"
+on:
+  pull_request:
+    # being explicit about what to trigger on.
+    # matches the docs for the default types
+    # https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request
+    types: [opened, reopened, synchronize]
+jobs:
+  update-review-app:
+    # this references a codebuild project configured in forms-deploy
+    # see: https://docs.aws.amazon.com/codebuild/latest/userguide/action-runner.html
+    runs-on: codebuild-review-forms-runner-gha-runner-${{github.run_id}}-${{github.run_attempt}}
+
+    permissions:
+      pull-requests: write
+
+    steps:
+      - name: Generate container image URI
+        run: |
+          echo "CONTAINER_IMAGE_URI=842676007477.dkr.ecr.eu-west-2.amazonaws.com/forms-runner:pr-${{github.event.pull_request.number}}-${{github.event.pull_request.head.sha}}-$(date +%s)" >> "$GITHUB_ENV"
+
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build container
+        run: |
+          # Docker credentials are configured in CodeBuild
+          # CodeBuild retrieves the credentials from ParameterStore
+          echo "${DOCKER_PASSWORD}" | docker login -u "${DOCKER_USERNAME}" --password-stdin
+          docker build \
+            --tag "${{env.CONTAINER_IMAGE_URI}}" \
+            .
+
+      - name: Push container
+        id: build-container
+        run: |
+          aws ecr get-login-password --region eu-west-2 \
+          | docker login --username AWS --password-stdin 842676007477.dkr.ecr.eu-west-2.amazonaws.com
+
+          echo "Pushing container image"
+          echo "${{env.CONTAINER_IMAGE_URI}}"
+
+          docker push "${CONTAINER_IMAGE_URI}"
+
+      - name: Determine Terraform version
+        id: terraform-version
+        run: |
+          cat .review_apps/.terraform-version | xargs printf "TF_VERSION=%s" >> "$GITHUB_OUTPUT"
+
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: ${{steps.terraform-version.outputs.TF_VERSION}}
+
+      - name: Deploy review app
+        id: deploy
+        run: |
+          cd .review_apps/
+
+          terraform init -backend-config="key=review-apps/forms-runner/pr-${{github.event.pull_request.number}}.tfstate"
+
+          terraform apply \
+            -var "pull_request_number=${{github.event.pull_request.number}}" \
+            -var "forms_runner_container_image=${{env.CONTAINER_IMAGE_URI}}" \
+            -no-color \
+            -auto-approve
+
+          echo "REVIEW_APP_URL=$(terraform output -raw review_app_url)" >> "$GITHUB_OUTPUT"
+          echo "ADMIN_APP_URL=$(terraform output -raw admin_app_url)" >> "$GITHUB_OUTPUT"
+          echo "ECS_CLUSTER_ID=$(terraform output -raw review_app_ecs_cluster_id)" >> "$GITHUB_OUTPUT"
+          echo "ECS_SERVICE_NAME=$(terraform output -raw review_app_ecs_service_name)" >> "$GITHUB_OUTPUT"
+
+      - name: Wait for AWS ECS deployments to finish
+        run: |
+          aws ecs wait services-stable \
+            --cluster "${{steps.deploy.outputs.ECS_CLUSTER_ID}}" \
+            --services "${{steps.deploy.outputs.ECS_SERVICE_NAME}}"
+
+      - name: Comment on PR
+        env:
+          COMMENT_MARKER: <!-- review apps on pr change -->
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          cat <<EOF > "${{runner.temp}}/pr-comment.md"
+          :tada: A review copy of this PR has been deployed! It is made of up two components
+
+          1. [A review copy of forms-runner](${{steps.deploy.outputs.REVIEW_APP_URL}})
+          2. [A production copy of forms-admin](${{steps.deploy.outputs.ADMIN_APP_URL}})
+
+          > [!IMPORTANT]
+          > Not all of the functionality of forms-runner is present in review apps.
+          > Functionality such as sending emails, file upload, and S3 submission types are
+          > deliberately disabled for the sake of simplifying review apps.
+          >
+          > You should use the full dev environment to test the functionality which is disabled here.
+
+          It may take 5 minutes or so for the application to be fully deployed and working. If it still isn't ready
+          after 5 minutes, there may be something wrong with the ECS task. You will need to go to the integration AWS account
+          to debug, or otherwise ask an infrastructure person.
+
+          For the sign in details and more information, [see the review apps wiki page](https://github.com/alphagov/forms-team/wiki/Review-apps).
+
+          $COMMENT_MARKER
+          EOF
+
+          old_comment_ids=$(gh api "repos/{owner}/{repo}/issues/${{github.event.pull_request.number}}/comments" --jq 'map(select((.user.login == "github-actions[bot]") and (.body | endswith($ENV.COMMENT_MARKER + "\n")))) | .[].id')
+          for comment_id in $old_comment_ids; do
+            gh api -X DELETE "repos/{owner}/{repo}/issues/comments/${comment_id}"
+          done
+
+          gh pr comment "${{github.event.pull_request.html_url}}" --body-file "${{runner.temp}}/pr-comment.md"

.github/workflows/review_apps_on_pr_close.yml

@@ -0,0 +1,36 @@
+name: "Review apps: on PR close"
+on:
+  pull_request:
+    # only run when a PR is closed or merged
+    types: [closed]
+env:
+  IMAGE_TAG: "842676007477.dkr.ecr.eu-west-2.amazonaws.com/forms-runner:pr-${{github.event.pull_request.number}}-${{github.event.pull_request.head.ref}}"
+jobs:
+  delete-review-app:
+    # this references a codebuild project configured in forms-deploy
+    # see: https://docs.aws.amazon.com/codebuild/latest/userguide/action-runner.html
+    runs-on: codebuild-review-forms-runner-gha-runner-${{github.run_id}}-${{github.run_attempt}}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Determine Terraform version
+        id: terraform-version
+        run: |
+          cat .review_apps/.terraform-version | xargs printf "TF_VERSION=%s" >> "$GITHUB_OUTPUT"
+
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: ${{steps.terraform-version.outputs.TF_VERSION}}
+
+      - name: Delete review app
+        run: |
+          cd .review_apps/
+
+          terraform init -backend-config="key=review-apps/forms-runner/pr-${{github.event.pull_request.number}}.tfstate"
+          terraform destroy \
+            -var "pull_request_number=${{github.event.pull_request.number}}" \
+            -var "forms_runner_container_image=${{env.IMAGE_TAG}}" \
+            -no-color \
+            -auto-approve

.github/workflows/terraform.yml

@@ -0,0 +1,37 @@
+name: "Terraform"
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - ".review_apps/**"
+  merge_group:
+    types: [checks_requested]
+env:
+  TERRAFORM_VERSION: "1.11.0"
+jobs:
+  terraform:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - uses: hashicorp/setup-terraform@v3
+        with:
+          terraform_version: ${{env.TERRAFORM_VERSION}}
+
+      - name: Check Terraform style
+        id: tf_fmt
+        working-directory: ".review_apps/"
+        run: |
+          terraform fmt -write=false -diff=true -list=true -recursive -check
+
+      - name: Lint Terraform
+        run: |
+          pip install -r .review_apps/requirements.txt
+          checkov -d .review_apps/ --framework terraform --quiet
+
+      - name: Validate Terraform syntax
+        working-directory: ".review_apps/"
+        run : |
+          terraform init -backend=false || exit
+          terraform validate

.gitignore

@@ -54,3 +54,6 @@ config/settings/*.local.yml
 config/environments/*.local.yml
 
 .DS_Store
+
+# Terraform
+.terraform/

.review_apps/.terraform-version

@@ -0,0 +1 @@
+1.11.0

.review_apps/README.md

@@ -0,0 +1,19 @@
+# Review apps
+
+The Terraform code in this directory is used to deploy a review copy of `forms-admin`.
+
+It constructs a minimal, ephemeral version of a GOV.UK Forms environment in AWS ECS that can be used for reviews, then freely destroyed. This includes: 
+
+* a copy of `forms-admin` at the commit in question
+* a copy of the version of `forms-api` currently in production
+* a local PostgreSQL database with seed data for both `forms-api` and `forms-admin`
+
+Review apps rely on a set of underlying infrastructure managed and deployed in `forms-deploy`. The Terraform will require you to be targeting the `integration` AWS account (where the `review` environment lives), and you should not override this.
+
+### State files
+Each review app uses its own Terraform state file, stored in an S3 bucket. The bucket itself is created and managed by `forms-deploy` and its name is safely assumed.
+
+### `forms-admin` container image
+The `forms-admin` container image to deploy is supplied under the `forms_admin_container_image` variable. Terraform does not build the container. It is assumed to be built and stored ahead of time.
+
+

.review_apps/app_autoscaling.tf

@@ -0,0 +1,38 @@
+resource "aws_appautoscaling_target" "review_app" {
+  service_namespace  = "ecs"
+  resource_id        = "service/${data.terraform_remote_state.review.outputs.ecs_cluster_id}/${aws_ecs_service.app.name}"
+  scalable_dimension = "ecs:service:DesiredCount"
+
+  max_capacity = 1
+  min_capacity = 1
+}
+
+resource "aws_appautoscaling_scheduled_action" "shutdown_at_night" {
+  name = "forms-runner-pr-${var.pull_request_number}-shutdown-at-night"
+
+  service_namespace  = aws_appautoscaling_target.review_app.service_namespace
+  resource_id        = aws_appautoscaling_target.review_app.resource_id
+  scalable_dimension = aws_appautoscaling_target.review_app.scalable_dimension
+
+  schedule = "cron(0 18 * * ? *)" # daily at 1800
+
+  scalable_target_action {
+    min_capacity = 0
+    max_capacity = 0
+  }
+}
+
+resource "aws_appautoscaling_scheduled_action" "startup_weekday_mornings" {
+  name = "forms-runner-pr-${var.pull_request_number}-startup-weekday-mornings"
+
+  service_namespace  = aws_appautoscaling_target.review_app.service_namespace
+  resource_id        = aws_appautoscaling_target.review_app.resource_id
+  scalable_dimension = aws_appautoscaling_target.review_app.scalable_dimension
+
+  schedule = "cron(0 8 ? * MON-FRI *)" # Monday-Friday at 0800
+
+  scalable_target_action {
+    min_capacity = 1
+    max_capacity = 1
+  }
+}

.review_apps/dependencies.tf

@@ -0,0 +1,26 @@
+##
+# Terraform remote state data resources are
+# used to read the content of a Terraform state
+# file.
+#
+# This is common pattern in the `forms-deploy`
+# codebase, and is used to share information
+# between different Terraform roots without
+# having to do any external wiring of outputs
+# to inputs.
+#
+# In this instance, we will be sharing things
+# like the subnet and security groups ids that
+# are necessary for deploying to AWS ECS. 
+##
+data "terraform_remote_state" "review" {
+  backend = "s3"
+
+  config = {
+    key    = "review.tfstate"
+    bucket = "gds-forms-integration-tfstate"
+    region = "eu-west-2"
+
+    use_lockfile = true
+  }
+}

.review_apps/ecs_service.tf

@@ -0,0 +1,24 @@
+resource "aws_ecs_service" "app" {
+  #checkov:skip=CKV_AWS_332:We don't want to target "LATEST" and get a surprise when a new version is released.
+  name = "forms-runner-pr-${var.pull_request_number}"
+
+  cluster         = data.terraform_remote_state.review.outputs.ecs_cluster_id
+  task_definition = aws_ecs_task_definition.task.arn
+
+  desired_count                      = 1
+  deployment_maximum_percent         = "200"
+  deployment_minimum_healthy_percent = "100"
+  force_new_deployment               = true
+
+
+  launch_type      = "FARGATE"
+  platform_version = "1.4.0"
+
+  network_configuration {
+    subnets          = data.terraform_remote_state.review.outputs.private_subnet_ids
+    security_groups  = [data.terraform_remote_state.review.outputs.review_apps_security_group_id]
+    assign_public_ip = false
+  }
+
+  depends_on = [aws_ecs_task_definition.task]
+}