Terraform Cloud (TFC) Run Task Integration

Configure the Terraform Cloud Run Task to scan Terraform plans with Nirmata Control Hub and Kyverno.

The Terraform Cloud (TFC) Run Task integration enables automatic scanning of Terraform plans using the Nirmata Control Hub (NCH) 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 (NCH) tenant with administrative access.
  • Access to a Git provider (GitHub required for MVP; GitLab and Bitbucket optional for future integrations).

Integration Overview

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 NCH.
The results are returned to TFC as pass/fail compliance checks.

Key Components

ComponentDescription
NCH Webapp & APIManages integrations, authentication keys, and displays scan results.
Terraform ServiceReceives webhooks, fetches policy sets, and invokes NCTL scans.
NCTLCLI tool that evaluates Terraform plans against Nirmata and Kyverno policy sets.
TFC Run TaskExecutes during Terraform plan runs and triggers compliance scans.

Step-by-Step Configuration

Step 1: Enable Integration in NCH

  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 NCH.
  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 NCH

  • Go to Integrations → Terraform → Runs in NCH to view detailed scan results, violations, and policy summaries.

Architecture Summary

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

Flow Summary:
Terraform Cloud Run → Webhook (Terraform Service) → Policy Fetch (NCH/Git) → NCTL Scan → Results → TFC/NCH

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

  • Explore custom policy sets in NCH for Terraform security and compliance.
  • Visit the Nirmata Documentation Portal for additional configuration and troubleshooting guides.