Terragrunt

Terragrunt is an open-source wrapper around Terraform and OpenTofu that organizations use to help keep code DRY. If used in Scalr, Scalr will use all of the Terragrunt commands on top of Terraform or OpenTofu, depending on the pipeline settings.

Configuration

To add Terragrunt, go to the account scope in Scalr, the integrations page, and select Terragrunt. Once selected, it can be enabled for the entire account for use:

There are optional checks that can be enabled for all workspaces that are using Terragrunt:

  • terragrunt hclvalidate - Finds all hcl files from the config stack and validates them.
  • terragrunt hclfmt - Recursively find hcl files and rewrite them into a canonical format with the check mode enabled.
  • terragrunt validate-inputs - Checks if the Terragrunt configured inputs align with the Terraform defined variables.

It will be available to all workspaces once the changes are saved.

Using Terragrunt

End users can enable Terragrunt at the workspace when creating a workspace or by updating the pipeline afterward. When creating a workspace, users are prompted to select the IaC platform (Terraform or OpenTofu and whether or not it should run with Terragrunt:

If Terragrunt is being added after a workspace has already been created, it can be added in the pipeline settings:

Users will see in the run that Terragrunt is being used to execute the commands:

Run-All

The run-all feature in Terragrunt is a powerful command that allows users to orchestrate Terraform or OpenTofu commands across multiple modules in a single execution. It simplifies managing complex infrastructure with multiple dependencies by handling the execution order and dependencies automatically.

When using run-all with Scalr:

  • A non-Scalr remote backend must be added to each unit to manage the state. See more here.
  • Terragrunt will automatically execute the run-all commands across all relevant modules defined in the workspace.
  • Users can observe the execution logs in the Scalr interface, showing the commands being run for each module.
  • Dependency resolution ensures a smooth workflow even in complex stacks.

The Terragrunt run-all option in Scalr is available in environments where the Scalr backend is disabled. To use run-all, ensure backend configurations are managed in your terragrunt.hcl files and Scalr's backend is disabled for the environment.

While creating or editing workspace in the Pipeline Setting section:

  • Enable Use Terragrunt toggle
  • Select Terragrunt version (0.69.1 or higher)
  • Set Execute run-all commands on multiple units at once check-box to true

To use run-all, the workspace must use Terragrunt version 0.69.1 or greater. At this point, run-all workspaces do not support the following (they will be supported in the future):

  • Structured plan output
  • Cost estimation
  • Policy checks
  • Downloading of plan JSON
  • Outputs

CLI-Driven Workflow

Terragrunt can be used in a VCS or CLI-driven workspace. If used in a CLI-driven workspace, one extra step is needed to add the Scalr remote backend for remote execution. To establish a connection with the remote workspace, you have to add the following code to the terragrunt.hcl file:

generate "backend" {
  path      = "backend.tf"
  if_exists = "overwrite"
  contents  = <<EOF
terraform {
  backend "remote" {
    hostname     = "<account>.scalr.io"
    organization = "<scalr-environment-name-or-ID>"

    workspaces {
      name = "<workspace-name>"
    }
  }
}
EOF
}

The code above automatically generates a remote backend configuration, which will be used to upload the source code and execute it remotely.

CLI Runs in "run-all" Workspaces

There are a few limitations you have to consider in the "run-all" workspaces:

  1. The root of the run-all workspace should have the terragrunt.hcl file with the remote backend block added, as seen above.
  2. Units inside the run-all workspace must be configured to use any state backend (S3, Azure, GCP, etc), theremote backend type is not recommended. If a remote backend is added to each unit, OpenTofu/Terraform will create separate remote workspaces, and each unit run will be tracked as individual runs.
  3. To trigger a CLI-driven run, you have to call simple commands (terragrunt plan or terragrunt-apply) instead of the terragrunt run-all <command> equivalent. The terragrunt run-all <command> will cause a local execution of the dependent units.