Terragrunt 1.0 Released!

After nearly a decade of development, over 900 releases, and tens of millions of infrastructure deployments by platform teams, today we're happy to announce that Terragrunt 1.0 is officially here.  We're also thrilled to announce, simultaneous with the release of Terragrunt 1.0, the general availability of Terragrunt Scale Free Tier.

The Journey to 1.0

In October 2024, we kicked off “The Road to Terragrunt 1.0” with a clear mission: stabilizing the Terragrunt user experience so that we can guarantee backwards compatibility, making it easy to benefit from features introduced in the latest versions of Terragrunt. We believe that Terragrunt is the best way to scale IaC with small, independently deployable units of infrastructure. We spent the last year refining the CLI, improving the developer experience, and working closely with the community through a gradual release process to ensure that this release is battle-tested with real world platform teams.

We want to extend a massive thank you to everyone who shared their feedback on RFCs, tried out experimental features before they were generally available, reported bugs, and championed Terragrunt on their teams and in their communities. Terragrunt would be nowhere near as powerful or ergonomic as it is today if it wasn’t for your continuous feedback and support.

What 1.0 Means

The most significant change in 1.0 isn’t the introduction of a new feature, it’s an explicit backwards compatibility guarantee. With the release of 1.0, Gruntwork is making a formal commitment to backwards compatibility for Terragrunt for the foreseeable future.

All CLI flags, serialized output (from commands like find and the Run Report), HCL configurations, and OpenTofu/Terraform stdout/stderr enrichment are now stable. You can safely upgrade throughout the 1.x series with confidence that your workflows will not break if you rely on any of these working the same way.

If you want a more explicit breakdown of all the ways backwards compatibility is and isn’t being promised, you are encouraged to review Terragrunt 1.0 Guarantees.

Terragrunt Scale Free Tier for Everyone

To celebrate the 1.0 release and make it easier than ever to adopt these new stable workflows, we are introducing a free tier of Terragrunt Scale that is available to every Terragrunt user today. 🎉

For years, platform teams have told us that while Terragrunt excels at orchestrating infrastructure updates and keeping code DRY, automating it in CI/CD often meant writing and maintaining fragile, custom pipeline scripts or relying on third party services. Terragrunt 1.0 solves the CLI side of the equation with guaranteed stability for all Terragrunt users running Terragrunt in CI/CD. Terragrunt Scale completes the picture by providing an out of the box solution for Terragrunt users so they don’t have to build these CI/CD solutions themselves.

The features stabilized for 1.0 were designed to work hand-in-hand with the automation provided by Terragrunt Scale:

• Run in your platform: Terragrunt Scale runs natively inside your GitHub Actions or GitLab CI runners, on both cloud-hosted and self-hosted runners.
• Minimize Your Blast Radius: Terragrunt runs “just work” in Terragrunt Scale. You don’t have to work out the right way to instrument Terragrunt to minimize your blast radius or authenticate with least privilege. You just propose IaC changes, and merge them to get the results you expect.
• Context Aware Authentication: Terragrunt Scale takes care of authentication for you across environments and cloud providers seamlessly. Set up is dead simple, and Terragrunt Scale does the heavy lifting of cloud authentication integrations based on the context of the IaC being edited.
• Native Support for Stacks: Terragrunt Stacks are the simplest way to manage large infrastructure estates. Terragrunt Scale natively understands how to evaluate and run these Stacks with a minimal blast radius and optimal performance, straight out of the box.
• Automated Run Reports: The parseable Run Reports introduced on the road to 1.0 integrate perfectly with your pull/merge requests, giving your team immediate, clear feedback on runs without digging through thousands of lines of raw OpenTofu logs.
• Drift Detection (Paid): Automatically detect drift in your infrastructure estate, with a convenient pull/merge request to remediate the drift.
• Patch Management (Paid): Keep your IaC from rotting away with automatically created pull/merge requests that keep your IaC up to date and healthy.

For this initial release of the free tier, we’ve designed an onboarding experience that is dead-simple for Terragrunt users on GitHub and AWS to get started, with automated onboarding for GitLab, Azure and GCP customers to follow soon.

Whether you’re just getting started with Terragrunt or you want a batteries-included CI/CD setup for a small platform team, the Terragrunt Scale Free Tier is designed to be the fastest, most secure way to run Terragrunt in CI/CD, from the creators of Terragrunt.

If you’re on GitHub and AWS, scale up today!

If you’re not on GitHub and AWS, join the waitlist to be notified soon when your platform is supported

Highlights of 1.0

If you haven’t been keeping up with the latest releases of Terragrunt, and are wondering whether it’s worth it to upgrade to the latest version of Terragrunt, here are some highlights of the changes made on the road to 1.0.

Terragrunt Stacks

Terragrunt Stacks are the modern way to define a higher level pattern of infrastructure you want to deploy with Terragrunt. It offers a new way to reduce boilerplate for large infrastructure estates, and makes it easier to version and deploy large scale infrastructure without sacrificing the advantages you gain with Terragrunt Units.

The community is using Terragrunt Stacks in production, and feedback has been overwhelmingly positive. Members of the community have reported that adoption of Terragrunt Stacks has significantly reduced file counts in repositories, and made it much simpler to work with large infrastructure estates.

