> 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/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/terraform-cloud-deployments.md).

# Terraform Cloud Provisioning

Connect to a Terraform Cloud or Enterprise instance and run your workspaces.

In addition to running Terraform configuration files on the Harness Delegate, Harness supports running **Terraform Cloud and Terraform Enterprise workspaces**. This allows you to use Harness Deploy stages to execute Terraform configurations and manage infrastructure through workspaces hosted in Terraform Cloud or Terraform Enterprise, rather than executing the Terraform configuration directly on the Delegate.

This topic explains how to configure and run **Terraform Cloud and Terraform Enterprise workspaces** in Harness Deploy stages, including connecting Harness to your Terraform environment, selecting a workspace, and using the workspace to provision or manage your target infrastructure.

For details on running Terraform configuration files locally on the delegate, refer to:

* [Provision Target Deployment Infra Dynamically with Terraform](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/provision-infra-dynamically-with-terraform.md)
* [Plan Terraform Provisioning with the Terraform Plan Step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/run-a-terraform-plan-with-the-terraform-plan-step.md)
* [Provision with the Terraform Apply Step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/run-a-terraform-plan-with-the-terraform-apply-step.md)
* [Remove Provisioned Infra with the Terraform Destroy Step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/remove-provisioned-infra-with-terraform-destroy.md)
* [Rollback Provisioned Infra with the Terraform Rollback Step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/rollback-provisioned-infra-with-the-terraform-rollback-step.md)

***

## What you will learn from this topic

