How to Use Upcoming Terragrunt 1.0 Changes Today

How can you use Terragrunt's newest features while managing backward compatibility? In this post, we'll show you practical strategies for trying the latest Terragrunt capabilities while safely transitioning through any breaking changes. This way, you can keep your workflows stable as Terragrunt evolves towards strong backward-compatibility guarantees in Terragrunt 1.0.

To reach the level of interface stability we envision for Terragrunt 1.0, there are some breaking changes that we cannot avoid (see The Road to 1.0 blog post for details). To make the transition as easy as possible, we've created two types of "opt-in controls" that give users the flexibility to adopt changes at their own pace: Experiments, and Strict Controls.

Experiments: Opt-In Exploration

You can use experiments to opt in to features that are explicitly marked as unstable. This provides a clear boundary: all features that are available by default are production-ready and any that require opt-in via an experiment flag are features that maintainers are actively collaborating with the community to validate. As an early adopter, you can try cutting-edge functionality and provide valuable feedback, based on practical infrastructure management.

A prime example is the Terragrunt CLI Redesign (#3445). Instead of releasing potentially disruptive changes by default, new CLI features were introduced behind the `cli-redesign` experiment flag. This allowed iterative development and feedback without impacting stable workflows.

$ terragrunt find --json --dag --dependencies --experiment cli-redesign
[
  {
    "type": "stack",
    "path": "stacks/live/dev"
  },
  {
    "type": "stack",
    "path": "stacks/live/prod"
  },
  {
    "type": "unit",
    "path": "units/live/dev/vpc"
  },
  {
    "type": "unit",
    "path": "units/live/prod/vpc"
  },
  {
    "type": "unit",
    "path": "units/live/dev/db",
    "dependencies": [
      "units/live/dev/vpc"
    ]
  },
  {
    "type": "unit",
    "path": "units/live/prod/db",
    "dependencies": [
      "units/live/prod/vpc"
    ]
  },
  {
    "type": "unit",
    "path": "units/live/dev/ec2",
    "dependencies": [
      "units/live/dev/vpc",
      "units/live/dev/db"
    ]
  },
  {
    "type": "unit",
    "path": "units/live/prod/ec2",
    "dependencies": [
      "units/live/prod/vpc",
      "units/live/prod/db"
    ]
  }
]

You no longer need the `--experiment cli-redesign` to use this functionality, but if you wanted to leverage the feature while it was still subject to experimentation and breaking changes, you could opt in. You would also be implicitly accepting that the JSON schema of the results above could change at any time, so it wouldn’t be a good idea to rely on that for any critical systems that depended on it!

For those comfortable with a faster pace of change, "Experiment Mode" (`—experiment-mode`) enables all current experiments, providing continuous access to the latest developments. This approach benefits everyone: maintainers can ship incrementally based on user feedback, and users gain early access and influence development. Real-world feedback is crucial; maintainers can only test so much in isolation.

Strict Controls: Gradual Deprecation and Future-Proofing

Whenever you receive a new deprecation warning, you can expect a strict control to accompany that deprecation.

Strict controls allow you to opt in to a *future* behavior involving a breaking change *before* it becomes the default behavior of Terragrunt. This lets you validate your Terragrunt usage against upcoming changes on your own timeline, ensuring it is future-proof before upgrading to a version of Terragrunt that no longer supports that usage.

$ terragrunt hclfmt
11:23:45.969 WARN   The `hclfmt` command is deprecated and will be removed in a future version of Terragrunt. Use `terragrunt hcl format` instead.

$ terragrunt hclfmt --strict-control cli-redesign
11:23:56.363 ERROR  The `hclfmt` command is no longer supported. Use `terragrunt hcl format` instead.

$ terragrunt hcl fmt --strict-control cli-redesign

When the `hclfmt` command was deprecated in favor of the new `hcl fmt` command, the strict control `cli-redesign` was also introduced to allow users to enforce usage of the future proof usage of the Terragrunt CLI (`terragrunt hcl fmt`). If you leave the strict control on while using the new command, you’ll receive neither warnings nor errors while using the Terragrunt CLI.

This method also serves as a vital feedback mechanism. Documentation or forum posts about deprecations don't always reach every user. However, warnings directly in the tool when using an eventually-to-be-removed feature *do* get noticed. This gives you a way to confirm that your workflows will definitely be impacted, and to to engage with maintainers, allowing coordination on design adjustments *before* critical functionality is removed or changed. You can also enable the strict control across your organization to guarantee readiness for a future version of Terragrunt where the feature is no longer available.

Consider the `terragrunt-prefix-flags` strict control. During the CLI Redesign (#3445), flags like `--terragrunt-non-interactive` were replaced by shorter versions like `--non-interactive`. Instead of supporting both indefinitely (introducing inconsistency) or breaking existing Terragrunt usage suddenly in a new release, we introduced the new flags, along with the `terragrunt-prefix-flags` strict control, and warnings when users used legacy flags. This allows you to migrate at your own pace and enable the control for confidence that no legacy flags remain in your convenience scripts or CI/CD workflows.

The timeline for removing functionality deprecated via a strict control depends on factors like:

- How long the feature has existed.
- How widely it's used.
- Its importance to typical Terragrunt workflows.
- The difficulty for users to adapt to the change.

In the case of `terragrunt-prefix`, these flags existed for most of Terragrunt's history and are widely used. However, adapting typically involves straightforward updates to scripts, aliases, and CI/CD. We introduced the strict control and shorter flags in v0.73.0 (released 2025-02-10), providing ample time for adaptation.

These deprecations are part of the scheduled breaking changes leading to 1.0, managed gradually to avoid a single disruptive release. You can track the schedule here (note that some dates may currently be TBD as we phase announcements).

Looking Beyond 1.0

This pattern of Experiments and Strict Controls isn't just for the road to 1.0; it's how you can confidently assume backwards compatibility moving forward. Post-1.0, we promise no *intentional* breaking changes within the 1.x series. However, Terragrunt development won't freeze. New features might necessitate changes to default behavior for the overall benefit of users.

To manage this, while upholding our stability promise, any future change impacting default behavior—such as:

- Removing a command or flag.
- Removing support for specific Terragrunt configurations.
- Altering default command output relied upon programmatically (e.g., schemas, stdout vs. stderr usage).

—will be introduced via a strict control first. You will have the entire 1.x major release to opt-in, test, and adapt, receiving ample warning before the changed behavior becomes the default, in a future major version like 2.0. You’ll also be able to expect strict controls that allow you to guarantee that you aren’t using any breaking functionality prior to upgrading.

Our commitment is to provide a stable, reliable Terragrunt experience. By using Experiments for exploration and Strict Controls for necessary evolution, we aim to balance innovation with the stability you can depend on, both on the path to 1.0 and long after

‍