"By adopting Terragrunt Stacks, we eliminated nearly 20,000 lines of custom IaC and reduced environment plan times from two hours to just eight minutes using the Terragrunt cache provider. Less code, faster feedback loops — unlocking a whole new level of velocity for our team." - Lorelei Rupp, Senior Principal DevOps Engineer @ Imprivata

Pipelines, the CI/CD component of Terragrunt Scale, has native support for handling Terragrunt Stacks in CI/CD workflows, so they “just work” how you would expect, with minimal blast radius and zero additional tooling.

You can read the Terragrunt Stacks migration guide to start leveraging Terragrunt Stacks today.

Streamlined CLI

The Terragrunt CLI has been overhauled to be more ergonomic and less verbose.

Parts of the Terragrunt CLI have been restructured, like removal of terragrunt prefixes in CLI flags (e.g. --terragrunt-non-interactive is now --non-interactive) and use of the run command to replace the run-all command. New capabilities have also been introduced, like introduction of the exec, backend, find and list commands.

Overall, the Terragrunt CLI has become more consistent, and obeys a set of rules to ensure that the CLI flags are predictable and conform to an intentional design. It will be easier to teach your colleagues how to use Terragrunt, and there are more tools available to you to control your infrastructure.

You can read the CLI Redesign migration guide to start using the new CLI design today.

The Filter Flag

Terragrunt has a new, comprehensive, system for targeting the infrastructure units and stacks in your infrastructure estate using Filters.

Filters offer a single CLI flag (--filter) that can be used on multiple commands to discover infrastructure and control how Terragrunt deploys your infrastructure estate. The syntax for Filters is sophisticated enough that it replaces seven legacy flags (on top of delivering more functionality that wasn’t possible before) with a single query system you can use to target infrastructure based on filesystem path, configuration properties, dependency graph relationships and Git diffs/hashes.

Read the Filter feature documentation to start using Filters today.

Run Reports

Terragrunt now offers the ability to optionally generate a Run Report detailing the outcomes of runs in JSON and CSV formats.

Run Reports offer a convenient and stable way to introspect the results of a run without searching and interpreting OpenTofu/Terraform logs. You no longer need to manually scan through thousands of lines of logs to work out which unit had an issue and why. You now have a convenient, parseable representation of your run results that make it far easier to understand what happened in your run.

Read the Run Reports feature documentation to start using Run Reports today.

Performance Improvements

If you are using a version of Terragrunt older than v0.89.0 you will experience significant performance improvements by upgrading to Terragrunt 1.0, especially if you are also using OpenTofu.

The core concurrency mechanism was completely revamped with the completion of the Runner Pool RFC.  This new concurrency model allows more work to be done by Terragrunt concurrently, without sacrificing respect for the Directed Acyclic Graph (DAG), and handles failures more gracefully. The performance improvements from the Runner Pool scales in proportion to the size of the infrastructure estate.

The Automatic Provider Cache Dir feature was put together in collaboration with OpenTofu maintainers. The OpenTofu team has done a fantastic job prioritizing improving the performance of OpenTofu, and OpenTofu 1.10 introduced the ability to safely access a shared provider plugin cache without encountering race conditions. Terragrunt will detect when you are using a version of OpenTofu ≥ 1.10 and automatically configure OpenTofu to use a shared cache to give you a performance boost out of the box with zero configuration on your part.

You do not need to do anything to benefit from this update aside from ensuring that you are using the latest version of Terragrunt and OpenTofu.

Beyond 1.0

After the release of 1.0, we will continue to make improvements to Terragrunt. Here are some of the features we’ve been planning post-1.0:

• Terragrunt Stacks: Support for dependencies
• Run Reports: Integration with OpenTofu/Terraform plans
• Terragrunt Catalog: Support for units and stacks
• CAS: General availability
• IaC Engines: General availability
• HCL parsing: Massive performance improvements

After 1.0, big changes to Terragrunt will be made with more deliberation, but we’ll continue to use the experiment system to ensure that you can try out new features as quickly as possible if you’re an early adopter.

Versioning Policy

With the release of 1.0, Terragrunt will utilize a different versioning policy.

We’ll continue to use semantic versioning, but now that we won’t be making any breaking changes in 1.x releases, you can expect that all minor releases will only contain new, backwards-compatible feature additions.

You can learn more about this policy here.

Getting Started with 1.0

Excited to try out Terragrunt 1.0? Install it today!

curl -sL https://terragrunt.gruntwork.io/install | bash -s -- -v v1.0.0

Note: If you would like to use an alternative installation mechanism, you can find them in the installation docs.

Join the community

The Terragrunt community is growing faster than ever.

The fastest growing part of the Terragrunt community is the Terragrunt Discord server. In this publicly accessible forum, you’ll have an opportunity to chat with maintainers, Terragrunt Ambassadors and hundreds of other Terragrunt users. Events are regularly hosted in the Discord server, including free, semi-weekly office hours hosted by maintainers to make sure Terragrunt is working well for everyone.

If you’re not already active in the Terragrunt community, the upgrade to Terragrunt 1.0 is the perfect time. The community is here to help.