From 1a6fc277917dbe45aa006fda2d66fbe6c384fcee Mon Sep 17 00:00:00 2001 From: Matthew Mellor Date: Wed, 4 Mar 2026 22:12:14 -0600 Subject: [PATCH] docs(standards): add terragrunt to terraform standards Add terragrunt hclfmt as companion formatter, configuration section, Makefile targets, and pre-commit hook guidance to terraform standards. Co-Authored-By: Claude Opus 4.6 --- content/docs/standards/_index.md | 8 ++++---- content/docs/standards/terraform.md | 23 +++++++++++++++++++++-- 2 files changed, 25 insertions(+), 6 deletions(-) diff --git a/content/docs/standards/_index.md b/content/docs/standards/_index.md index daeb0e8..3db0554 100644 --- a/content/docs/standards/_index.md +++ b/content/docs/standards/_index.md @@ -14,7 +14,7 @@ The following table shows the default tool for each concern per language. These | Concern | Python | Bash | Terraform | Ansible | Ruby | Go | JavaScript | Rust | |---|---|---|---|---|---|---|---|---| | Linter | ruff | shellcheck | tflint | ansible-lint | rubocop, reek | golangci-lint | eslint | clippy | -| Formatter | ruff format | shfmt | terraform fmt | -- | rubocop | gofumpt | prettier | rustfmt | +| Formatter | ruff format | shfmt | terraform fmt, terragrunt hclfmt | -- | rubocop | gofumpt | prettier | rustfmt | | Security | bandit, semgrep | -- | tfsec, checkov | -- | brakeman, bundler-audit | govulncheck | npm audit | cargo-audit, cargo-deny | | Tests | pytest | bats | terratest | molecule | rspec | go test | vitest | cargo test | | Type Check | mypy | -- | -- | -- | sorbet | -- | tsc | -- | @@ -30,8 +30,8 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev | Target | What It Runs | |---|---| | `make lint` | ruff check, shellcheck, tflint, ansible-lint, mypy, rubocop, reek, golangci-lint, eslint, tsc, clippy | -| `make format` | ruff format --check, shfmt -d, terraform fmt -check, rubocop --check, gofumpt -d, prettier --check, cargo fmt --check | -| `make fix` | ruff format, shfmt -w, terraform fmt, rubocop -a, gofumpt -w, prettier --write, cargo fmt | +| `make format` | ruff format --check, shfmt -d, terraform fmt -check, terragrunt hclfmt --terragrunt-check, rubocop --check, gofumpt -d, prettier --check, cargo fmt --check | +| `make fix` | ruff format, shfmt -w, terraform fmt, terragrunt hclfmt, rubocop -a, gofumpt -w, prettier --write, cargo fmt | | `make test` | pytest, bats, terratest, molecule, rspec, go test, vitest, cargo test | | `make security` | bandit, semgrep, tfsec, checkov, brakeman, bundler-audit, govulncheck, npm audit, cargo-audit, cargo-deny | | `make scan` | trivy, gitleaks (universal -- all projects) | @@ -44,7 +44,7 @@ Each Makefile target runs the relevant tools for all languages declared in `.dev - [Coding Practices](/docs/standards/practices/) -- principles, error handling, testing, git workflow - [Python Standards](/docs/standards/python/) -- ruff, bandit, semgrep, pytest, mypy - [Bash Standards](/docs/standards/bash/) -- shellcheck, shfmt, bats -- [Terraform Standards](/docs/standards/terraform/) -- tflint, terraform fmt, tfsec, checkov, terratest, terraform-docs +- [Terraform Standards](/docs/standards/terraform/) -- tflint, terraform fmt, terragrunt hclfmt, tfsec, checkov, terratest, terraform-docs - [Ansible Standards](/docs/standards/ansible/) -- ansible-lint, molecule - [Ruby Standards](/docs/standards/ruby/) -- rubocop, brakeman, bundler-audit, rspec, reek, sorbet - [Go Standards](/docs/standards/go/) -- golangci-lint, gofumpt, govulncheck, go test diff --git a/content/docs/standards/terraform.md b/content/docs/standards/terraform.md index 92f34d2..8f852eb 100644 --- a/content/docs/standards/terraform.md +++ b/content/docs/standards/terraform.md @@ -2,7 +2,7 @@ title: "Terraform Standards" linkTitle: "Terraform" weight: 30 -description: "Terraform tooling standards: tflint, terraform fmt, tfsec, checkov, terratest, and terraform-docs." +description: "Terraform tooling standards: tflint, terraform fmt, terragrunt hclfmt, tfsec, checkov, terratest, and terraform-docs." --- ## Tools @@ -11,6 +11,7 @@ description: "Terraform tooling standards: tflint, terraform fmt, tfsec, checkov |---|---|---| | Linting | tflint | Terraform-specific linting rules | | Formatting | terraform fmt | Canonical HCL formatting | +| Formatting | terragrunt hclfmt | Terragrunt HCL formatting (when `terragrunt.hcl` present) | | Security | tfsec | Terraform-focused security scanning | | Security | checkov | Policy-as-code scanning | | Testing | terratest | Go-based infrastructure testing | @@ -110,6 +111,20 @@ func TestTerraformModule(t *testing.T) { The `tests/` directory must contain a `go.mod` file for the test module. +### terragrunt hclfmt + +No config file required. Terragrunt is a companion tool that runs automatically when `terragrunt.hcl` files are detected in the project. It formats Terragrunt HCL files to a canonical style. + +```bash +# Check formatting (exits non-zero if files need formatting) +terragrunt hclfmt --terragrunt-check + +# Apply formatting +terragrunt hclfmt +``` + +Projects that do not use Terragrunt are unaffected — the formatter is silently skipped when no `terragrunt.hcl` files exist. + ### terraform-docs No config file required for default operation. Generates markdown documentation from Terraform module inputs, outputs, and descriptions. @@ -134,6 +149,8 @@ terraform-docs markdown table . > README.md |---|---|---| | `make lint` | `tflint --recursive` | Lint all Terraform configurations | | `make format` | `terraform fmt -check -recursive` | Check formatting (no changes) | +| `make format` | `terragrunt hclfmt --terragrunt-check` | Check Terragrunt formatting (when `terragrunt.hcl` present) | +| `make fix` | `terragrunt hclfmt` | Apply Terragrunt formatting fixes (when `terragrunt.hcl` present) | | `make security` | `tfsec .` | Security scanning for Terraform | | `make security` | `checkov -d .` | Policy-as-code scanning | | `make test` | `cd tests && go test -v -timeout 30m` | Run terratest suite | @@ -153,6 +170,8 @@ repos: hooks: - id: terraform_fmt - id: terraform_tflint + # Uncomment if using Terragrunt: + # - id: terragrunt_fmt ``` ### CI-Only (too slow for local hooks) @@ -164,7 +183,7 @@ repos: ## Notes -- **`terraform fmt` is the only accepted formatter.** Do not use third-party HCL formatters. +- **`terraform fmt` is the only accepted formatter** for `.tf` files. Do not use third-party HCL formatters. Terragrunt HCL files (`terragrunt.hcl`) are formatted by `terragrunt hclfmt`. - **Both `tfsec` and `checkov` run as part of `make security`.** They are complementary: tfsec focuses on Terraform-specific misconfigurations, checkov applies broader policy-as-code rules. - **`terraform-docs` runs as part of `make docs`.** Place `` / `` markers in your `README.md`. - **`terratest` tests are written in Go.** The `tests/` directory must contain a `go.mod` file.