From 3eaf10a9c7c7915916a6aed374756002c11fec6a Mon Sep 17 00:00:00 2001 From: aidenvaines-bjss Date: Tue, 25 Feb 2025 11:23:57 +0000 Subject: [PATCH] CCM-8568 Adding TFDocs Manifest --- .github/workflows/cicd-1-pull-request.yaml | 6 +- .github/workflows/cicd-2-publish.yaml | 6 +- .github/workflows/cicd-3-deploy.yaml | 6 +- .github/workflows/stage-1-commit.yaml | 24 ++++++ .tool-versions | 1 + README.md | 1 + .../terraform/components/acct/README.md | 38 +++++++++ ...dule_s3bucket_lambda_function_artefacts.tf | 2 +- .../terraform/components/cdn/README.md | 50 +++++++++++ .../terraform/components/cdn/module_kms.tf | 2 +- ...e_lambda_rewrite_origin_branch_requests.tf | 2 +- ..._lambda_rewrite_viewer_trailing_slashes.tf | 2 +- .../components/cdn/module_s3bucket_cf_logs.tf | 2 +- scripts/config/pre-commit.yaml | 85 ++++++++++--------- scripts/config/terraform-docs.yml | 53 ++++++++++++ scripts/githooks/check-terraform-docs.sh | 50 +++++++++++ scripts/terraform/terraform-docs.sh | 82 ++++++++++++++++++ scripts/terraform/terraform.lib.sh | 1 - scripts/terraform/terraform.mk | 8 ++ 19 files changed, 367 insertions(+), 54 deletions(-) create mode 100644 infrastructure/terraform/components/acct/README.md create mode 100644 infrastructure/terraform/components/cdn/README.md create mode 100644 scripts/config/terraform-docs.yml create mode 100755 scripts/githooks/check-terraform-docs.sh create mode 100755 scripts/terraform/terraform-docs.sh diff --git a/.github/workflows/cicd-1-pull-request.yaml b/.github/workflows/cicd-1-pull-request.yaml index 02d7d67..b5cbfe4 100644 --- a/.github/workflows/cicd-1-pull-request.yaml +++ b/.github/workflows/cicd-1-pull-request.yaml @@ -40,9 +40,9 @@ jobs: echo "build_datetime=$datetime" >> $GITHUB_OUTPUT echo "build_timestamp=$(date --date=$datetime -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT echo "build_epoch=$(date --date=$datetime -u +'%s')" >> $GITHUB_OUTPUT - echo "nodejs_version=$(grep "^nodejs" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT - echo "python_version=$(grep "^nodejs" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT - echo "terraform_version=$(grep "^terraform" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "nodejs_version=$(grep "^nodejs " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "python_version=$(grep "^python " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "terraform_version=$(grep "^terraform " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT echo "version=$(head -n 1 .version 2> /dev/null || echo unknown)" >> $GITHUB_OUTPUT - name: "Check if pull request exists for this branch" id: pr_exists diff --git a/.github/workflows/cicd-2-publish.yaml b/.github/workflows/cicd-2-publish.yaml index 5717ee9..8bad3db 100644 --- a/.github/workflows/cicd-2-publish.yaml +++ b/.github/workflows/cicd-2-publish.yaml @@ -30,9 +30,9 @@ jobs: echo "build_datetime=$datetime" >> $GITHUB_OUTPUT echo "build_timestamp=$(date --date=$datetime -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT echo "build_epoch=$(date --date=$datetime -u +'%s')" >> $GITHUB_OUTPUT - echo "nodejs_version=$(grep "^nodejs" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT - echo "python_version=$(grep "^nodejs" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT - echo "terraform_version=$(grep "^terraform" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "nodejs_version=$(grep "^nodejs " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "python_version=$(grep "^python " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "terraform_version=$(grep "^terraform " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT # TODO: Get the version, but it may not be the .version file as this should come from the CI/CD Pull Request Workflow echo "version=$(head -n 1 .version 2> /dev/null || echo unknown)" >> $GITHUB_OUTPUT - name: "List variables" diff --git a/.github/workflows/cicd-3-deploy.yaml b/.github/workflows/cicd-3-deploy.yaml index 1282fb0..b950974 100644 --- a/.github/workflows/cicd-3-deploy.yaml +++ b/.github/workflows/cicd-3-deploy.yaml @@ -66,9 +66,9 @@ jobs: echo "build_datetime=$datetime" >> $GITHUB_OUTPUT echo "build_timestamp=$(date --date=$datetime -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT echo "build_epoch=$(date --date=$datetime -u +'%s')" >> $GITHUB_OUTPUT - echo "nodejs_version=$(grep "^nodejs" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT - echo "python_version=$(grep "^nodejs" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT - echo "terraform_version=$(grep "^terraform" .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "nodejs_version=$(grep "^nodejs " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "python_version=$(grep "^python " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT + echo "terraform_version=$(grep "^terraform " .tool-versions | cut -f2 -d' ')" >> $GITHUB_OUTPUT # TODO: Get the version, but it may not be the .version file as this should come from the CI/CD Pull Request Workflow echo "version=$(head -n 1 .version 2> /dev/null || echo unknown)" >> $GITHUB_OUTPUT echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT diff --git a/.github/workflows/stage-1-commit.yaml b/.github/workflows/stage-1-commit.yaml index ed14a61..72070af 100644 --- a/.github/workflows/stage-1-commit.yaml +++ b/.github/workflows/stage-1-commit.yaml @@ -66,6 +66,30 @@ jobs: fetch-depth: 0 # Full history is needed to compare branches - name: "Check Markdown format" uses: ./.github/actions/check-markdown-format + terraform-docs: + name: "Run terraform-docs" + runs-on: ubuntu-latest + needs: detect-terraform-changes + if: needs.detect-terraform-changes.outputs.terraform_changed == 'true' + permissions: + contents: write + steps: + - name: "Checkout code" + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Full history is needed to compare branches + - name: "Check to see if Terraform Docs are up-to-date" + run: | + make terraform-docs + - name: "Stage changes" + run: | + git add infrastructure/terraform/**/*.md + - name: "Check for changes in Terraform Docs" + run: | + if git diff --cached --name-only | grep -qE '\.md$'; then + echo "Markdown files have changed. Please run 'make terraform-docs' and commit the changes." + exit 1 + fi check-english-usage: name: "Check English usage" runs-on: ubuntu-latest diff --git a/.tool-versions b/.tool-versions index 0e6e096..2380db2 100644 --- a/.tool-versions +++ b/.tool-versions @@ -2,6 +2,7 @@ pre-commit 3.6.0 terraform 1.7.0 +terraform-docs 0.19.0 tfsec 1.28.10 # ============================================================================== diff --git a/README.md b/README.md index 38722e8..196bd84 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ Make use of this repository template to expedite your project setup and enhance - [Contributing](#contributing) - [Contacts](#contacts) - [Licence](#licence) + - [Shared Terraform Modules](#shared-terraform-modules) ## Documentation diff --git a/infrastructure/terraform/components/acct/README.md b/infrastructure/terraform/components/acct/README.md new file mode 100644 index 0000000..14c8e7d --- /dev/null +++ b/infrastructure/terraform/components/acct/README.md @@ -0,0 +1,38 @@ + + + + +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.9.0 | +| [aws](#requirement\_aws) | ~> 5.50 | +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [aws\_account\_id](#input\_aws\_account\_id) | The AWS Account ID (numeric) | `string` | n/a | yes | +| [component](#input\_component) | The variable encapsulating the name of this component | `string` | `"acct"` | no | +| [default\_tags](#input\_default\_tags) | A map of default tags to apply to all taggable resources within the component | `map(string)` | `{}` | no | +| [environment](#input\_environment) | The name of the tfscaffold environment | `string` | n/a | yes | +| [group](#input\_group) | The group variables are being inherited from (often synonmous with account short-name) | `string` | n/a | yes | +| [log\_retention\_in\_days](#input\_log\_retention\_in\_days) | The retention period in days for the Cloudwatch Logs events to be retained, default of 0 is indefinite | `number` | `0` | no | +| [observability\_account\_id](#input\_observability\_account\_id) | The Observability Account ID that needs access | `string` | n/a | yes | +| [project](#input\_project) | The name of the tfscaffold project | `string` | n/a | yes | +| [region](#input\_region) | The AWS Region | `string` | n/a | yes | +| [root\_domain\_name](#input\_root\_domain\_name) | The service's root DNS root nameespace, like nonprod.nhsnotify.national.nhs.uk | `string` | `"nonprod.nhsnotify.national.nhs.uk"` | no | +## Modules + +| Name | Source | Version | +|------|--------|---------| +| [s3bucket\_lambda\_artefacts](#module\_s3bucket\_lambda\_artefacts) | git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/s3bucket | v1.0.8 | +## Outputs + +| Name | Description | +|------|-------------| +| [dns\_zone](#output\_dns\_zone) | n/a | +| [s3\_buckets](#output\_s3\_buckets) | n/a | + + + diff --git a/infrastructure/terraform/components/acct/module_s3bucket_lambda_function_artefacts.tf b/infrastructure/terraform/components/acct/module_s3bucket_lambda_function_artefacts.tf index 46e65cb..afa5e73 100644 --- a/infrastructure/terraform/components/acct/module_s3bucket_lambda_function_artefacts.tf +++ b/infrastructure/terraform/components/acct/module_s3bucket_lambda_function_artefacts.tf @@ -1,5 +1,5 @@ module "s3bucket_lambda_artefacts" { - source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/s3bucket?ref=v1.0.0" + source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/s3bucket?ref=v1.0.8" providers = { aws = aws.us-east-1 } diff --git a/infrastructure/terraform/components/cdn/README.md b/infrastructure/terraform/components/cdn/README.md new file mode 100644 index 0000000..11a43f0 --- /dev/null +++ b/infrastructure/terraform/components/cdn/README.md @@ -0,0 +1,50 @@ + + + + +## Requirements + +| Name | Version | +|------|---------| +| [terraform](#requirement\_terraform) | >= 1.9.0 | +| [aws](#requirement\_aws) | ~> 5.50 | +| [github](#requirement\_github) | ~> 6.0 | +## Inputs + +| Name | Description | Type | Default | Required | +|------|-------------|------|---------|:--------:| +| [AMPLIFY\_BASIC\_AUTH\_SECRET](#input\_AMPLIFY\_BASIC\_AUTH\_SECRET) | Secret key/password to use for amplify microservice headers - This is entended to be read from CI variables and not commited to any codebase | `string` | `"unset"` | no | +| [amplify\_microservice\_routes](#input\_amplify\_microservice\_routes) | An object representing the amplify microservice routing configration | 
list(object({
    service_prefix  = string,
    service_csi     = string,
    root_dns_record = string,
  }))
| `[]` | no | +| [aws\_account\_id](#input\_aws\_account\_id) | The AWS Account ID (numeric) | `string` | n/a | yes | +| [cdn\_sans](#input\_cdn\_sans) | Aliases to associate with CDN | `list(string)` | `[]` | no | +| [cms\_origin](#input\_cms\_origin) | Object to specifiy static domains for CDN | 
object({
    domain_name = string,
    origin_path = string,
    origin_id   = string
  })
| 
{
  "domain_name": "nhsdigital.github.io",
  "origin_id": "github-nhs-notify-web-cms",
  "origin_path": "/nhs-notify-web-cms-dev"
}
| no | +| [component](#input\_component) | The variable encapsulating the name of this component | `string` | `"cdn"` | no | +| [default\_tags](#input\_default\_tags) | A map of default tags to apply to all taggable resources within the component | `map(string)` | `{}` | no | +| [enable\_github\_actions\_ip\_access](#input\_enable\_github\_actions\_ip\_access) | Should the Github actions runner IP addresses be permitted access to this distribution. This should not be enabled in production environments | `bool` | `false` | no | +| [environment](#input\_environment) | The name of the tfscaffold environment | `string` | n/a | yes | +| [force\_lambda\_code\_deploy](#input\_force\_lambda\_code\_deploy) | If the lambda package in s3 has the same commit id tag as the terraform build branch, the lambda will not update automatically. Set to True if making changes to Lambda code from on the same commit for example during development | `bool` | `false` | no | +| [group](#input\_group) | The group variables are being inherited from (often synonmous with account short-name) | `string` | n/a | yes | +| [kms\_deletion\_window](#input\_kms\_deletion\_window) | When a kms key is deleted, how long should it wait in the pending deletion state? | `string` | `"30"` | no | +| [log\_level](#input\_log\_level) | The log level to be used in lambda functions within the component. Any log with a lower severity than the configured value will not be logged: https://docs.python.org/3/library/logging.html#levels | `string` | `"INFO"` | no | +| [log\_retention\_in\_days](#input\_log\_retention\_in\_days) | The retention period in days for the Cloudwatch Logs events to be retained, default of 0 is indefinite | `number` | `0` | no | +| [parent\_acct\_environment](#input\_parent\_acct\_environment) | Name of the environment responsible for the acct resources used, affects things like DNS zone. Useful for named dev environments | `string` | `"main"` | no | +| [project](#input\_project) | The name of the tfscaffold project | `string` | n/a | yes | +| [region](#input\_region) | The AWS Region | `string` | n/a | yes | +| [waf\_rate\_limit\_cdn](#input\_waf\_rate\_limit\_cdn) | The rate limit is the maximum number of CDN requests from a single IP address that are allowed in a five-minute period | `number` | `20000` | no | +## Modules + +| Name | Source | Version | +|------|--------|---------| +| [kms](#module\_kms) | git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/kms | v1.0.8 | +| [lambda\_rewrite\_origin\_branch\_requests](#module\_lambda\_rewrite\_origin\_branch\_requests) | git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/lambda | v1.0.8 | +| [lambda\_rewrite\_viewer\_trailing\_slashes](#module\_lambda\_rewrite\_viewer\_trailing\_slashes) | git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/lambda | v1.0.8 | +| [s3bucket\_cf\_logs](#module\_s3bucket\_cf\_logs) | git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/s3bucket | v1.0.8 | +## Outputs + +| Name | Description | +|------|-------------| +| [cloudfront\_distribution\_aliases](#output\_cloudfront\_distribution\_aliases) | Cloudfront distribution custom alias URLs | +| [cloudfront\_distribution\_url](#output\_cloudfront\_distribution\_url) | Cloudfront distribution URL | + + + diff --git a/infrastructure/terraform/components/cdn/module_kms.tf b/infrastructure/terraform/components/cdn/module_kms.tf index 7feaa6f..333049d 100644 --- a/infrastructure/terraform/components/cdn/module_kms.tf +++ b/infrastructure/terraform/components/cdn/module_kms.tf @@ -1,5 +1,5 @@ module "kms" { - source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/kms?ref=v1.0.0" + source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/kms?ref=v1.0.8" providers = { aws = aws.us-east-1 } diff --git a/infrastructure/terraform/components/cdn/module_lambda_rewrite_origin_branch_requests.tf b/infrastructure/terraform/components/cdn/module_lambda_rewrite_origin_branch_requests.tf index f364010..c2e996c 100644 --- a/infrastructure/terraform/components/cdn/module_lambda_rewrite_origin_branch_requests.tf +++ b/infrastructure/terraform/components/cdn/module_lambda_rewrite_origin_branch_requests.tf @@ -1,5 +1,5 @@ module "lambda_rewrite_origin_branch_requests" { - source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/lambda?ref=v1.0.2" + source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/lambda?ref=v1.0.9" providers = { aws = aws.us-east-1 diff --git a/infrastructure/terraform/components/cdn/module_lambda_rewrite_viewer_trailing_slashes.tf b/infrastructure/terraform/components/cdn/module_lambda_rewrite_viewer_trailing_slashes.tf index 20e5635..cdcdc16 100644 --- a/infrastructure/terraform/components/cdn/module_lambda_rewrite_viewer_trailing_slashes.tf +++ b/infrastructure/terraform/components/cdn/module_lambda_rewrite_viewer_trailing_slashes.tf @@ -1,5 +1,5 @@ module "lambda_rewrite_viewer_trailing_slashes" { - source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/lambda?ref=v1.0.2" + source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/lambda?ref=v1.0.9" providers = { aws = aws.us-east-1 diff --git a/infrastructure/terraform/components/cdn/module_s3bucket_cf_logs.tf b/infrastructure/terraform/components/cdn/module_s3bucket_cf_logs.tf index ca26439..403bc54 100644 --- a/infrastructure/terraform/components/cdn/module_s3bucket_cf_logs.tf +++ b/infrastructure/terraform/components/cdn/module_s3bucket_cf_logs.tf @@ -1,5 +1,5 @@ module "s3bucket_cf_logs" { - source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/s3bucket?ref=v1.0.0" + source = "git::https://github.com/NHSDigital/nhs-notify-shared-modules.git//infrastructure/modules/s3bucket?ref=v1.0.9" providers = { aws = aws.us-east-1 } diff --git a/scripts/config/pre-commit.yaml b/scripts/config/pre-commit.yaml index 37ca637..da31ce7 100644 --- a/scripts/config/pre-commit.yaml +++ b/scripts/config/pre-commit.yaml @@ -1,40 +1,47 @@ repos: -- repo: local - hooks: - - id: scan-secrets - name: Scan secrets - entry: ./scripts/githooks/scan-secrets.sh - args: ["check=staged-changes"] - language: script - pass_filenames: false -- repo: local - hooks: - - id: check-file-format - name: Check file format - entry: ./scripts/githooks/check-file-format.sh - args: ["check=staged-changes"] - language: script - pass_filenames: false -- repo: local - hooks: - - id: check-markdown-format - name: Check Markdown format - entry: ./scripts/githooks/check-markdown-format.sh - args: ["check=staged-changes"] - language: script - pass_filenames: false -- repo: local - hooks: - - id: check-english-usage - name: Check English usage - entry: ./scripts/githooks/check-english-usage.sh - args: ["check=staged-changes"] - language: script - pass_filenames: false -- repo: local - hooks: - - id: lint-terraform - name: Lint Terraform - entry: ./scripts/githooks/check-terraform-format.sh - language: script - pass_filenames: false + - repo: local + hooks: + - id: scan-secrets + name: Scan secrets + entry: ./scripts/githooks/scan-secrets.sh + args: ["check=staged-changes"] + language: script + pass_filenames: false + - repo: local + hooks: + - id: check-file-format + name: Check file format + entry: ./scripts/githooks/check-file-format.sh + args: ["check=staged-changes"] + language: script + pass_filenames: false + - repo: local + hooks: + - id: check-markdown-format + name: Check Markdown format + entry: ./scripts/githooks/check-markdown-format.sh + args: ["check=staged-changes"] + language: script + pass_filenames: false + - repo: local + hooks: + - id: check-english-usage + name: Check English usage + entry: ./scripts/githooks/check-english-usage.sh + args: ["check=staged-changes"] + language: script + pass_filenames: false + - repo: local + hooks: + - id: lint-terraform + name: Lint Terraform + entry: ./scripts/githooks/check-terraform-format.sh + language: script + pass_filenames: false + - repo: local + hooks: + - id: generate-terraform-docs + name: Generate Terraform Docs + entry: ./scripts/githooks/check-terraform-docs.sh + language: script + pass_filenames: false diff --git a/scripts/config/terraform-docs.yml b/scripts/config/terraform-docs.yml new file mode 100644 index 0000000..e49d91f --- /dev/null +++ b/scripts/config/terraform-docs.yml @@ -0,0 +1,53 @@ +formatter: 'markdown' # this is required + +version: '' + +recursive: + enabled: false + +sections: + hide: [] + show: [] + +content: |- + {{ .Header }} + {{ .Requirements }} + {{ .Inputs }} + {{ .Modules }} + {{ .Outputs }} + {{ .Footer }} + +output: + file: 'README.md' + mode: inject + template: |- + + + + {{ .Content }} + + + + +output-values: + enabled: false + from: '' + +sort: + enabled: true + by: name + +settings: + anchor: true + color: true + default: true + description: false + escape: true + hide-empty: false + html: true + indent: 2 + lockfile: true + read-comments: true + required: true + sensitive: true + type: true diff --git a/scripts/githooks/check-terraform-docs.sh b/scripts/githooks/check-terraform-docs.sh new file mode 100755 index 0000000..69210ce --- /dev/null +++ b/scripts/githooks/check-terraform-docs.sh @@ -0,0 +1,50 @@ +#!/bin/bash + +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/nhs-england-tools/repository-template). Raise a PR instead. + +set -euo pipefail + +# Pre-commit git hook to check Terraform documentation. +# +# Usage: +# $ [options] ./check-terraform-documentation.sh +# +# Options: +# VERBOSE=true # Show all the executed commands, default is 'false' + +# ============================================================================== + +function main() { + + cd "$(git rev-parse --show-toplevel)" + + terraform-docs +} + +# Generate Terraform documentation. +# Arguments (provided as environment variables): +# check_only=[do not format, run check only] +function terraform-docs() { + + make terraform-docs + git add infrastructure/terraform/**/*.md +} + +# ============================================================================== + +function is-arg-true() { + + if [[ "$1" =~ ^(true|yes|y|on|1|TRUE|YES|Y|ON)$ ]]; then + return 0 + else + return 1 + fi +} + +# ============================================================================== + +is-arg-true "${VERBOSE:-false}" && set -x + +main "$@" + +exit 0 diff --git a/scripts/terraform/terraform-docs.sh b/scripts/terraform/terraform-docs.sh new file mode 100755 index 0000000..446d30d --- /dev/null +++ b/scripts/terraform/terraform-docs.sh @@ -0,0 +1,82 @@ +#!/usr/bin/env bash + +# WARNING: Please DO NOT edit this file! It is maintained in the Repository Template (https://github.com/NHSDigital/nhs-notify-repository-template). Raise a PR instead. + +set -euo pipefail + +# Terraform-docs command wrapper. It will run the command natively if terraform-docs is +# installed, otherwise it will run it in a Docker container. +# Run terraform-docs for generating Terraform module documentation code. +# +# Usage: +# $ ./terraform-docs.sh [directory] +# ============================================================================== + +function main() { + + cd "$(git rev-parse --show-toplevel)" + + local dir_to_document=${1:-.} + + if command -v terraform-docs > /dev/null 2>&1 && ! is-arg-true "${FORCE_USE_DOCKER:-false}"; then + # shellcheck disable=SC2154 + run-terraform-docs-natively "$dir_to_document" + else + run-terraform-docs-in-docker "$dir_to_document" + fi +} + +# Run terraform-docs on the specified directory. +# Arguments: +# $1 - Directory to document +function run-terraform-docs-natively() { + + local dir_to_scan="$1" + echo "Terraform-docs found locally, running natively" + if [ -d "$dir_to_scan" ]; then + echo "Running Terraform-docs on directory: $dir_to_scan" + terraform-docs \ + -c scripts/config/terraform-docs.yml \ + --output-file README.md \ + "$dir_to_scan" + fi +} + +function run-terraform-docs-in-docker() { + + # shellcheck disable=SC1091 + source ./scripts/docker/docker.lib.sh + local dir_to_scan="$1" + + # shellcheck disable=SC2155 + local image=$(name=quay.io/terraform-docs/terraform-docs docker-get-image-version-and-pull) + # shellcheck disable=SC2086 + echo "Terraform-docs not found locally, running in Docker Container" + echo "Running Terraform-docs on directory: $dir_to_scan" + docker run --rm --platform linux/amd64 \ + --volume "$PWD":/workdir \ + --workdir /workdir \ + "$image" \ + -c scripts/config/terraform-docs.yml \ + --output-file README.md \ + "$dir_to_scan" + +} +# ============================================================================== + +function is-arg-true() { + + if [[ "$1" =~ ^(true|yes|y|on|1|TRUE|YES|Y|ON)$ ]]; then + return 0 + else + return 1 + fi +} + +# ============================================================================== + +is-arg-true "${VERBOSE:-false}" && set -x + +main "$@" + +exit 0 diff --git a/scripts/terraform/terraform.lib.sh b/scripts/terraform/terraform.lib.sh index d94213e..1f0aeb4 100644 --- a/scripts/terraform/terraform.lib.sh +++ b/scripts/terraform/terraform.lib.sh @@ -58,7 +58,6 @@ function terraform-fmt() { terraform fmt --recursive "${d}" fi done - } # Validate Terraform code. diff --git a/scripts/terraform/terraform.mk b/scripts/terraform/terraform.mk index 5ffbba2..518dcf0 100644 --- a/scripts/terraform/terraform.mk +++ b/scripts/terraform/terraform.mk @@ -63,6 +63,13 @@ terraform-sec: # TFSEC check against Terraform files - optional: terraform_dir|d --tfvars-file infrastructure/terraform/etc/env_eu-west-2_main.tfvars \ --config-file scripts/config/tfsec.yaml +terraform-docs: # Terraform-docs check against Terraform files - optional: terraform_dir|dir=[path to a directory where the command will be executed, relative to the project's top-level directory, default is one of the module variables or the example directory, if not set], terraform_opts|opts=[options to pass to the Terraform fmt command, default is '-recursive'] @Quality + for dir in ./infrastructure/terraform/components/* ./infrastructure/terraform/modules/*; do \ + if [ -d "$$dir" ]; then \ + ./scripts/terraform/terraform-docs.sh $$dir; \ + fi \ + done + # ============================================================================== # Module tests and examples - please DO NOT edit this section! @@ -97,6 +104,7 @@ ${VERBOSE}.SILENT: \ terraform-example-destroy-aws-infrastructure \ terraform-example-provision-aws-infrastructure \ terraform-fmt \ + terraform-docs \ terraform-init \ terraform-install \ terraform-plan \