Declarative IaC with Terraform & Terragrunt — A 2026 Series Recap

TL;DR

I wrote the first post in this series in early 2025, after spending the better part of a year helping teams untangle their Terraform setups at scale. Five posts later — module supply chain, live repo structure, GitHub Actions and GitLab CI pipelines — the Terragrunt track is done. This recap indexes all six parts (including the original Medium post that started the conversation), adds a tooling comparison I kept putting off, and notes what I’d do differently today.

How the series happened

The question I kept getting from engineers: “We’re using Terraform but it’s getting painful to manage across multiple AWS accounts — what do you actually do in production?”

I’d given that answer verbally a dozen times. In 2025 I finally sat down to write it up. The first post became five. By Mid 2025 the series was complete, covering everything from the declarative-vs-imperative philosophy through to the exact .gitlab-ci.yml snippet that configures OIDC short-lived tokens for AWS.

In March 2026 I refreshed all five posts: tightened the prose, updated the Terragrunt CLI syntax to the current run --all form (the old run-all was renamed in terragrunt 0.54), and added the tooling comparison that was missing from the originals.

The reference repos — hagzag/tf-modules for the module library and tf-live for the live repo demo — are public.

The full series

Part 0 — The Starting Point (Medium, 2024)

Infrastructure as Code: Navigating Declarative and Imperative Approaches

Originally published on Medium / Israeli Tech Radar, January 2024. The philosophical foundation: why declarative IaC wins over imperative scripts, and where Terraform, AWS CDK, and Pulumi sit on that spectrum. The series picks up from here without repeating it.

If you haven’t read that post, start there. Everything in the five parts assumes you’ve made peace with the declarative model and are now asking: how do I operate it at scale?

I have to say that since then i’ve been in 2 different engagements where aws CDK, and CDKTF was also considered which gave me the programmable declarative angle which I wrote about internally which I plan to make public soon, stay tuned for that.

Part 1 — Why Declarative IaC and Where Terragrunt Fits

Why Declarative IaC and Where Terragrunt Fits February 2025 · Updated March 2026

The four things Terragrunt adds to Terraform — DRY root.hcl inheritance, per-module state, dependency graph, and run --all fan-out — and why workspaces fall short the moment you have more than one AWS account. Includes the Terragrunt built-in functions (find_in_parent_folders, path_relative_to_include, get_repo_root) that make the hierarchy feel seamless.

What changed in March 2026: The --experiment cli-redesign flag from older posts has been replaced with the current run --all syntax. Info block in the post explains the migration path.

Part 2 — Terraform Modules: Versioning, Scanning, and Distribution

Terraform Modules — Versioning, Scanning, and Distribution March 2025 · Updated March 2026

The module supply chain from hagzag/tf-modules: semantic-release git-tag versioning, Dependabot drift detection, terraform fmt -check as the CI gate, terraform-docs auto-generation, and Trivy/tfsec security scanning. GitHub Actions and GitLab shared-CI template both covered.

What changed in March 2026: Updated security scanning from tfsec to Trivy (same findings, single binary for IaC + container + SCA). The post explains the migration and why both are still valid.

Part 3 — Terragrunt Live: Structure, Dependencies, and Multi-Account

Terragrunt Live — Structure, Dependencies, and Multi-Account April 2025 · Updated March 2026

The full account.hcl / region.hcl / env.hcl hierarchy in detail, the OIDC hub-and-spoke multi-account role design, the allowed_account_ids guard that prevented an accidental prod apply, and the .bootstrap/ one-time setup. The deepest HCL post in the series — references the tf-live demo repo.

What I’d do differently: Bootstrap still runs locally with SSO credentials. Moving it to a dedicated org-management pipeline with a break-glass OIDC role is on the list for a future post.

Part 4 — CI/CD Pipelines for Terragrunt: GitHub Actions

CI/CD Pipelines for Terragrunt: GitHub Actions May 2025 · Updated March 2026

The GitHub Actions plan/apply lifecycle: hierarchical HCL change detection (project → account → region → env → module), dynamic matrix, parallel PR plan comments, apply-on-merge. Three options for role ARN management. The story of the silent empty-matrix failure that caused two days of undetected drift.

What’s new in 2026: The change-detection logic can now be factored into a reusable workflow, shareable across multiple live repos.

Part 5 — CI/CD Pipelines for Terragrunt: GitLab CI

CI/CD Pipelines for Terragrunt: GitLab CI May 2025 · Updated March 2026

The GitLab CI equivalent: web_identity_token OIDC for keyless AWS auth, YAML anchor job templates, static per-environment job structure, TG_EXCLUDE_ARGS for skipping unready modules, and the hard rule that apply is always when: manual — backed by a real incident story of an accidental auto-apply.

The GitLab CI — In Tikal our SCM and CI reside in an internal GitLab, I’ve migrated the examples to work well with gitlab.com.

Tools comparison: where this approach fits

The approach in this series — Terragrunt on GitHub Actions or GitLab CI, no external orchestration — is the right fit when:

Your team lives in GitHub or GitLab and doesn’t want another service to operate
The pipeline logic needs to be readable, testable, and version-controlled alongside the infrastructure
You’re in an air-gapped, regulated, or restricted environment where SaaS isn’t viable
You want full control over plan/apply sequencing and blast-radius containment

It’s not the obvious choice when:

Situation	Better fit
UI-driven approval with cost estimates	Terraform Cloud or env0
GitOps-native PR automation, minimal config	Atlantis or Terrateam
FOSS orchestration with OpenTofu support	Digger
Managed state + runs, HashiCorp ecosystem	HCP Terraform
Drift detection + compliance + cost in one product	env0 or Spacelift

The honest answer: the right choice is the one your team will actually maintain. A well-understood 300-line GitHub Actions workflow often outlasts a perfectly configured SaaS product that only one person knows how to debug.

What’s next

The 2025 series covered Terraform HCL and Terragrunt. Coming up:

CDK for Terraform (CDKTF) — writing infrastructure in TypeScript/Python, compiled to Terraform JSON
Pulumi — infrastructure as actual code, real type systems, real loops
OpenTofu — the open-source Terraform fork and where it stands post-BSL

The declarative IaC problem space is broad. This series was one opinionated slice of it.

Reference repos

Module library: hagzag/tf-modules — versioned Terraform modules with semantic-release CI
Live repo demo: tf-live — sanitized multi-account Terragrunt layout with OIDC bootstrap and GitHub Actions workflows

Series Navigation