Skip to content

Commit 9cebc3e

Browse files
aidenvaines-cgiaidenvaines-cgi
committed
CCM-8568 TFDocsAutomation
1 parent 031a0c8 commit 9cebc3e

File tree

10 files changed

+227
-1
lines changed

10 files changed

+227
-1
lines changed

‎.github/workflows/stage-1-commit.yaml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,32 @@ jobs:
6666
fetch-depth: 0 # Full history is needed to compare branches
6767
- name: "Check Markdown format"
6868
uses: ./.github/actions/check-markdown-format
69+
terraform-docs:
70+
name: "Run terraform-docs"
71+
runs-on: ubuntu-latest
72+
needs: detect-terraform-changes
73+
if: needs.detect-terraform-changes.outputs.terraform_changed == 'true'
74+
permissions:
75+
contents: write
76+
steps:
77+
- name: "Checkout code"
78+
uses: actions/checkout@v4
79+
with:
80+
fetch-depth: 0 # Full history is needed to compare branches
81+
- name: "Check to see if Terraform Docs are up-to-date"
82+
run: |
83+
for dir in $(find infrastructure/terraform/{components,modules} -mindepth 1 -maxdepth 1 -type d); do
84+
make terraform-docs dir=$dir
85+
done
86+
- name: "Stage changes"
87+
run: |
88+
git add infrastructure/terraform/**/*.md
89+
- name: "Check for changes in Terraform Docs"
90+
run: |
91+
if git diff --cached --name-only | grep -qE '\.md$'; then
92+
echo "Markdown files have changed. Please run 'make terraform-docs' and commit the changes."
93+
exit 1
94+
fi
6995
check-english-usage:
7096
name: "Check English usage"
7197
runs-on: ubuntu-latest

‎.tool-versions‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ act 0.2.64
22
gitleaks 8.18.4
33
pre-commit 3.6.0
44
terraform 1.9.2
5+
terraform-docs 0.19.0
56
tfsec 1.28.10
67
vale 3.6.0
78

‎infrastructure/images/.gitkeep‎

Whitespace-only changes.

‎infrastructure/modules/.gitkeep‎

Whitespace-only changes.

‎scripts/config/pre-commit.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,10 @@ repos:
5757
entry: ./scripts/githooks/check-terraform-format.sh
5858
language: script
5959
pass_filenames: false
60+
- repo: local
61+
hooks:
62+
- id: generate-terraform-docs
63+
name: Generate Terraform Docs
64+
entry: ./scripts/githooks/check-terraform-docs.sh
65+
language: script
66+
pass_filenames: false

‎scripts/config/terraform-docs.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
formatter: 'markdown' # this is required
2+
3+
version: ''
4+
5+
recursive:
6+
enabled: false
7+
8+
sections:
9+
hide: []
10+
show: []
11+
12+
content: |-
13+
{{ .Header }}
14+
{{ .Requirements }}
15+
{{ .Inputs }}
16+
{{ .Modules }}
17+
{{ .Outputs }}
18+
{{ .Footer }}
19+
20+
output:
21+
file: 'README.md'
22+
mode: inject
23+
template: |-
24+
<!-- BEGIN_TF_DOCS -->
25+
{{ .Content }}
26+
<!-- END_TF_DOCS -->
27+
28+
output-values:
29+
enabled: false
30+
from: ''
31+
32+
sort:
33+
enabled: true
34+
by: name
35+
36+
settings:
37+
anchor: true
38+
color: true
39+
default: true
40+
description: false
41+
escape: true
42+
hide-empty: false
43+
html: true
44+
indent: 2
45+
lockfile: true
46+
read-comments: true
47+
required: true
48+
sensitive: true
49+
type: true

‎scripts/githooks/check-terraform-docs.sh‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#!/bin/bash
2+
3+
# 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.
4+
5+
set -euo pipefail
6+
7+
# Pre-commit git hook to check Terraform documentation.
8+
#
9+
# Usage:
10+
# $ [options] ./check-terraform-documentation.sh
11+
#
12+
# Options:
13+
# VERBOSE=true # Show all the executed commands, default is 'false'
14+
15+
# ==============================================================================
16+
17+
function main() {
18+
19+
cd "$(git rev-parse --show-toplevel)"
20+
21+
terraform-docs
22+
}
23+
24+
# Generate Terraform documentation.
25+
# Arguments (provided as environment variables):
26+
# check_only=[do not format, run check only]
27+
function terraform-docs() {
28+
29+
# shellcheck disable=SC2044
30+
for dir in $(find infrastructure/terraform/{components,modules} -mindepth 1 -maxdepth 1 -type d); do
31+
make terraform-docs dir="${dir}"
32+
done
33+
34+
git add infrastructure/terraform/**/*.md
35+
}
36+
37+
# ==============================================================================
38+
39+
function is-arg-true() {
40+
41+
if [[ "$1" =~ ^(true|yes|y|on|1|TRUE|YES|Y|ON)$ ]]; then
42+
return 0
43+
else
44+
return 1
45+
fi
46+
}
47+
48+
# ==============================================================================
49+
50+
is-arg-true "${VERBOSE:-false}" && set -x
51+
52+
main "$@"
53+
54+
exit 0

