Taming 100+ AWS Accounts with Terragrunt and Gruntwork Pipelines

In 2023, Easygo experienced rapid growth across both projects and headcount as the business expanded. The result was Easygo DevOps needing to rapidly scale the number of AWS organisations and accounts, with the increasing pressure of managing configurations and setup at scale. Having used Terraform as our native Infrastructure-as-Code (IaC) stack for the last couple of years, we found it worked well at a smaller scale, but unforeseen complexities and issues began to occur with this rapid expansion.

Evaluating Our Path: Why Terragrunt?

Before committing to Terragrunt, our team evaluated several alternatives to solve our scaling challenges. We looked at:

• Terraform Workspaces: While they offered a way to manage multiple environments, we found that Terraform Workspaces lacked the separation of state and the ability to easily maintain DRY (Don't Repeat Yourself) configurations across a large, rapidly growing number of AWS accounts.
• AWS CDK / Pulumi: We considered these for their programmatic power, but we wanted to avoid forcing our team to relearn infrastructure workflows. We needed a tool that was close enough to Terraform to adopt quickly, but structured enough to manage configuration sprawl effectively.

We ultimately chose Terragrunt because it allowed us to "stay the course" with our existing Terraform knowledge, while adding the missing structure. Specifically, the ability to define shared infrastructure logic once and reuse it across accounts. This enabled us to scale significantly without the operational complexity that other tools would have introduced.

In the early days, the DevOps team followed a very simple pattern for managing AWS infrastructure within a handful of accounts: a module folder, and a number of environment folders with providers linking to AWS accounts. We followed the same common pattern, continuing to scale environment folders as we created more environments. Because we operate on AWS, we deployed our Terraform infrastructure using AWS CodePipeline, with our IaC code hosted on GitHub. This setup worked well for a small number of environments, until we noticed at a certain point our operational overhead and ability to keep the IaC code DRY failed. Other difficulties included maintaining consistency of provider versions and general account onboarding overhead.

Terragrunt

We decided to trial Terragrunt in the middle of 2023, focusing on standardising the way we scaled our Terraform footprint. Our first hurdle was to maintain consistency of the provider file across all our environments.

In a typical Terraform setup, you have the main.tf file with your provider declarations. We experienced inconsistency in how we named our state folders as our footprint increased, and refactored to use Terragrunt’s provider generator.

We baked in some extra logic, such as feature flagging to override provider versions and maintaining a base, to allow upgrading one environment’s provider version before upgrading the rest. Altogether we managed to scale our entire stack with a single root.hcl file at the end. One primary challenge was maintaining our account.hcl files. This account.hcl file defined the AWS account, region and additional metadata related to the environment in which resources reside.

Building on our foundation, a key part of our Terragrunt journey from day one was the use of the _envcommon pattern and moving the Terraform modules into their own dedicated repository. This modularisation provided a number of benefits:

1. 01.
   Version controlling the module allows different environments to stagger their module updates independent of each other, reducing blast radius if a module regression happens.
2. 02.
   Using the most up-to-date versions is a growing supply chain security risk. By keeping the module separate and using immutable references, we are able to trace changes and opt out of problematic versions, reducing another operational risk.
3. 03.
   Separation of ownership and maintenance - a different team may manage the Terraform modules, while another DevOps engineer can use the module to create resources.

A major change involved our release management and IaC pipelines. When we developed our first version of the DevOps pipeline, we made a number of architectural decisions:

1. 01.
   Terraform apply - by definition, it requires broad permissions to manage and maintain resources. It is simply not scalable to manage IAM policy on every single AWS resource when running Terraform apply. The operational overhead grows too high to realistically and continuously maintain IAM policies, coupled with AWS introducing new features, IAM policies and services.
2. 02.
   Central vs per environment apply - in the early days of our Terragrunt journey, we decided not to run a centralised build setup, but instead run compute (Terragrunt plan and apply) inside the AWS account environment the folder targeted. We decided on this pattern to minimise the blast radius if the pipeline was compromised. Over time, as we continued to scale up the number of environments, we began experiencing compounding operational issues that required bespoke central logging solutions, parsing verbose Terraform log formats and trying to build our own GitHub integrations.

Challenges & Lessons Learned

Our transition from managing just a handful of accounts to over 100 highlighted several critical takeaways:

• Account Config Sprawl: The biggest 'gotcha' was maintaining consistency in our account.hcl files. Implementing schema enforcement early is essential to prevent configuration drift.
• IAM Policy Scaling: Attempting to manage granular IAM policies on a per-resource basis became unsustainable. Shifting to centralised, shared policy management was necessary to manage complexity.
• Centralise Pipelines Early: We initially chose per-account pipelines to minimise blast radius, but the operational tax (centralising logs, managing individual CI/CD integrations) grew rapidly. Transitioning to a centralised deployment model earlier would have saved significant effort.
• Balance Abstraction: While DRY code is a goal, avoid over-abstraction. Ensure modules remain simple enough that they can be easily understood and maintained by teams outside the core DevOps group.

These lessons directly informed our decision to adopt Gruntwork Pipelines.

Gruntwork Pipelines

We committed to Gruntwork pipelines in 2026. By using Gruntwork pipelines, we rolled back our per-account deployment model and migrated towards a centralised deployment model. Our implementation of Gruntwork pipelines targeted the following major pain points:

• The operational toil of managing our existing setup was slowing us down
• We were building too many bespoke solutions and troubleshooting the existing stack, rather than focusing on other high priority items.
• As we continued to scale, granting access to the environment became constant operational toil. This access was required simply to troubleshoot when the pipeline failed in that environment.

After a very short engagement with the Gruntwork team, we began the rollout of Gruntwork pipelines across our entire Terragrunt stack. To showcase how we integrated Gruntwork pipelines, the following folder structure illustrates the changes required and demonstrates the high-level structure of our repository.

• We have a single root.hcl which includes remote state, providers and generators for each environment.
• We use an _envcommon folder which references remote modules. This keeps our module configurations DRY.
• We split environments with subfolders to group types of environments (production, non-prod, sandbox, etc.)

Onboarding the Gruntwork pipeline was very straightforward; we ran Gruntwork’s provided Terragrunt stack to set up dependencies. As we continued to onboard, we realised we were duplicating IAM roles and permissions across environments. Another pain point was missing an IAM permission in the policy, resulting in having to update every other environment’s IAM policy to prevent fragmentation and inconsistency between environments.

To solve this pain point, we introduced a central folder holding the IAM policies, which all environments reference:

In the Gruntwork Pipeline Stack configuration, we pass in the IAM plan and apply policy, using a relative file path to reference the central IAM folder:

As of June 2026, we’ve successfully scaled Gruntwork pipelines across our initial 40+ environments in less than a week. Following this successful pilot, we have since rolled out this model across our entire infrastructure, bringing the total number of AWS accounts managed under this Gruntwork pipeline to over 100. This rollout has resulted in many benefits:

• We’ve eliminated virtually all operational work and removed CodeBuild compute running Terraform plan and apply across all the environments. This equated to roughly 5-7 hours of toil a week.
• Our security posture has improved. We no longer need to provide access to multiple AWS accounts including production, as the Gruntwork pipeline handles the Terraform plan and applies output as PR comments on the pull request.
• Introducing an account.hcl schema enforcement early prevented engineers from accidentally introducing attributes which are not well defined - controlling account.hcl sprawl.

Embarking on the Terragrunt journey is a continuous process of improvement, with Terragrunt constantly releasing new features and improvements. We continue to review, iterate and innovate our structure while the business continues to expand.