Merge branch 'feat/terragrunt-support' into 'main'

docs(standards): add terragrunt support across all repos

See merge request orgdocs/development-standards!21

Author: Matthew

DEVELOPMENT.md

@@ -516,6 +516,7 @@ Every repo includes an `.editorconfig` file that defines formatting rules (inden
 |---|---|---|
 | Linter | **tflint** | Terraform-specific linting rules |
 | Formatter | **terraform fmt** | Canonical formatting |
+| Formatter | **terragrunt hclfmt** | Terragrunt HCL formatting (when `terragrunt.hcl` files present) |
 | Security | **tfsec**, **checkov** | Infrastructure security scanning |
 | Tests | **terratest** | Go-based infrastructure testing |
 | Docs | **terraform-docs** | Auto-generate module documentation |

dev-toolchain/Makefile

@@ -303,6 +303,10 @@ _format: _check-config
 	if [ -n "$(HAS_TERRAFORM)" ]; then \
 		ran_languages="$${ran_languages}\"terraform\","; \
 		terraform fmt -check -recursive || { overall_exit=1; failed_languages="$${failed_languages}\"terraform\","; }; \
+		tg_files=$$(find . -name 'terragrunt.hcl' -not -path './.git/*' -not -path './.terraform/*' 2>/dev/null); \
+		if [ -n "$$tg_files" ]; then \
+			terragrunt hclfmt --terragrunt-check || { overall_exit=1; failed_languages="$${failed_languages}\"terraform:terragrunt\","; }; \
+		fi; \
 		if [ "$(DEVRAIL_FAIL_FAST)" = "1" ] && [ $$overall_exit -ne 0 ]; then \
 			end_time=$$(date +%s%3N); \
 			duration=$$((end_time - start_time)); \
@@ -402,6 +406,10 @@ _fix: _check-config
 	if [ -n "$(HAS_TERRAFORM)" ]; then \
 		ran_languages="$${ran_languages}\"terraform\","; \
 		terraform fmt -recursive || { overall_exit=1; failed_languages="$${failed_languages}\"terraform\","; }; \
+		tg_files=$$(find . -name 'terragrunt.hcl' -not -path './.git/*' -not -path './.terraform/*' 2>/dev/null); \
+		if [ -n "$$tg_files" ]; then \
+			terragrunt hclfmt || { overall_exit=1; failed_languages="$${failed_languages}\"terraform:terragrunt\","; }; \
+		fi; \
 		if [ "$(DEVRAIL_FAIL_FAST)" = "1" ] && [ $$overall_exit -ne 0 ]; then \
 			end_time=$$(date +%s%3N); \
 			duration=$$((end_time - start_time)); \
@@ -786,6 +794,7 @@ _docs: _check-config
 			_tv tfsec "tfsec --version"; \
 			_tv checkov "checkov --version"; \
 			_tv terraform-docs "terraform-docs --version"; \
+			_tv terragrunt "terragrunt --version"; \
 		fi; \
 		if [ -n "$(HAS_ANSIBLE)" ]; then \
 			_tv ansible-lint "ansible-lint --version"; \

dev-toolchain/README.md

@@ -50,7 +50,7 @@ test                 Run validation tests
 |----------------|---------------------------------------------------|
 | Python         | ruff, bandit, semgrep, pytest, mypy               |
 | Bash           | shellcheck, shfmt, bats                           |
-| Terraform      | tflint, tfsec, checkov, terraform-docs, terraform |
+| Terraform      | tflint, tfsec, checkov, terraform-docs, terraform, terragrunt |
 | Ansible        | ansible-lint, molecule                            |
 | Ruby           | rubocop, reek, brakeman, bundler-audit, rspec, sorbet |
 | Go             | golangci-lint, gofumpt, govulncheck, go test      |

dev-toolchain/scripts/install-terraform.sh

@@ -12,6 +12,7 @@
 #   - checkov         (IaC security scanner — installed via pip)
 #   - terraform-docs  (Terraform documentation gen — built in Go builder stage)
 #   - terraform       (Terraform CLI — downloaded from HashiCorp)
+#   - terragrunt      (Terraform wrapper for DRY configs — downloaded from GitHub)
 #
 # Notes:
 #   - terratest is a Go module dependency, not a standalone binary.
@@ -32,7 +33,7 @@ source "${DEVRAIL_LIB}/platform.sh"
 if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
   log_info "install-terraform.sh — Install Terraform tooling for DevRail"
   log_info "Usage: bash scripts/install-terraform.sh [--help]"
-  log_info "Tools: tflint, tfsec, checkov, terraform-docs, terraform"
+  log_info "Tools: tflint, tfsec, checkov, terraform-docs, terraform, terragrunt"
   log_info "Note: terratest is a Go module dependency — not installed as a binary"
   exit 0
 fi
@@ -111,6 +112,31 @@ else
   log_info "terraform ${TERRAFORM_VERSION} installed successfully"
 fi
 
+# Install terragrunt (idempotent)
+if command -v terragrunt &>/dev/null; then
+  log_info "terragrunt is already installed, skipping"
+else
+  log_info "Installing terragrunt"
+  require_cmd "curl" "curl is required to download terragrunt"
+
+  ARCH="$(get_arch)"
+  OS="$(get_os)"
+
+  # Fetch the latest terragrunt version from GitHub API
+  TERRAGRUNT_VERSION=$(curl -s https://api.github.com/repos/gruntwork-io/terragrunt/releases/latest | jq -r '.tag_name' | sed 's/^v//')
+  if is_empty "${TERRAGRUNT_VERSION}"; then
+    log_warn "Could not determine latest terragrunt version, using fallback"
+    TERRAGRUNT_VERSION="0.99.4"
+  fi
+
+  log_info "Downloading terragrunt ${TERRAGRUNT_VERSION} for ${OS}/${ARCH}"
+  TERRAGRUNT_URL="https://github.com/gruntwork-io/terragrunt/releases/download/v${TERRAGRUNT_VERSION}/terragrunt_${OS}_${ARCH}"
+  curl -fsSL "${TERRAGRUNT_URL}" -o "${TMPDIR_CLEANUP}/terragrunt"
+  install -m 0755 "${TMPDIR_CLEANUP}/terragrunt" /usr/local/bin/terragrunt
+
+  log_info "terragrunt ${TERRAGRUNT_VERSION} installed successfully"
+fi
+
 # Note about terratest
 log_info "terratest is a Go module dependency — not installed as a binary"
 log_info "Consumer projects use 'go get github.com/gruntwork-io/terratest' as needed"

dev-toolchain/tests/test-terraform.sh

@@ -18,7 +18,7 @@ source "${DEVRAIL_LIB}/log.sh"
 if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
   log_info "test-terraform.sh — Validate Terraform tooling installation"
   log_info "Usage: bash tests/test-terraform.sh [--help]"
-  log_info "Checks: tflint, tfsec, checkov, terraform-docs, terraform"
+  log_info "Checks: tflint, tfsec, checkov, terraform-docs, terraform, terragrunt"
   exit 0
 fi
 
@@ -52,6 +52,7 @@ check_tool "tfsec" "--version"
 check_tool "checkov" "--version"
 check_tool "terraform-docs" "--version"
 check_tool "terraform" "version"
+check_tool "terragrunt" "--version"
 
 # terratest is a Go module, not a binary — log a note
 log_info "terratest is a Go module dependency — no binary to validate"

devrail.dev/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 |
 |---|---|---|---|---|---|---|---|
 | Linter | ruff | shellcheck | tflint | ansible-lint | rubocop, reek | golangci-lint | eslint |
-| Formatter | ruff format | shfmt | terraform fmt | -- | rubocop | gofumpt | prettier |
+| Formatter | ruff format | shfmt | terraform fmt, terragrunt hclfmt | -- | rubocop | gofumpt | prettier |
 | Security | bandit, semgrep | -- | tfsec, checkov | -- | brakeman, bundler-audit | govulncheck | npm audit |
 | Tests | pytest | bats | terratest | molecule | rspec | go test | vitest |
 | 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 |
-| `make format` | ruff format --check, shfmt -d, terraform fmt -check, rubocop --check, gofumpt -d, prettier --check |
-| `make fix` | ruff format, shfmt -w, terraform fmt, rubocop -a, gofumpt -w, prettier --write |
+| `make format` | ruff format --check, shfmt -d, terraform fmt -check, terragrunt hclfmt --terragrunt-check, rubocop --check, gofumpt -d, prettier --check |
+| `make fix` | ruff format, shfmt -w, terraform fmt, terragrunt hclfmt, rubocop -a, gofumpt -w, prettier --write |
 | `make test` | pytest, bats, terratest, molecule, rspec, go test, vitest |
 | `make security` | bandit, semgrep, tfsec, checkov, brakeman, bundler-audit, govulncheck, npm audit |
 | `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

devrail.dev/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 `<!-- 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.

github-repo-template/.pre-commit-config.yaml

@@ -39,6 +39,8 @@ repos:
   #   hooks:
   #     - id: terraform_fmt
   #     - id: terraform_tflint
+  #     # Uncomment if using Terragrunt:
+  #     # - id: terragrunt_fmt
 
   # --- Ruby (uncomment if languages includes ruby) ---
   # Linting and formatting with rubocop

gitlab-repo-template/.pre-commit-config.yaml

@@ -39,6 +39,8 @@ repos:
   #   hooks:
   #     - id: terraform_fmt
   #     - id: terraform_tflint
+  #     # Uncomment if using Terragrunt:
+  #     # - id: terragrunt_fmt
 
   # --- Ruby (uncomment if languages includes ruby) ---
   # Linting and formatting with rubocop

standards/devrail-yml-schema.md

@@ -352,7 +352,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 | -- |
@@ -364,6 +364,7 @@ The following table shows the default tool for each concern per language. These
 - "Universal" tools run for all languages and are not language-specific overrides
 - A `--` entry means the concern does not apply to that language
 - Default tools are used when no per-language override is specified
+- `terraform` includes Terragrunt formatting (`terragrunt hclfmt`) — no separate language entry needed. Terragrunt formatting runs automatically when `terragrunt.hcl` files are detected
 
 ## Exit Codes