---
title: "Terraform Cloud (TFC) Run Task Integration"
description: "Configure the Terraform Cloud Run Task to scan Terraform plans with Nirmata Control Hub and Kyverno."
diataxis: how-to
applies_to:
  product: "nirmata-control-hub"
audience: ["platform-engineer","admin"]
last_updated: 2026-04-16
url: https://docs.nirmata.io/docs/control-hub/settings/integrations/terraformintegration/
---

The **Terraform Cloud (TFC)** Run Task integration enables automatic scanning of Terraform plans using the **Nirmata Control Hub** and **Kyverno** for policy compliance.  

This ensures Terraform infrastructure changes are validated against enterprise policies before being applied.

---

## Prerequisites

Before you begin, ensure that you have:

- A **Terraform Cloud (TFC)** organization with permissions to create Run Tasks.  
- A **Nirmata Control Hub** tenant with administrative access.  
- Access to a **Git provider** (GitHub required for MVP; GitLab and Bitbucket optional for future integrations).  

---

For an explanation of how the integration works and its key components, see [Terraform Cloud Integration Overview](overview/).

---

## Step-by-Step Configuration

### Step 1: Enable Integration in Nirmata Control Hub

1. Log in to your **Nirmata Control Hub** instance.  
2. Navigate to **Integrations → Terraform**.  
3. Copy the generated **Webhook URL** and **Shared HMAC Key**.  

### Step 2: Add a Run Task in Terraform Cloud

1. In **Terraform Cloud**, go to **Settings → Run Tasks → Create Run Task**.  
2. Provide a descriptive name (e.g., `Nirmata Policy Scan`).  
3. Paste the **Webhook URL** from Nirmata Control Hub.  
4. Enter the **Shared HMAC Key** into the **HMAC Secret** field.  
5. Assign the Run Task to one or more workspaces where you want policy scans to run.  

### Step 3: Trigger a Terraform Run

1. Execute a **terraform plan** or **apply** in the configured workspace.  
2. Terraform Cloud sends the plan payload to the **Nirmata Terraform Service**.  
3. The service runs compliance scans using default public policy sets.  
4. The pass/fail status is displayed in the Terraform Cloud run UI.  

### Step 4: View Results in Nirmata Control Hub

- Go to **Integrations → Terraform → Runs** in Nirmata Control Hub to view detailed scan results, violations, and policy summaries.  

---

## Next Steps

- Explore **custom policy sets** in Nirmata Control Hub for Terraform security and compliance.  
- Visit the [Nirmata Documentation Portal](https://docs.nirmata.io) for additional configuration and troubleshooting guides.


---

## Terraform Cloud Integration Overview


> **Applies to:** Nirmata Control Hub 4.0 and later

When a Terraform run reaches the **Plan** stage, **Terraform Cloud** triggers a webhook to the **Nirmata Terraform Service**.
This service evaluates the Terraform plan using **NCTL** (Nirmata CLI) and policy sets managed within Nirmata Control Hub.
The results are returned to TFC as pass/fail compliance checks.

## Key Components

| Component | Description |
|------------|-------------|
| **Nirmata Control Hub Webapp & API** | Manages integrations, authentication keys, and displays scan results. |
| **Terraform Service** | Receives webhooks, fetches policy sets, and invokes NCTL scans. |
| **NCTL** | CLI tool that evaluates Terraform plans against Nirmata and Kyverno policy sets. |
| **TFC Run Task** | Executes during Terraform plan runs and triggers compliance scans. |

## Architecture

```text
flowchart TD
    A[TFC Run Task Triggered] --> B[Nirmata Terraform Service (Webhook)]
    B --> C[Policy Fetch (from Nirmata Control Hub / Git)]
    C --> D[NCTL Policy Scan]
    D --> E[Results sent to Terraform Cloud & Nirmata Control Hub]
```

**Flow Summary:**
`Terraform Cloud Run → Webhook (Terraform Service) → Policy Fetch (Nirmata Control Hub/Git) → NCTL Scan → Results → TFC/Nirmata Control Hub`

**Key Notes:**
- Run data, credentials, and findings are securely stored in Nirmata for **auditability**.
- **Observability** is available through integrated logs, metrics, and traces.

## Next Steps

To configure this integration, see [Terraform Cloud Run Task Integration](./) for step-by-step instructions.