Nirmata Terraform Controller

A policy enforcement layer for Terraform that uses Kyverno to ensure every change meets organizational standards.

Overview

The Nirmata Terraform Controller (Nirmata Terraform Controller) enables policy enforcement for Terraform Cloud (TFC) workloads by validating Terraform plans against Kyverno policies. Nirmata Terraform Controller runs inside a Kubernetes cluster, synchronizes Kyverno policies that are versioned in Git and applied to the same cluster, and exposes endpoints that can be invoked by Terraform Cloud Agents during plan execution.

This document provides installation‑focused guidance for setting up Nirmata Terraform Controller in a Kubernetes environment. It excludes integration and implementation workflows, which are covered in a separate document.

Prerequisites

Kubernetes: v1.23 or later
Helm: v3.8 or later
Network connectivity: Terraform Cloud Agent must be able to send requests to the Nirmata Terraform Controller /scan or /runtask endpoint.
Kyverno policies: Maintain the policies in Git and ensure they are applied to the cluster where Nirmata Terraform Controller is deployed. Nirmata Terraform Controller reads and processes the policies from the same cluster.

Installation

Installation Using Helm Repository (Recommended)

Add the Nirmata Helm repository

helm repo add nirmata https://nirmata.github.io/terraform-cloud-run-task
helm repo update
```text


##### Install with API key for standalone mode (TFC agent hooks)

```bash 

helm install ntc nirmata/nirmata-terraform-controller --set secrets.apiKey="$(openssl rand -base64 32)" --namespace ntc --create-namespace
```text

##### Or install with an existing internal secret

```bash

helm install ntc nirmata/nirmata-terraform-controller --set secrets.existingSecret="my-ntc-secret" --namespace ntc --create-namespace

```text

### From OCI Registry

```bash
helm install ntc oci://ghcr.io/nirmata/charts/nirmata-terraform-controller --set secrets.apiKey="your-api-key" --namespace ntc --create-namespace
```text


## Nirmata Terraform Controller Helm Configuration Options

You can customize policy behavior during installation using Helm values.


### Defaults

- Audit mode enabled  
- Policy reports enabled  

### Configuration Options

#### Disable policy reports

```yaml

policyReports:
  enabled: false

```text

Configure Policy Mode

```yaml
env:
  auditMode: true   # Audit mode (default)
  # auditMode: false  # Enforce mode
```text

Helm Install Example

```bash
helm install ntc nirmata/nirmata-terraform-controller \
  --set policyReports.enabled=false \
  --set env.auditMode=false

Endpoints

Nirmata Terraform Controller exposes the following API endpoints:

Endpoint	Method	Description
`/healthcheck`	GET	Health check endpoint
`/scan`	POST	Direct plan scanning (API Key auth)
`/runtask`	POST	TFC webhook endpoint (HMAC auth)

Verifying the Installation

# Check pods are running
kubectl get pods -n ntc -l app.kubernetes.io/name=nirmata-terraform-controller

# View logs
kubectl logs -f deployment/ntc-nirmata-terraform-controller -n ntc

# Test health endpoint

curl http://<Nirmata Terraform Controller-Endpoint>/healthcheck

Uninstalling

helm uninstall ntc --namespace ntc
kubectl delete namespace ntc

Licensing

The Nirmata Terraform Controller is commercial software available under a paid Nirmata subscription. Use is governed by the Nirmata Terms of Use. See the Licensing page for details.