‎scripts/terraform/terraform-docs.sh‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
#!/usr/bin/env bash
2+
3+
# 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.
4+
5+
set -euo pipefail
6+
7+
# Terraform-docs command wrapper. It will run the command natively if terraform-docs is
8+
# installed, otherwise it will run it in a Docker container.
9+
# Run terraform-docs for generating Terraform module documentation code.
10+
#
11+
# Usage:
12+
# $ ./terraform-docs.sh [directory]
13+
# ==============================================================================
14+
15+
function main() {
16+
17+
cd "$(git rev-parse --show-toplevel)"
18+
19+
local dir_to_document=${1:-.}
20+
21+
if command -v terraform-docs > /dev/null 2>&1 && ! is-arg-true "${FORCE_USE_DOCKER:-false}"; then
22+
# shellcheck disable=SC2154
23+
run-terraform-docs-natively "$dir_to_document"
24+
else
25+
run-terraform-docs-in-docker "$dir_to_document"
26+
fi
27+
}
28+
29+
# Run terraform-docs on the specified directory.
30+
# Arguments:
31+
# $1 - Directory to document
32+
function run-terraform-docs-natively() {
33+
34+
local dir_to_scan="$1"
35+
echo "Terraform-docs found locally, running natively"
36+
if [ -d "$dir_to_scan" ]; then
37+
echo "Running Terraform-docs on directory: $dir_to_scan"
38+
terraform-docs \
39+
-c scripts/config/terraform-docs.yml \
40+
--output-file README.md \
41+
"$dir_to_scan"
42+
fi
43+
}
44+
45+
function run-terraform-docs-in-docker() {
46+
47+
# shellcheck disable=SC1091
48+
source ./scripts/docker/docker.lib.sh
49+
local dir_to_scan="$1"
50+
51+
# shellcheck disable=SC2155
52+
local image=$(name=quay.io/terraform-docs/terraform-docs docker-get-image-version-and-pull)
53+
# shellcheck disable=SC2086
54+
echo "Terraform-docs not found locally, running in Docker Container"
55+
echo "Running Terraform-docs on directory: $dir_to_scan"
56+
docker run --rm --platform linux/amd64 \
57+
--volume "$PWD":/workdir \
58+
--workdir /workdir \
59+
"$image" \
60+
-c scripts/config/terraform-docs.yml \
61+
--output-file README.md \
62+
"$dir_to_scan"
63+
64+
}
65+
# ==============================================================================
66+
67+
function is-arg-true() {
68+
69+
if [[ "$1" =~ ^(true|yes|y|on|1|TRUE|YES|Y|ON)$ ]]; then
70+
return 0
71+
else
72+
return 1
73+
fi
74+
}
75+
76+
# ==============================================================================
77+
78+
is-arg-true "${VERBOSE:-false}" && set -x
79+
80+
main "$@"
81+
82+
exit 0

‎scripts/terraform/terraform.lib.sh‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,6 @@ function terraform-fmt() {
5858
terraform fmt --recursive "${d}"
5959
fi
6060
done
61-
6261
}
6362

6463
# Validate Terraform code.

‎scripts/terraform/terraform.mk‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,13 @@ terraform-sec: # TFSEC check against Terraform files - optional: terraform_dir|d
6363
--tfvars-file infrastructure/terraform/etc/env_eu-west-2_main.tfvars \
6464
--config-file scripts/config/tfsec.yaml
6565

66+
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
67+
for dir in ./infrastructure/terraform/components/* ./infrastructure/terraform/modules/*; do \
68+
if [ -d "$$dir" ]; then \
69+
./scripts/terraform/terraform-docs.sh $$dir; \
70+
fi \
71+
done
72+
6673
# ==============================================================================
6774
# Module tests and examples - please DO NOT edit this section!
6875

@@ -97,6 +104,7 @@ ${VERBOSE}.SILENT: \
97104
terraform-example-destroy-aws-infrastructure \
98105
terraform-example-provision-aws-infrastructure \
99106
terraform-fmt \
107+
terraform-docs \
100108
terraform-init \
101109
terraform-install \
102110
terraform-plan \

0 commit comments

Comments
 (0)