* How to create a [Harness Terraform Cloud connector](#harness-connector) to connect to Terraform Cloud or Enterprise.
* How to use the [Terraform Cloud Run step](#configure-the-terraform-cloud-run-step) to execute workspaces with different run types.
* How to configure [Provisioner Identifiers](#provisioner-identifier) to link Plan and Apply operations.
* How to use the [Terraform Cloud Rollback step](#terraform-cloud-rollback-step) to roll back failed runs.
* How to use [complete pipeline examples](#pipeline-example) for both dynamic and ad hoc provisioning workflows with Terraform Cloud.

***

## Before you begin

* **Harness project access**: View, Create/Edit, and Execute permissions on Pipelines and Environments. Go to [RBAC in Harness](https://developer.harness.io/docs/platform/role-based-access-control/rbac-in-harness) to configure roles.
* **Terraform Cloud or Enterprise account**: You need an active Terraform Cloud or Terraform Enterprise account with configured workspaces. Go to [Terraform Cloud documentation](https://developer.hashicorp.com/terraform/cloud-docs) to learn more.
* **Terraform Cloud API token**: You need a User or Team API token with permissions to run the workspace. Organization tokens cannot be used for run creation. Go to [API tokens access levels](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#access-levels) to understand token permissions.
* **Workspace configuration**: Your Terraform Cloud workspace must be configured with execution mode set to **Remote** and connected to a configuration files repository.
* **Harness Delegate**: A delegate must be installed to execute Terraform Cloud steps. Go to [Delegate installation overview](https://developer.harness.io/docs/platform/delegates/install-delegates/overview) to install a delegate.
* **AWS OIDC connector** (optional): If you use an OIDC-enabled AWS connector with Terraform Cloud provisioner, you need Delegate version `854xx` or later. Go to [AWS OIDC connector reference](https://developer.harness.io/docs/platform/connectors/cloud-providers/ref-cloud-providers/aws-connector-settings-reference) to configure OIDC.

***

## Considerations

* The Terraform Cloud workspace must be connected to the repository containing your Terraform configuration files, and its execution mode must be set to **Remote**. Currently, Harness supports running executions in the workspace; workspace configuration is managed in Terraform Cloud.
* To connect Harness to Terraform Cloud, create a **User API token** or **Team API token** in Terraform Cloud and configure it in the Harness connector. Organization API tokens are not supported for creating runs. Go to [API tokens access levels](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens#access-levels) to understand required permissions.
* You can add Terraform Cloud steps to any **Deploy** or **Custom** stage.
* Harness supports using a Terraform Cloud provisioner with an **OIDC-enabled AWS connector**. This requires Delegate version `854xx` or later. Go to [AWS OIDC connector reference](https://developer.harness.io/docs/platform/connectors/cloud-providers/ref-cloud-providers/aws-connector-settings-reference) to configure OIDC.

## Harness connector

The Harness Terraform Cloud connector connects your Harness account with your Terraform Cloud or Enterprise account.

You can create the Terraform Cloud connector and then select it in each of the Terraform Cloud steps you add to your pipeline.

The Terraform Cloud connector uses a [Terraform Cloud API token](https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens) for authentication.

To add the Terraform Cloud connector, do the following:

{% tabs %}
{% tab title="YAML" %}
The following is an example of the YAML for a Terraform Cloud connector.

<details>

<summary>Terraform Cloud connector YAML example</summary>

```yaml
connector:
  name: TF Cloud connector
  identifier: TF_Cloud_connector
  description: ""
  orgIdentifier: default
  projectIdentifier: TerraformCloud_Doc_team
  type: TerraformCloud
  spec:
    terraformCloudUrl: https://app.terraform.io
    credential:
      type: ApiToken
      spec:
        apiToken: account.terraformconnector
    executeOnDelegate: true

```

</details>
{% endtab %}

{% tab title="API" %}
Create the Terraform Cloud connector using the [Create a Connector](https://apidocs.harness.io/tag/Connectors#operation/createConnector) API.

<details>

<summary>Terraform Cloud connector API example</summary>

```yaml
curl --location --request POST 'https://app.harness.io/gateway/ng/api/connectors?accountIdentifier=12345' \
--header 'Content-Type: text/yaml' \
--header 'x-api-key: pat.12345.6789' \
--data-raw 'connector:
  name: TF Cloud connector
  identifier: TF_Cloud_connector
  description: ""
  orgIdentifier: default
  projectIdentifier: TerraformCloud_Doc_team
  type: TerraformCloud
  spec:
    terraformCloudUrl: https://app.terraform.io
    credential:
      type: ApiToken
      spec:
        apiToken: account.terraformconnector
    executeOnDelegate: true'
```

</details>
{% endtab %}

{% tab title="Pipeline Studio" %}
You can create a Terraform Cloud connector in the Harness UI using Pipeline Studio. The connector authenticates with Terraform Cloud or Enterprise using an API token and enables Harness to execute workspace runs.

Perform the following steps to create the connector:

1. In your Harness project, select **Project Settings**, and then select **Connectors**.
2. Select **New Connector**, and then select **Terraform Cloud**.
3. Enter a name for the connector and select **Continue**.
4. Enter the URL for Terraform Cloud, such as `https://app.terraform.io`.
5. In **API Token**, create or select a Harness secret containing your Terraform Cloud API token, and then select **Continue**.
6. In **Connect to the provider**, select whether to connect using a delegate or Harness Platform, and then select **Continue** or **Save and Continue**.
   * If you selected to connect using a delegate, select one or more delegates.
7. Select **Finish**. Harness verifies the connection.
   {% endtab %}
   {% endtabs %}

## Configure the Terraform Cloud Run step

The Terraform Cloud Run step uses the Terraform Cloud connector to connect to your Terraform Cloud or Terraform Enterprise account and run a workspace. Configure the required basic settings to specify the workspace and execution details, and use the optional settings to customize the run behavior as needed.

## Basic settings

Configure the following basic settings for the Terraform Cloud Run step.

{% hint style="info" %}
**The available configuration options differ based on the Run type you select. Some fields and settings appear only for specific run types.**
{% endhint %}

### Name

Enter a name for the step. You can use this name in expressions to reference the step in other parts of the pipeline.

### Timeout

Enter the maximum time Harness should wait for the Terraform Cloud run to complete before timing out the step. The default is 10 minutes.

### Run type

Select the type of Terraform Cloud run to execute. The Terraform Cloud Run step can perform the following run types.

* **Plan**: A plan is a Terraform Cloud run that generates an execution plan that describes the changes that Terraform will make to the infrastructure in order to match the configuration code. The plan step is typically used to preview changes before actually applying them. It provides insights into what resources will be created, modified, or destroyed, and what actions will be taken by Terraform to achieve the desired state.

  <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Refresh command option</strong></p><p>When you select <strong>Plan</strong> or <strong>Plan Only</strong> run type, you can enable the <strong>Refresh</strong> command option. This triggers a refresh plan in Terraform Enterprise without auto-approval. Harness waits for manual approval before proceeding. You can review and approve or reject the refresh plan within Harness (using an Approval step) or directly in the Terraform Cloud UI. If no approval action is taken within the configured timeout, the pipeline fails and the run is marked as expired. This feature requires delegate version <code>857xx</code> or later.</p></div>
* **Apply**: An apply run is a Terraform Cloud run that applies the changes described in the execution plan generated by a previous plan run. The apply step is used to make the actual changes to the infrastructure resources based on the configuration code. When an apply run is executed, Terraform will create, modify, or destroy resources as needed to bring the infrastructure into the desired state.
* **Refresh**: A refresh run is a Terraform Cloud run that updates the state of the infrastructure resources with the current state of the cloud environment. This can be useful if there have been changes made to the infrastructure outside of Terraform, and you need to update the state to reflect those changes.
* **Plan Only**: A plan-only run is a Terraform Cloud run that generates an execution plan but cannot apply it. This can be useful for previewing changes and verifying that the desired changes will be made without actually applying them. The **Refresh** command option is also available for this run type (see Plan note above).
* **Plan and Apply**: A plan-and-apply run is a Terraform Cloud run that generates an execution plan and then applies the changes to the infrastructure based on that plan. This is a combination of the plan and apply steps, and is often used when you are confident in the changes that will be made and want to apply them without previewing them first.
* **Plan and Destroy**: A plan-and-destroy run is a Terraform Cloud run that generates an execution plan and then destroys all of the infrastructure resources that are managed by the Terraform configuration. This can be useful if you want to delete the entire infrastructure environment, such as when decommissioning a project or environment.

### Discard pending runs

This setting is supported in the following run types: Plan, Refresh, Plan Only, Plan and Apply, Plan and Destroy. It is also supported in the Terraform Cloud Rollback step.

A pending run is a Terraform run that has been queued but has not yet started executing. Enabling **Discard Pending Runs** allows you to cancel or discard a pending Terraform run before it is applied to the infrastructure environment.

When enabled, any pending runs associated with that workspace will be cancelled and removed from the queue. This can be useful if you want to cancel a run that was initiated accidentally or if you want to prevent a run from being applied due to a change in requirements or a mistake in the configuration.

Discarding a pending run does not delete the associated configuration files or modify the state of the infrastructure resources. It simply removes the run from the queue and prevents it from being applied.

### Run message

This setting is supported in the following run types: Plan, Refresh, Plan Only, Plan and Apply, Plan and Destroy.

Use **Run Message** to add a custom message or comment to a Terraform run. The run message can be used to provide additional context or information about the run, such as the reason for the changes, the status of the infrastructure resources, or any other relevant details.

### Select connector

This setting is supported in the following run types: Plan, Refresh, Plan Only, Plan and Apply, Plan and Destroy.

Select the Harness Terraform Cloud connector to use when running this step. Ensure the Terraform Cloud API token used in the connector has the permissions needed to run the workspace and is scoped to the workspace.

### Organization

This setting is supported in the following run types: Plan, Plan Only, Refresh, Plan and Apply, Plan and Destroy.

Select the Terraform Cloud organization that includes the workspace you want to run.

### Project (optional)

Select the **Project** that includes the workspace you want to run.

This field is **optional**. If you populate it, the list of workspaces in the dropdown will be filtered to show only those associated with the selected project.

If left blank, all workspaces within the specified organization will be displayed.

### Terraform workspace

Select the workspace to run.

### Command

This setting is supported in the following run types: Plan, Plan Only.

In **Command**, select **Apply** or **Destroy**.

* **Apply**: The plan will be applied by a Terraform Cloud step using the **Apply** run type later in your stage. Even though you are only running a Terraform plan in this step, you identify that this step can be used with a Terraform Cloud step using the **Apply** run type later.
* **Destroy**: The plan will be created with the [destroy mode](https://developer.hashicorp.com/terraform/cli/commands/plan#planning-modes).

### Terraform Version

This setting is supported in the following run types: Plan Only.

Select the Terraform version to run.

### Provisioner identifier

This setting is supported in the following run types: Plan, Apply, Plan Only, Plan and Apply, Plan and Destroy.

The **Provisioner Identifier** is a unique value that identifies the provisioning done in each Terraform Cloud Run step.

You use the Provisioner Identifier to reference specific provisioning across Terraform Cloud Run and Terraform Cloud Rollback steps.

The most common use of **Provisioner Identifier** is between Terraform Cloud Run steps performing Plan (or Plan Only) and Apply run types.

For the Terraform Cloud Run **Apply** run type to apply the provisioning from the Terraform Cloud Run **Plan** run type, you use the same **Provisioner Identifier** in both steps.

To rollback the provisioning done by that Terraform Cloud Run **Apply** run type, you would use the same **Provisioner Identifier** in the Terraform Cloud Rollback step.

{% hint style="info" %}
**The Provisioner Identifier is a pipeline-wide setting. You can reference it across stages in the same pipeline.**

For this reason, it is important that all your project members know the Provisioner Identifiers. This will prevent one member building a pipeline from accidentally impacting the provisioning of another member pipeline.
{% endhint %}

## Optional configuration

The following settings are available under **Optional Configuration** in the Terraform Cloud Run step:

### Variables

This setting is supported in the following run types: Plan, Refresh, Plan Only, Plan and Apply, Plan and Destroy.

Enter any workspace environment variables.

### Targets

This setting is supported in the following run types: Plan, Refresh, Plan Only, Plan and Apply, Plan and Destroy.

Enter any workspace targets to limit the scope of a Terraform run to a specific set of resources or modules. This allows you to apply changes to a subset of your infrastructure resources without impacting the entire environment.

### Export JSON representation of Terraform Plan

This setting is supported in the following run types: Plan and Plan Only.

Enable this setting to use a JSON representation of the Terraform plan that is implemented in a Terraform Cloud Run step.

In subsequent execution steps, such as a Shell Script step, you can reference the Terraform plan using this expression format:

```
<+terraformCloudPlanJson."id">
```

### Continue on Soft Mandatory Policy evaluation result

This setting is supported in the following run types:

* Plan and Apply
* Plan and Destroy

It is also supported in the Terraform Cloud Rollback step.

Soft Mandatory policies allow you to specify certain compliance requirements or best practices for your infrastructure code, but which do not block the deployment process if the policy check fails. Instead, they generate a warning or informational message and allow the deployment to proceed.

Enable the **Continue on Soft Mandatory Policy evaluation result** option to specify how to handle Soft Mandatory policies that generate warnings or informational messages during the deployment process. This option is the same as the option in the Terraform Cloud UI when configuring a workspace's policy sets.

When **Continue on Soft Mandatory Policy evaluation result** is enabled, Terraform Cloud will proceed with the deployment even if a Soft Mandatory policy check generates a warning or informational message.

If **Continue on Soft Mandatory Policy evaluation result** is disabled, Terraform Cloud will treat Soft Mandatory policy warnings or informational messages as errors and block the deployment process until the policy check result is resolved. This can help to ensure that your infrastructure deployments adhere to organizational standards and best practices.

## Terraform Cloud expressions

You can use Harness expressions to display the plan JSON and policy checks.

The expressions can be copied from the Terraform Cloud Run step's **Output** tab when the Run Type is **Plan** or **Plan Only**.

### Print plan expression

Use the expression `<+terraformCloudPlanJson."id">` after the Terraform Cloud Run step to print the plan.

For example:

```
cat <+terraformCloudPlanJson."id">
```

### Print policy checks

Use the expression `<+policyChecksJson."id">` to print the Sentinel checks involved in the run.

For example:

```
cat <+policyChecksJson."id">
```

***

## Terraform Cloud Run step YAML

This section provides the YAML structure for the Terraform Cloud Run step.

<details>

<summary>TerraformCloudRun step YAML example</summary>

```yaml
# Terraform Cloud Run Step
# This step triggers runs in Terraform Cloud workspaces

- step:
    type: TerraformCloudRun
    name: Terraform Cloud Run
    identifier: TF_Cloud_Run
    spec:
      # Run type determines what operation to perform
      # Options: Plan, Apply, PlanAndApply, PlanAndDestroy, RefreshState
      runType: PlanAndApply
      
      # Message displayed in Terraform Cloud UI for this run
      runMessage: "Triggered from Harness Pipeline"
      
      # Nested spec containing workspace and authentication details
      spec:
        # Unique identifier linking Plan, Apply, and Rollback steps
        provisionerIdentifier: my_terraform_provisioner
        
        # Reference to Terraform Cloud connector
        connectorRef: account.TerraformCloud
        
        # Terraform Cloud organization name
        organization: my-tfc-organization
        
        # Workspace ID (not workspace name - find in TFC Settings → General)
        workspace: ws-XXXXXXXXXXXXX
        
        # Optional: Terraform Cloud project ID
        project: prj-XXXXXXXXXXXXX
        
        # Discard any pending runs before starting this run
        discardPendingRuns: true
        
        # Pass Terraform variables to the workspace
        variables:
          - name: environment
            value: production
            valueType: string  # Options: string, hcl
          - name: instance_count
            value: "3"
            valueType: string
        
        # Override policy checks (requires appropriate permissions)
        overridePolicies: false
        
        # Target specific resources
        targets: []
    
    # Step timeout
    timeout: 30m
```

</details>

***

## Terraform Cloud Rollback step

The Terraform Cloud Rollback step triggers a rollback of the latest run on your Terraform Cloud workspace. When a rollback is performed, Harness reverts the workspace to the previous successful state. The cleanup methods also run a decline step on any plans that have not been applied.

### Configure the rollback step

To configure the Terraform Cloud Rollback step, do the following:

1. In your pipeline, navigate to the **Rollback** section of your stage.
2. Select **Add Step**, and then select **Terraform Cloud Rollback**.
3. Enter a **Name** for the step.
4. In **Provisioner Identifier**, enter the same unique identifier used in the Terraform Cloud Run step that ran the workspace. This links the rollback step to the specific provisioning operation you want to revert.
5. Configure any optional settings such as **Discard Pending Runs** or **Continue on Soft Mandatory Policy evaluation result** as needed.
6. Select **Apply Changes**.

The rollback step uses the same Terraform Cloud connector and workspace configuration as the original Terraform Cloud Run step.

### Terraform Cloud Rollback step YAML

This section provides the YAML structure for the Terraform Cloud Rollback step.

<details>

<summary>TerraformCloudRollback step YAML example</summary>

```yaml
# Terraform Cloud Rollback Step
# This step reverts a Terraform Cloud workspace to its previous successful state

- step:
    type: TerraformCloudRollback
    name: Rollback Terraform Cloud Run
    identifier: TF_Cloud_Rollback
    spec:
      # CRITICAL: Must match the provisionerIdentifier from TerraformCloudRun step
      provisionerIdentifier: my_terraform_provisioner
      
      # Reference to Terraform Cloud connector (same as TerraformCloudRun step)
      connectorRef: account.TerraformCloud
      
      # Terraform Cloud organization name (same as TerraformCloudRun step)
      organization: my-tfc-organization
      
      # Workspace ID (same as TerraformCloudRun step)
      workspace: ws-XXXXXXXXXXXXX
      
      # Optional: Discard any pending runs before performing rollback
      discardPendingRuns: false
      
      # Optional: Continue execution even if soft mandatory policies fail
      continueOnSoftMandatoryPolicyEvalResult: false
    
    # Step timeout
    timeout: 10m
```

</details>

***

## Open Policy Agent (OPA) policy support

Harness now fetches and evaluates **Open Policy Agent (OPA)** policies alongside **Sentinel** policies in your Terraform Cloud Run step.

{% hint style="info" %}
**Delegate version requirement**

This feature needs delegate version `858xx` or above.
{% endhint %}

* Harness invokes the Terraform Cloud **Task Stages** and **Policy Evaluations** APIs to pull down both Sentinel and OPA policy results.
* Results for OPA policies appear under a **Policy Evaluation** section in the step logs.
* **Enforcement levels**: OPA policies support two enforcement types: **Advisory** (warnings only, run continues) and **Mandatory** (fail the run unless overridden).
* **Override support**: For policies marked as `overridable`, you can let the run continue despite a mandatory OPA failure by selecting the **Continue on Soft Mandatory Policy evaluation result** checkbox in the Terraform Cloud Run step UI (or via the corresponding API action).

For more information on **Open Policy Agent (OPA)** policies, refer [Terraform documentation](https://www.openpolicyagent.org/docs/latest/terraform/)

{% hint style="info" %}
**Any mandatory OPA policy failure will automatically fail the pipeline stage.**
{% endhint %}

{% hint style="warning" %}
**Policy checks are deprecated and will be permanently removed in August 2025. We recommend that you start using policy evaluations to avoid disruptions.** [**Learn more**](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/policy-checks)
{% endhint %}

***

## Pipeline example

The following example demonstrates a tested, working configuration using Terraform Cloud Agents running in-cluster. This approach allows Terraform Cloud to provision resources in private Kubernetes clusters without requiring public API access.

<details>

<summary>Terraform Cloud Agent Pipeline YAML</summary>

```yaml
# Terraform Cloud Run Provisioning - Working Example
# This pipeline uses Terraform Cloud with in-cluster agents
# Tested configuration for provisioning Kubernetes namespaces via Terraform Cloud

pipeline:
  name: Terraform Cloud Run Provisioning
  identifier: TF_CloudRun_AdHoc
  projectIdentifier: KrishnamoorthyTest  # Replace with your project
  orgIdentifier: default
  tags: {}
  description: Ad-hoc provisioning using Terraform Cloud Run step
  
  # Pipeline variables
  variables:
    # Unique identifier linking TerraformCloudRun and TerraformCloudRollback steps
    - name: provisioner_id
      type: String
      value: tf_cloud_run
    # Terraform Cloud organization name
    - name: tf_organization
      type: String
      value: HarnessTesting  # Replace with your TFC organization
    # Terraform Cloud workspace name
    - name: tf_workspace
      type: String
      value: harnesscd-example-apps  # Replace with your workspace
  
  stages:
    - stage:
        name: Terraform Cloud Provision
        identifier: TF_Cloud_Provision
        type: Deployment
        spec:
          deploymentType: Kubernetes
          
          # Service reference
          service:
            serviceRef: PielineK8S_service  # Replace with your service
          
          # Environment configuration
          environment:
            environmentRef: testenv  # Replace with your environment
            deployToAll: false
            infrastructureDefinitions:
              - identifier: dynamicTF  # Replace with your infrastructure
          
          # Execution steps
          execution:
            steps:
              # Step 1: Terraform Cloud Run - PlanAndApply
              - step:
                  type: TerraformCloudRun
                  name: Terraform Cloud Run
                  identifier: TF_Cloud_Run
                  spec:
                    # Run type: PlanAndApply executes both plan and apply
                    runType: PlanAndApply
                    # Message displayed in Terraform Cloud UI
                    runMessage: "Harness Pipeline: TFC integration test"
                    # Nested spec (REQUIRED for TerraformCloudRun)
                    spec:
                      # CRITICAL: Must match across Plan/Apply/Rollback steps
                      provisionerIdentifier: <+pipeline.variables.provisioner_id>
                      # Terraform Cloud connector reference
                      connectorRef: tfcloud  # Replace with your connector identifier
                      # Terraform Cloud organization
                      organization: HarnessTesting  # Replace with your organization
                      # Workspace ID (not workspace name!)
                      # Find in TFC UI: Settings → General → Workspace ID
                      workspace: ws-X2zgfrrrtWA9jESf  # Replace with your workspace ID
                      # Discard any pending runs before starting this one
                      discardPendingRuns: true
                      # Optional: Terraform Cloud project ID (if using projects)
                      project: prj-kP8NgQmYEo2M6XhH  # Replace or remove if not using
                      # Pass variables to Terraform (optional)
                      variables: []
                      # Override policy checks if needed (optional)
                      overridePolicies: false
                      # Target specific resources (optional)
                      targets: []
                  timeout: 30m
              
              # Step 2: Display run information
              - step:
                  type: ShellScript
                  name: Display Outputs
                  identifier: Display_Outputs
                  spec:
                    shell: Bash
                    source:
                      type: Inline
                      spec:
                        script: |
                          echo "Step Identifier: TF_Cloud_Run"
                          echo "Provisioner ID: tf_cloud_run"
                          # Run ID from Terraform Cloud (available after run completes)
                          echo "Run ID: <+pipeline.stages.TF_Cloud_Provision.spec.execution.steps.TF_Cloud_Run.runData.runId>"
                    executionTarget: {}
                    environmentVariables: []
                    outputVariables: []
                  timeout: 5m
            
            # Rollback steps (executed on failure)
            rollbackSteps:
              - step:
                  type: TerraformCloudRollback
                  name: Rollback
                  identifier: TF_Cloud_Rollback
                  spec:
                    # CRITICAL: Must match TerraformCloudRun provisionerIdentifier
                    provisionerIdentifier: <+pipeline.variables.provisioner_id>
                    # Same connector as TerraformCloudRun step
                    connectorRef: tfcloud
                    # Same organization as TerraformCloudRun step
                    organization: <+pipeline.variables.tf_organization>
                    # Same workspace as TerraformCloudRun step
                    workspace: <+pipeline.variables.tf_workspace>
                  timeout: 10m
        
        # Failure strategy - triggers rollback on any error
        failureStrategies:
          - onFailure:
              errors:
                - AllErrors
              action:
                type: StageRollback
```

**Key configuration notes:**

1. **Workspace ID vs. Workspace Name**
   * The `workspace` field requires the **workspace ID** (starts with `ws-`), not the workspace name
   * Find it in Terraform Cloud: **Settings → General → Workspace ID**
   * Example: `ws-X2zgfrrrtWA9jESf`
2. **Output Access**
   * Terraform outputs are not directly accessible in Harness expressions
   * Outputs are available in Terraform Cloud UI under workspace Outputs tab
   * Use Kubernetes verification steps to check provisioned resources
   * Run ID available via: `<+pipeline.stages.STAGE_ID.spec.execution.steps.STEP_ID.runData.runId>`

</details>

## Troubleshooting

<details>

<summary>Terraform Cloud Run step fails with authentication error</summary>

Verify the Terraform Cloud API token in the connector has the required permissions. User and Team API tokens are supported, but Organization tokens cannot be used for run creation. For more information, refer to the Terraform Cloud documentation on API token access levels.

</details>

<details>

<summary>Workspace not found when selecting Terraform workspace</summary>

Ensure the workspace exists in the selected organization and the API token has access to it. Check that the workspace execution mode is set to Remote in Terraform Cloud settings. Verify the connector is configured with the correct Terraform Cloud URL.

</details>

<details>

<summary>Terraform Cloud Run step times out waiting for manual approval</summary>

Check the configured timeout value in the step settings. If no approval action is taken within the timeout period, the pipeline fails and the run is marked as expired. Review and approve the run in the Terraform Cloud UI or add a Harness Approval step before the Terraform Cloud Run step.

</details>

<details>

<summary>Policy check failure blocks Terraform Cloud Run</summary>

Review the policy check results in the step logs under the Policy Evaluation section. For Soft Mandatory policies, enable Continue on Soft Mandatory Policy evaluation result in the step settings to proceed. For Mandatory policies, resolve the policy violation in your configuration before re-running.

</details>

<details>

<summary>OPA or Sentinel policies not appearing in step logs</summary>

Ensure your delegate version is 858xx or above for Open Policy Agent (OPA) policy support. Verify that policies are configured in your Terraform Cloud workspace settings. Check that the API token has permissions to read policy evaluations.

</details>

***

## Next steps

* [Terraform Plan step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/run-a-terraform-plan-with-the-terraform-plan-step.md): Run Terraform locally on the delegate.
* [Terraform Apply step](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/run-a-terraform-plan-with-the-terraform-apply-step.md): Apply Terraform configurations locally.
* [Terraform provisioning overview](/continuous-delivery/use-continuous-delivery/provision-infrastructure/terraform-infra/terraform-provisioning-with-harness.md): Understand the complete Terraform workflow in Harness.

{% @harness-feedback/feedback %}