> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/infrastructure-as-code-management/new-to-iacm/get-started/terragrunt-get-started.md).
# Get Started With Terragrunt
Use this guide to create a Terragrunt workspace. Provision infrastructure through Harness Infrastructure as Code Management (IaCM).
### What is IaCM?
IaC automates infrastructure management via code. IaCM enhances this by ensuring consistent, accountable, and repeatable deployments. Harness boosts IaCM with [**real-time cost estimation**](/infrastructure-as-code-management/platform/workspaces/cost-estimation.md), [**automated policy enforcement**](/infrastructure-as-code-management/platform/policy-and-governance/terraform-plan-cost-policy.md), and [**drift detection**](/infrastructure-as-code-management/platform/iacm-pipelines/operations-overview.md), ensuring efficient provisioning and compliance with standards.
{% hint style="info" %}
**TERRAFORM TO OPENTOFU MIGRATION**
Harness IaCM supports integration with all **OpenTofu** versions.\
For **Terraform**, we support all MPL versions up to **1.5.x**, any BSL versions (from 1.6.0) are not supported.
Follow this [**OpenTofu migration guide**](https://opentofu.org/docs/intro/migration/) to transition from Terraform to OpenTofu and leverage the benefits of this open-source alternative.
{% endhint %}
Go to [What's Supported in IaCM](/infrastructure-as-code-management/troubleshooting-and-resources/whats-supported.md) for more information on supported Cloud Providers and Code/Git providers.
{% @harness-package-selector/package-selector platforms="%5B%7B%22label%22%3A%22AWS%20CDK%22%2C%22slug%22%3A%22aws-cdk%22%2C%22path%22%3A%22infrastructure-as-code-management%2Fnew-to-iacm%2Fget-started%2Faws-cdk-get-started%22%7D%2C%7B%22label%22%3A%22OpenTofu%22%2C%22slug%22%3A%22opentofu%22%2C%22path%22%3A%22infrastructure-as-code-management%2Fnew-to-iacm%2Fget-started%2Fopentofu-get-started%22%7D%2C%7B%22label%22%3A%22Terragrunt%22%2C%22slug%22%3A%22terragrunt%22%2C%22path%22%3A%22infrastructure-as-code-management%2Fnew-to-iacm%2Fget-started%2Fterragrunt-get-started%22%7D%2C%7B%22label%22%3A%22Terraform%22%2C%22slug%22%3A%22terraform%22%2C%22path%22%3A%22infrastructure-as-code-management%2Fnew-to-iacm%2Fget-started%2Fterraform-get-started%22%7D%5D" selectedPlatform="terragrunt" %}
{% hint style="info" %}
**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.
{% endhint %}
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 you will learn from this topic
This guide covers the following:
* **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`).
### Before you begin
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. Go to [Getting started with Harness Platform](/harness-ai/new-to-harness-platform/get-started.md) to access or create a Harness account.
* **Pipeline permissions:** View, Create/Edit, and Execute on [Pipelines](/harness-ai/use-harness-platform/platform-access-control/permissions-reference.md#pipelines). Go to [RBAC in Harness](/harness-ai/use-harness-platform/platform-access-control.md) to review the permissions model, and go to [Manage roles](/harness-ai/use-harness-platform/platform-access-control/add-manage-roles.md) to assign a role that includes them.
* **Git repository:** Access to a Git provider with your [Terragrunt](https://terragrunt.gruntwork.io/) 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](/harness-ai/new-to-harness-platform/get-started.md) 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](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html) 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/finding-an-ami.html) to find your AMI image ID.
* **Instance Type:** Configures the instance to use a t2.micro. Go to the [AWS t2 instances list](https://aws.amazon.com/ec2/instance-types/t2/).\
Tags: To facilitate easy identification and management within AWS resources, a tag name with the value `my_first_ec2_instance` is applied.
```hcl
provider "aws" {
region = "us-east-1"
}
resource "aws_instance" "my_first_ec2_instance" {
ami = "ami-123abc321cba18"
instance_type = "t2.micro" # Go 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](https://terragrunt.gruntwork.io/docs/) to review 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.
{% hint style="info" %}
Harness recommends configuring your connector before creating your workspace; you can also add new connectors during the [Create Workspace flow](/infrastructure-as-code-management/new-to-iacm/get-started.md#add-a-new-workspace).
{% endhint %}
#### Step 1: create a connector
Use **Harness AI** to create and configure your cloud provider and code repository connectors before you create a workspace:
{% tabs %}
{% tab title="Create a Connector" %}
{% embed url="" %}
Create Cloud Provider Connector with Harness AI
{% endembed %}
{% endtab %}
{% tab title="Step-by-step" %}
When adding any connector, start by:
1. Sign in to [app.harness.io](https://app.harness.io).
2. In the module pane, select **Infrastructure**.
3. Select **Project Setup**, and then select **Connectors**.
4. Select **New Connector (AI)**.
5. Select an option, for example "Create a GitHub connector", or type your request to create a connector for your chosen cloud provider or code repository.
Harness creates a YAML file for your connector. Once you select **Create**, Harness creates your connector and adds it to your project.
{% hint style="info" %}
**EDIT CONNECTOR**
Edit your connector by updating the AI generated YAML file, or by selecting **Edit Details** in the connectors panel.
{% endhint %}
Go to [Connect your Cloud Provider](/harness-ai/use-harness-platform/connectors/cloud-providers.md) and [Connect your Code Repository](/harness-ai/use-harness-platform/connectors/code-repositories/connect-to-code-repo.md) to connect your cloud provider and code repository.
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**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. Go to [the Use OIDC tab](/harness-ai/use-harness-platform/connectors/cloud-providers/ref-cloud-providers/aws-connector-settings-reference.md#credentials) for setup details.
{% endhint %}
***
#### Step 2: create your workspace
Once you have configured your connectors, create a workspace and select those connectors in the **New Workspace** wizard.
{% hint style="info" %}
**MIGRATE EXISTING PROJECTS**
For first-time use, go to [State Migration](/infrastructure-as-code-management/use-iacm/remote-backends/state-migration.md) to import the state of your existing Terraform projects into a Harness workspace.
{% endhint %}
{% tabs %}
{% tab title="Interactive Guide" %}
{% embed url="" %}
Create Terragrunt Workspace in Harness IaCM
{% endembed %}
{% endtab %}
{% tab title="Step-by-step" %}
1. In the module pane, select **Infrastructure**.
2. Select an existing project or create a new project.
3. Select **Workspaces**, and then select **New Workspace**.
4. Select **Create new Workspace**, then select **Start from scratch** and complete the following fields in the new workspace wizard:
**About workspace**
* **Name** - Enter a unique name to identify the workspace.
* **Description (optional)**: Enter an optional description to help identify the workspace.
* **Tags (optional)**: Add a unique tag to identify the workspace.
**Configure repository details**
* Select your Git provider, either **Harness Code Repository** or **Third-party Git provider** for other providers like GitHub or GitLab.
* **Git Connector**: Select the Git connector you created in the previous step.
* **Git Fetch Type**: Select the Git fetch type, either **Latest from branch**, **Git tag** or **Commit SHA**.
* **Git Branch**: Specify the branch you want to use for the workspace.
{% hint style="info" %}
**BRANCH WITH JEXL**
You can configure the workspace branch as a [JEXL expression](/harness-ai/use-harness-platform/variables-and-expressions/harness-variables.md) that references a pipeline variable, and then set the pipeline variable as a runtime input.
Set your branch variable as a runtime input in the pipeline:
```yaml
variables:
- name: iacm_branch
type: String
description: ""
required: true
value: <+input>.default(main)
```
{% endhint %}
* **Folder Path**: Specify the path from the root of the repository to the directory containing your Terragrunt configuration.
{% hint style="info" %}
**OPTIONAL OVERRIDE IN PIPELINE**
The **Folder Path** you set here applies when a Terragrunt pipeline step does not set an override. For a specific run, you can override it with **Folder Path Override** on each Terragrunt step: **init**, **plan**, and **apply**. Go to [Configure Terragrunt folder path override](#configure-terragrunt-folder-path-override) to set it.
{% endhint %}
**Advanced** options allow you to **include submodules** if your code repository includes modules and submodules. Go to [Module Registry](/infrastructure-as-code-management/registry/module-registry.md) to review module registry concepts.
**Provisioner**
* **Connector**: Select the cloud provider connector you created in the previous step.
* **Workspace Type**: Select **Terragrunt** as the workspace type you want to use for the workspace.
* **Terragrunt Version**: Select the Terragrunt version you want to use for the workspace.
* **Terragrunt TF Binary**: Select either Open Tofu or Terraform as your Terragrunt TF binary for your workspace.
* **Terragrunt TF Version**: Select the Open Tofu or Terraform version to use for the Terragrunt TF binary.
* Optional: Run all Terragrunt modules.
{% hint style="info" %}
**RUN ALL TERRAGRUNT MODULES**
When enabled, Harness reviews your Terragrunt modules at both the root level and nested folders and runs all detected Terragrunt modules in your repository as part of a single workspace execution. Disable this option if you prefer to only review Terragrunt modules at the root level.
{% endhint %}
**Add variable set (optional)**
If you have configured variable sets for reuse, select the variable set you want to use for the workspace.
5. Select **Create**.
{% endtab %}
{% endtabs %}
***
#### Step 3: add a provision pipeline
A pipeline structures workflows to manage tasks like planning infrastructure changes, enforcing policies, and approvals. Go to [Harness Pipelines](/harness-ai/use-harness-platform/pipelines.md) to review pipeline concepts. You can also add pipelines through the Harness Platform or [use a code-first approach with YAML](/harness-ai/use-harness-platform/pipelines/create-pipeline-quickstart.md).
**Harness AI pipeline generation**
{% tabs %}
{% tab title="Interactive Guide" %}
{% embed url="" %}
Create a Provision Pipeline in Harness IaCM
{% endembed %}
{% endtab %}
{% tab title="Step-by-step" %}
Start by adding the pipeline:
1. Select the **Infrastructure** module.
2. Select **Pipelines**, then select **Create a Pipeline**.
3. Select an option from Harness AI chat or type a request to generate one, for example:
* "Create a pipeline to Provision an OpenTofu files with an init, plan and apply step."
4. Review the generated YAML and Harness AI chat summary, and make any changes if necessary.
5. Select **Accept**.
{% endtab %}
{% endtabs %}
The Provision operation adds three Terraform plugin steps: `init`, `plan`, and `apply`. Go to [Tofu/Terraform Plugins](/infrastructure-as-code-management/use-iacm/iacm-cli-commands/terraform-plugins.md) to review 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.
{% hint style="info" %}
**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.
{% endhint %}
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.
{% hint style="warning" %}
**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.
{% endhint %}
{% tabs %}
{% tab title="Interactive Guide" %}
{% embed url="" %}
Add Approval step to your OpenTofu Pipeline in Harness IaCM
{% endembed %}
{% endtab %}
{% tab title="Step-by-step" %}
1. From the Pipeline > **Execution** tab, click the **Add** icon between `plan` and `apply`.
2. Click **Add Step**.
3. Under **IACM**, select **IACM Approval**.
4. Name the approval step and click **Apply Changes**.
5. Click **Save**, then click **Run** to run your pipeline.
{% endtab %}
{% endtabs %}
### Next steps
This guide introduced you to the core functionalities and setup of Harness IaCM, from creating workspaces to configuring pipelines. To enhance your experience and team efficiency, get the most out of Harness IaCM's built-in reusable features, including:
* [**Workspace Templates:**](/infrastructure-as-code-management/platform/workspaces/workspace-templates.md) Quickly create new workspaces using pre-defined, customizable templates.
* [**Module Registry:**](/infrastructure-as-code-management/registry/module-registry.md) Share and reuse infrastructure modules across teams to standardize deployments.
* [**Default Pipelines:**](/infrastructure-as-code-management/platform/iacm-pipelines/default-pipelines.md) Start with ready-made pipeline templates to accelerate automation and best practices.
* [**Queue Step:**](/infrastructure-as-code-management/platform/iacm-pipelines/operations-overview.md) Serialize your pipeline execution to track concurrent executions and prevent state conflicts.
* [**Harness CLI:**](/infrastructure-as-code-management/use-iacm/iacm-cli-commands/harness-cli.md) Install the unified CLI to list, get, and execute IaCM workspaces from your terminal.
Go to [Harness AI Chat use cases](/harness-ai/untitled-1/use-harness-ai/use-cases/harness-ai-chat-guide.md) for more use cases on Harness AI, and platform integration.
For an interactive onboarding experience including further use cases and features like \*\*drift detection\*\*, \*\*remote backends\*\*, and \*\*policy enforcement\*\*, check out \[\*\*Harness IaCM self-paced training\*\*]\().