Skip to content

docs(standards): add terragrunt to terraform standards #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matthew-on-git merged 1 commit into from
Mar 5, 2026
Merged

docs(standards): add terragrunt to terraform standards #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions content/docs/standards/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 | -- |
Expand All @@ -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) |
Expand All @@ -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
Expand Down
23 changes: 21 additions & 2 deletions content/docs/standards/terraform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 |
Expand Down Expand Up @@ -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.
Expand All @@ -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 |
Expand All @@ -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)
Expand All @@ -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 `<!-- BEGIN_TF_DOCS -->` / `<!-- END_TF_DOCS -->` markers in your `README.md`.
- **`terratest` tests are written in Go.** The `tests/` directory must contain a `go.mod` file.
Expand Down