terragrunt

The Road to 1.0: Terragrunt Stacks Feature Complete

Terragrunt Stacks: Feature Complete
The Road to 1.0: Terragrunt Stacks Feature Complete
Yousif Akbar
Principal Software Engineer
Published April 16, 2025

Update Apr 21, 2025: To allow more community members in different timezones, a second session has been scheduled far later in the day. See the link below for more details.

We are incredibly excited to announce that Terragrunt Stacks is now feature-complete! 🎉

This marks a significant milestone on our journey towards Terragrunt 1.0, bringing powerful new capabilities for managing your infrastructure configurations at scale.

Why Terragrunt Stacks?

It’s been four months since our initial The Road to 1.0: Terragrunt Stacks blog post where we shared a deep dive on what Terragrunt Stacks is, when to use it, and how it works.

If you’re new to Terragrunt Stacks, here’s a quick refresher: When you work with OpenTofu or Terraform, it’s a best practice to use OpenTofu/Terraform modules so that you can define your patterns once and re-use them multiple times. In Terragrunt terminology, when you create an instance of an OpenTofu/Terraform module, we call that a “Terragrunt unit.”

But sometimes you need to combine multiple units as part of achieving a common use case such as standing up a new customer, creating a new environment, or deploying a new service. Until now, there was no formal way to declare the combination of units you want to deploy for a given use case. As a result, users would resort to just copy/pasting prior configurations.

With Terragrunt Stacks, now you can formally define a reusable combination of units so that it’s easier than ever to launch your new customer, environment, service, or any other recurring pattern. In practical terms, you can now author Terragrunt configurations with significantly less bloat in your Infrastructure as Code repositories. That is, more of your configuration in the form of terragrunt.hcl files can be references to versioned, atomic artifacts in terragrunt.stack.hcl files, so you and your team can put more of your energy refining infrastructure patterns for reuse across your infrastructure estate.

What’s New With Terragrunt Stacks?

With the feature completion of Terragrunt Stacks, Terragrunt now has access to several key enhancements:

  • On-Demand Generation: Define your infrastructure units declaratively using terragrunt.stack.hcl files, allowing Terragrunt to generate the necessary configurations when needed. This significantly reduces bloat in Terragrunt repositories, makes it easier to reason about infrastructure and moves more infrastructure configuration into atomic, reusable building blocks.
  • Recursive Generation: Seamlessly manage complex infrastructure layouts with support for recursively generating nested stacks defined within your terragrunt.stack.hcl files.
  • Dynamic Values: Inject dynamic data into your generated terragrunt.hcl files through the new terragrunt.values.hcl file, offering greater flexibility.

To support these features, we’ve added a new suite of commands under the new stack sub-command:

Built with the Community

The development of Terragrunt Stacks has been a truly collaborative effort. The Stacks RFC was built in public, inviting feedback and discussion from the Terragrunt community. The engagement has been fantastic!

To date, the RFC has garnered dozens of positive reactions, and received hundreds of insightful comments from its 35 active participants.

This invaluable feedback has directly shaped the final design of Stacks. Several key features were added specifically based on community input:

  • The terragrunt.values.hcl file: Users requested more robust ways to handle dynamic values in generated units, leading us to incorporate this new file into the design.
  • The stack clean command: Early adopters testing Stacks highlighted the need for a simple way to undo the generation process, resulting in this helpful command.
  • The no_dot_terragrunt_stack attribute: To ease adoption, users asked for a way to use terragrunt.stack.hcl without forcing state migration. This attribute provides a gradual on-ramp.
  • Enhanced Validations: Testing Stacks in real-world scenarios helped us identify crucial edge cases, leading to additional validation checks before and after generation to ensure generation results in expected units, and the ability to disable validation, when necessary via the no_validation attribute on unit and stack blocks.

Your Turn: Final Validation Needed!

Now that Terragrunt Stacks is feature complete, we’re entering the final validation phase before removing the stacks experiment flag and declaring General Availability (GA). We need your help!

We kindly ask the Terragrunt community to start experimenting with Stacks in your lower environments (like development or staging) if you haven’t so far. Your feedback during this crucial period will help us catch any remaining issues and ensure Terragrunt Stacks is robust and reliable for everyone.

To help you get started, we’ve prepared example repositories demonstrating how to structure your Terragrunt configurations with Stacks in mind:

Gruntwork Pipelines Customers

If you are a Gruntwork Pipelines customer, you can start using Terragrunt Stacks in your workflows today! Pipelines has already been updated to factor in the behavior of Terragrunt Stacks, so as long as you’re using a Terragrunt version that’s recent enough (we recommend using the latest version, which is v0.77.13 as of today), Terragrunt Stacks will just work with no manual configuration on your part.

Gruntwork Pipelines will automatically run terragrunt stack generate on any changed terragrunt.stack.hcl file in your repository, and handle created, updated and deleted stacks with minimal blast radius, and the same great GitOps Pull Request / Merge Request based UI/UX you expect from Gruntwork Pipelines today.

As Terragrunt Stacks evolves, you’ll be able to expect all the latest and greatest features validated in Gruntwork Pipelines first, and support for any new functionality integrated into Gruntwork Pipelines before any other CI/CD solution.

Terragrunt Stacks support is available in both GitHub and GitLab versions of Gruntwork Pipelines.

Join Us for Office Hours!

Have questions? Want to share your feedback directly? Join us for a special Terragrunt Office Hours session focused entirely on Stacks!

This is a great opportunity to engage directly with the maintainers and the Terragrunt community.

Looking Ahead: GA vs. 1.0

Achieving General Availability (GA) for Stacks means the feature is considered stable and ready for broader use. However, it’s important to note that GA does not guarantee zero breaking changes moving forward. While we strive for stability, minor adjustments might still occur based on continued feedback.

The release of Terragrunt 1.0 will be the point where we formally commit to API stability, guaranteeing no breaking changes until Terragrunt 2.0 (as discussed in the initial Road to 1.0 blog post).

Thank you to everyone who has participated in the Stacks journey so far. We’re thrilled with how this feature has evolved and can’t wait for you to try it out! Please share your experiences and help us make Terragrunt Stacks the best they can be.