The Road to Terragrunt 1.0
Update Dec 20, 2024: We’ve added a link to The Road to 1.0: Terragrunt Stacks.
Update Apr 18, 2025: We've added a link to The Road to 1.0: Terragrunt Stacks Feature Complete
Update Dec 20, 2024: We’ve added a link to The Road to 1.0: Terragrunt Stacks.
Update Feb 5, 2024: We’ve announced a surprise new feature not listed below: The Road to 1.0: Terragrunt Feature Flags!
In this blog post, we’re excited to kick off the road to Terragrunt 1.0! This marks the beginning of a series of both blog posts and feature releases that will eventually culminate in Terragrunt 1.0.
If you’re in a hurry, here’s a shortlist of what we’re announcing here:
- UX and CLI improvements
- Terragrunt Stacks
- Terragrunt Remote Runners
- A stronger Terragrunt community
- A fancy new Terragrunt logo
Let’s read on for more details!
The Significance of Terragrunt 1.0
First, let’s talk about what Terragrunt 1.0 means to us and the Terragrunt community.
A clear purpose
After some 7 years of working with thousands of Terragrunt users, we’ve acquired a deep understanding of why thousands of teams have chosen to run their entire infrastructure on Terragrunt, and why Terragrunt is so often used as teams grow their IaC footprint.
In short, you want to split infrastructure into small, deployable units (represented as terragrunt.hcl files) and then manage those “units” at scale. Doing so requires handling dependencies among units, sharing configuration among units, and executing units in tandem. We see “small, deployable units” as the central, organizing concept that makes Terragrunt useful and going forward we’ll be building all Terragrunt features around this concept.
Ultimately, we’ve discovered that OpenTofu and Terraform work great for defining a reusable infrastructure pattern in the form of an OpenTofu/Terraform module, while Terragrunt shines at helping you deploy those patterns in a manageable, scalable way.
Key new features
From a feature perspective, we want Terragrunt 1.0 to fulfill Terragrunt’s promise as the best way to scale your IaC with small, deployable units.
In this post, we’ll be announcing features that range in maturity from “in internal planning” to “in preview” to “just released” with the goal of both helping you plan for what’s to come and getting your feedback on how these features should work. We’ll share a short summary of each feature, with follow-on blog posts to be published over the coming weeks that explore each in more detail.
Stability
Once we release Terragrunt 1.0, Gruntwork will make a formal commitment to maintaining backward compatibility in all 1.x releases.
A good upgrade experience
Finally, while we’re excited to offer you a more streamlined, powerful version of Terragrunt, we’re mindful that our users run mission-critical infrastructure at scale on Terragrunt and have built up integrations over many years. So we plan to invest not only in new functionality, but also in the smoothest possible upgrade path along the way to 1.0.
We’ll share additional details below on our approach to creating a good upgrade experience, but first let’s talk through those features!
1. UX and CLI improvements
As we wrote above, we see “working in small, deployable units” as the central, organizing concept that makes Terragrunt useful, so we’re excited to announce our plans to streamline the Terragrunt UX around this idea.
Here are the three major UX updates we’ve either already released, or plan on making:
1.1 Streamlined CLI
Status quo
Terragrunt started out as a thin wrapper around Terraform, and much of the design around what flags were used and what arguments were supported were driven by the need to disambiguate between arguments/flags for Terragrunt and those used by OpenTofu/Terraform. As a result, the Terragrunt CLI today is verbose and at times a little clumsy.
What’s new
We’re redesigning the CLI to make it easier to run Terragrunt commands and work with units in a first-class way.
First, we’ll be introducing a new list command to enable users to find and discover their unit configurations more easily.
Second, we’ll be introducing a new run command that will handle all the current responsibilities of run-all and graph. This command will explicitly pass arguments to either OpenTofu or Terraform and make it clear when you’re executing a native Terragrunt command versus when you’re passing through to OpenTofu or Terraform.
Because terragrunt plan and terragrunt apply roll off the tongue so nicely, we’ll retain those commands, but treat them as aliases for terragrunt run -- plan and terragrunt run -- apply. Now that we no longer need to disambiguate whether you’re running a Terragrunt or OpenTofu/Terraform command, we’ll also be able to remove the --terragrunt flag from global options so that options like --terragrunt-excludes-file become --excludes-file.
As an aside, when we tested the breaking change impact of changes like this, we found them to be surprisingly low, though we’ll share details on that later.
Third, we’re introducing a new exec command that will allow you to execute arbitrary commands against any unit.
Why have separate commands for run and exec? In short, Terragrunt uses “smarts” when interacting specifically with OpenTofu or Terraform, but sometimes you don’t want those smarts; you simply want to run a command against a unit with knowledge of the execution context (such as the AWS authentication profile to use). Now you’ll be able to list units, and then exec arbitrary commands against those units such as tflint or checkov.
Finally, we’ll be making Terragrunt’s currently implicit backend operations explicit so that you can now programmatically control how Terragrunt deals with backend management.
Status
Check out our public RFC for the latest, and we’ll be publishing a more detailed blog post soon.
1.2 Improved Logging
Status quo
As an orchestration tool, Terragrunt emits a lot of information as it runs OpenTofu/Terraform. That information can be hard to parse without good context, colorful highlighting and smart summarization. We also believe Terragrunt users are looking for a good deal of control.
What’s new and status
We released a major logging update in Terragrunt v0.67.0, whose release notes include an animated summary of the update. You can also check out the new — forward-tf-stdout for additional details.
We’re currently working on new tooling that allows you to customize Terragrunt logging to give you exactly the information you’re looking for when running Terragrunt.
We’ll add a more detailed blog post on logging improvements in the near future.
1.3 Faster runs with more graceful error handling
Status quo
Who among us has not wished for Terragrunt runs to finish faster or for failures to be handled more gracefully?
What’s new
We’ve been designing a new concurrency model for Terragrunt around a concept we call “Runner Pools.” We’re not ready to share too much about that now, but we can share that it will result in faster Terragrunt runs, and that you will have more control to have Terragrunt fail gracefully.
Once again, look for our future blog post, which we’ll link here once published.
2. Terragrunt Stacks
Status quo
Armed with our insight around the power of working in small, deployable units (or just “units” for short), we were now able to interpret a common use case. We discovered that users often work with a set of reusable patterns for defining new environments, complex application configurations, or new customer setups where each customer might receive their own infrastructure.
What’s new
We’re excited to announce the upcoming release of Terragrunt Stacks!
Terragrunt Stacks is a paradigm shift in how Terragrunt configurations will be written. At its core, a Terragrunt Stack takes all the patterns that users are already familiar with (a directory of terragrunt.hcl files, or units), and provides a mechanism for re-using those configurations in a DRY (Don’t Repeat Yourself) fashion that scales. Users will soon be able to replace the majority of repeated terragrunt.hcl files with new terragrunt.stack.hcl files.
Terragrunt Stacks will be the largest change in how Terragrunt configurations are written and read to date, and we are intentionally designing Terragrunt Stacks to require as little in the way of updates to terragrunt.hcl files as possible. The tradeoff of maximum backward compatibility is a slightly more challenging learning curve, but we plan to ease that over time.
To learn more about Terragrunt Stacks, see the Terragrunt Stacks RFC, and we’ll be publishing a more detailed blog post soon.
Update Dec 20, 2024: Check out The Road to 1.0: Terragrunt Stacks.
Update Apr 18, 2025: Check out The Road to 1.0: Terragrunt Stacks Feature Complete
3. Terragrunt Remote Runners
Status quo
Historically, Terragrunt relied on the OpenTofu or Terraform binary being installed in your environment in order to work. This was because we assumed that you wanted to run OpenTofu or Terraform in the same environment that you’re running Terragrunt.
What’s new
With Terragrunt Remote Runners, it’s now possible to run your underlying OpenTofu/Terraform runs in remote environments!
Terragrunt Remote Runners enable you to bypass the typical constraints around compute and memory when running Terragrunt locally, and run your Terragrunt runs in Kubernetes pods, GitHub Actions, or any other environment you wish.
Terragrunt Remote Runners work by delegating the work of running the tofu or terraform binary using custom, user-authored plugins called IaC Engine Plugins.
Status
IaC engine plugins are available today! Keep in mind that the only IaC engine implementations currently available run Terraform or OpenTofu locally. We’re hoping the Terragrunt community will write its own IaC engine plugins to support bespoke use cases.
In the meantime, stay tuned for our upcoming blog post on IaC engines and IaC engine plugins to learn more.
4. A stronger Terragrunt community
We’re also announcing three new ways to engage with Gruntwork on Terragrunt:
- For async questions and discussion, we’re opening up GitHub Discussions for Terragrunt.
- For real-time questions and discussion, we’re launching an official Discord server.
- We’ll be starting weekly Terragrunt office hours via Discord in November.
Finally, yeah, we get it, the Terragrunt website and docs look dated. So we’ll be launching an updated Terragrunt website with better documentation, more guides, and better overall design.
5. A fancy new Terragrunt logo
Oh, and there’s one more thing! We couldn’t help but notice how our lack of clear Terragrunt logo led to a whole bunch of confusion and awkward blog post images, so we are also excited to announce the new Terragrunt logo!
For those who are interested, we’ll post more about the Terragrunt logo in another future blog post.
Creating a good upgrade experience
If you’re still with us, thank you for reading this far, so now let’s talk about what kind of upgrade experience we’re planning for our users as we roll out all the new hotness.
Over Terragrunt’s 8-year life, we’ve gone out of our way to minimize breaking changes and indeed across hundreds of new Terragrunt releases, there have been relatively few. Now as we progress to Terragrunt 1.0, we know that some of the features above will represent breaking changes as we’ll outline below, so here’s how we’ll be rolling them out.
Backward-compatible rollouts
To make sure we’ve gotten both the functionality and the upgrade path right, we’ll release a series of 0.x updates prior to Terragrunt 1.0. Each 0.x release will have backward-compatible support for deprecated commands or flags. We’ll continue to offer backward-compatible support for a while, until we believe it can be removed without causing much fuss.
CLI changes versus file format changes
Ever mindful of the potential impact of breaking changes, we interviewed several users about the impact of making the above changes. To our delight, we found that making changes to Terragrunt commands was generally cheap because most users don’t call Terragrunt commands in that many distinct places. By contrast, making changes to the Terragrunt file format could be very expensive because users have sometimes tens of thousands of unit files.
Nearly all the above new features are focused on command changes, so while we remain focused on a good upgrade experience, we’re hopeful that it will be surprisingly painless for most users.
Validating new functionality
We deeply value our community’s feedback, and we want to make sure the community is satisfied with the overall behavior of a new Terragrunt feature before before we make it official. So we’ll be looking for active feedback as we release new functionality.
This was an important lesson learned for us when we rolled out our recent new logging functionality. In the end, our logging updates have been a major improvement, but it’s taken a few iterations to get it right, and in retrospect we should have released the functionality as “opt in” first, validated the functionality, and then made it “opt out.”
Post-1.0 commitments
Once we release Terragrunt 1.0, we will stabilize the Terragrunt command line interface and file format for the foreseeable future, and require that every Terragrunt 1.x change be fully backward compatible.
Terragrunt has been pre-1.0 for nearly 8 years now, so this will indeed be a major milestone for the Terragrunt community!
Closing Thoughts
Whew, what a blog post. Again, thanks for reading this far.
To close, we’d like to thank the amazing Terragrunt community for your contributions, your questions, and your feedback. Terragrunt is operated by Gruntwork and engaging with our community gives us confidence that genuinely improve the way you work with infrastructure. We’re announcing our road to 1.0 in advance so that we can build Terragrunt together with you and respect the trust you’ve placed in us as you use Terragrunt with critical infrastructure.
So please share your feedback! We invite you to:
- Comment on this blog post
- Review and comment on GitHub issues
- Post a question in GitHub Discussions
- 💬 Join our Discord Server
We’ll see you along the road to 1.0!
Special thanks for Yousif Akbar, Denis O, and Levko Himins for their significant contributions to the work announced here!