Skip to main content

terragrunt-quickstart

Last updated on
warning

Terragrunt support is currently pending release and will be available soon!

Terragrunt in Harness IaCM

Terragrunt simplifies managing multiple OpenTofu/Terraform modules by orchestrating shared configurations and keeping your infrastructure code consistent across environments.

In Harness IaCM, Terragrunt extends rather than replaces OpenTofu or Terraform—it still runs their plan and apply commands under the hood. When creating a Terragrunt workspace, select your preferred binary (OpenTofu or Terraform) and version to execute infrastructure changes.

Terragrunt in Harness Infrastructure as Code Management (IaCM) lets you run Terragrunt-driven workflows from a workspace backed by your Git repository and cloud connectors, with the same pipeline patterns (init, plan, apply) you use for standalone OpenTofu or Terraform.

Use this guide when you want a repeatable path from connectors and workspace creation through a provision pipeline—including optional per-run Folder Path Override on each Terragrunt pipeline step (init, plan, and apply) for monorepos and multi-environment layouts.

What will you learn?​

  • Connectors and workspace: Create cloud and Git connectors, then create a Terragrunt workspace wired to your repository and provisioner settings.
  • Provision pipeline: Generate or author a pipeline that runs Terragrunt init, plan, and apply (and optionally add an approval between plan and apply).
  • Folder path override: Use the workspace Folder Path as the default, and optionally set Folder Path Override per run on each Terragrunt step (init, plan, and apply).

Prerequisites​

Before you use this guide, ensure you have the following:

  • Harness account with IaCM enabled: You need Infrastructure as Code Management under Infrastructure in Harness when it is entitled on your account. For how to access or create a Harness account, see Getting started with Harness Platform.

    Contact Harness support:

    If IaCM does not appear, see Get started with IaCM or contact your account administrator or Harness Support.

  • Pipeline permissions: You need View, Create/Edit, and Execute for Pipelines. An administrator must assign you a role that includes them. See RBAC in Harness and Manage roles.

  • Git repository: Access to a Git provider with your Terragrunt project.

  • Cloud provider: Access to a cloud provider such as AWS or Google Cloud Platform for the infrastructure you manage.

  • Harness organization and project: An organization and project set up on the Harness Platform.

Sample Terragrunt

The following example Terragrunt (.hcl) file declares:

  • Provider Configuration: Specifies the AWS provider and sets the region to "us-east-1". Go to AWS Regions & Availability Zones for a complete region list.
  • Resource Definition: Creates an EC2 instance with the identifier my_first_ec2_instance.
  • AMI: Utilizes ami-123abc321cba18, go to AWS EC2 User Guide to find your AMI image ID.
  • Instance Type: Configures the instance to use a t2.micro. Go to the AWS t2 instances list.
    Tags: To facilitate easy identification and management within AWS resources, a tag name with the value my_first_ec2_instance is applied.
provider "aws" {
  region = "us-east-1"
}

resource "aws_instance" "my_first_ec2_instance" {
  ami = "ami-123abc321cba18"
  instance_type = "t2.micro" # Got to https://aws.amazon.com/ec2/instance-types/t2/ for a full T2 instance type list.

  tags = {
    Name = "my_first_ec2_instance"
  }
}

Go to Terragrunt Documentation for more information on currently supported workspace types.

Set up your workspace​

A workspace is a named environment for storing your Terragrunt configurations and resources. You connect your cloud provider and code repository through Connectors so Harness IaCM pipelines can run against your repository and credentials.

info

Harness recommends configuring your connector before creating your workspace; you can also add new connectors during the Create Workspace flow.

Step 1: Create a connector​

Use Harness AI to create and configure your cloud provider and code repository connectors before you create a workspace:

OIDC Connectors

For easier access and token management, use the OIDC (OpenID Connect) option in the Credentials panel. This allows your connector to assume roles with permissions set in your Cloud Provider, updated only by authorized users. For more details, visit the Use OIDC tab.

Step 2: Create your workspace​

Once you have configured your connectors, create a workspace and select those connectors in the New Workspace wizard.

migrate existing projects

For first-time use, use our migration tool to create new workspaces and import your existing Terraform projects into the Harness Platform.

Step 3: Add a provision pipeline​

A pipeline structures workflows to manage tasks like planning infrastructure changes, enforcing policies, and approvals. Learn more about Harness Pipelines. You can also add pipelines through the Harness Platform or use a code-first approach with YAML.

Harness AI pipeline generation​

The Provision operation adds three Terraform plugin steps: init, plan, and apply. Go to Tofu/Terraform Plugins for more information about supported OpenTofu/Terraform commands.

Configure Terragrunt folder path override​

Terragrunt provision pipelines use init, plan, and apply steps. Each of these steps exposes an optional Folder Path Override in the pipeline editor (or the equivalent in YAML) so Harness knows which repository directory to use for that step.

  • Folder Path Override (optional): Enter the path from the root of the repository to the directory containing your Terragrunt configuration for this step. When set, it overrides the workspace Folder Path for that step’s execution only.
Folder path precedence

Folder Path Override on a Terragrunt step takes precedence over the Folder Path defined in the workspace configuration for that step. If Folder Path Override is left empty on a step, the workspace Folder Path is used.

For a single run against one directory, use the same override value on init, plan, and apply so every step targets the same Terragrunt context.

Example (monorepo): Set the workspace Folder Path to the repository root so one workspace represents the whole Terragrunt monorepo. For environment-specific runs—for example environments/dev versus environments/prod—set Folder Path Override to that subdirectory on init, plan, and apply for each pipeline execution instead of maintaining a separate workspace per environment.

Step 4: Add an Approval step (optional)​

You can add the Approval step to prompt a review of the previous pipeline stage before proceeding. The most common use case is to add the Approval step between the plan and apply steps so you can review infrastructure changes and estimated costs (if cost estimation is enabled on your workspace) before applying them.

Approval steps hold resources

When using an Approval step, the underlying machine running the pipeline remains active until the approval is resolved. This means it will continue consuming compute resources.