Terragrunt

Warning

This approach is deprecated and will be removed on October 31, 2026. Spacelift provides a native Terragrunt platform with full support for state management, run-all, and more. See the native Terragrunt stack documentation.

Migrating to native Terragrunt platform

Spacelift provides a migration path to convert existing Terraform-based Terragrunt stacks to the native Terragrunt platform.

Migrating a single stack

You can migrate individual stacks from the stack settings page:

If needed, you can also roll back to the previous Terraform-based approach:

Migrating all stacks at once

You need the Update stack permission to migrate stacks. You can migrate all eligible stacks at once from the Dashboard. The Stacks that require attention widget shows how many stacks still need migration and lets you migrate them all with a single click.

To roll back all migrated stacks:

Using Terragrunt (legacy)

Warning

This approach is deprecated and will be removed on October 31, 2026. Spacelift provides a native Terragrunt platform with full support for state management, run-all, and more. See the native Terragrunt stack documentation.

Whether a Terraform stack is using Terragrunt or not is controlled by the presence of terragrunt label on the stack:

If present, all workloads will use terragrunt instead of terraform as the main command. Since the Terragrunt API is a superset of Terraform's, this is completely transparent to the end user.

Warning

The terragrunt label is deprecated and will be removed on October 31, 2026. Migrate your stacks to native Terragrunt.

Terragrunt is installed on our standard runner image. If you're not using our runner image, you can install Terragrunt separately.

During the Initialization phase we're showing you the exact binary that will process your job, along with its location:

Versioning with Terragrunt

When working with Terragrunt, you will still specify the Terraform version to be used to process your job. We don't do it for Terragrunt, which is way more relaxed in terms of how it interacts with Terraform versions, especially since we're only using a very stable subset of its API.

On our runner image, we install a version of Terragrunt that will work with the latest version of Terraform that we support. If you need a specific version of Terragrunt, feel free to create a custom runner image and install the Terragrunt version of your choosing.

Scope of support

We're currently using Terragrunt the same way we're using Terraform, running init, plan, and apply commands. Run-all is supported in our new Terragrunt native platform in Spacelift.

We also support authentication with Spacelift modules by automatically filling the TG_TF_REGISTRY_TOKEN environment variable for each run. Terragrunt uses this variable to authenticate with private module registries.

Debugging Terragrunt

Similar to Terraform, Terragrunt provides an advanced logging mode, and as of the writing of this documentation, there are currently two ways it can be enabled:

1. Using the --terragrunt-log-level debug CLI flag (You'll need to set this flag using the TF_CLI_ARGS environment variable. For example, TF_CLI_ARGS="--terragrunt-log-level debug")

2. Using the TERRAGRUNT_LOG_LEVEL environment variable. Logging levels supported: info (default), panic fatal error warn debug trace

Please refer to the Setting Environment Variables section within our Terraform Debugging Guide for more information on how to set these variables on your Spacelift Stack(s).

For more information on logging with Terragrunt, please refer to the Terragrunt documentation.