Getting Started

Install the Remediator Agent and run your first policy violation remediation.

Prerequisites

Required Components

Kubernetes cluster running Kubernetes 1.20+
Helm 3.x installed and configured
kubectl configured to access your cluster
Kyverno installed and running with policy reports enabled
ArgoCD (optional) — required for Hub Mode multi-cluster setups

Required Credentials

Nirmata Control Hub Service Account Token — create a Service Account in Nirmata Control Hub and copy its secret

Create a Service Account

Log in to Nirmata Control Hub
Navigate to Identity & Access from the left sidebar
Go to Service Accounts and create a new one
Copy the generated secret — you’ll use it in the next step

Installation

1. Create Namespace and Secrets

kubectl create namespace nirmata

kubectl create secret generic nirmata-service-account-token \
  --from-literal=service-account-token=YOUR_NCH_SERVICE_ACCOUNT_TOKEN \
  --namespace nirmata

2. Add the Helm Repository

helm repo add nirmata https://nirmata.github.io/kyverno-charts
helm repo update nirmata

3. Install the Agent

helm install nirmata-agent nirmata/nirmata-agent --devel \
  --namespace nirmata \
  --create-namespace
```json




Note

    The chart uses serviceAccountToken authentication by default and expects the nirmata-service-account-token secret created above. To use API token authentication instead, set:
--set nirmata.auth="apiToken" \
--set nirmata.apiTokenSecret="nirmata-api-token"
```json
### 4. Verify the Installation
```bash
# Check pods are running
kubectl get pods -n nirmata -l app.kubernetes.io/name=nirmata-agent
# Check custom resource definitions were installed
kubectl get llmconfigs,toolconfigs,remediators -n nirmata
# Tail the agent logs
kubectl logs -n nirmata -l app.kubernetes.io/name=nirmata-agent --tail=50
```yaml
---
## Quick Configuration
The agent requires three custom resources before it will start remediating. See [Configuration](../configuration/) for full details and all available options.
### 1. ToolConfig (Git credentials)
**GitHub Personal Access Token:**
```bash
kubectl create secret generic github-pat-token \
 --from-literal=token=GITHUB_PAT_TOKEN \
 --namespace nirmata
kubectl apply -f - <<EOF
apiVersion: serviceagents.nirmata.io/v1alpha1
kind: ToolConfig
metadata:
name: toolconfig-sample
namespace: nirmata
spec:
type: github
credentials:
method: pat
pat:
tokenSecretRef:
name: github-pat-token
namespace: nirmata
key: token
defaults:
git:
pullRequests:
branchPrefix: "remediation-"
titleTemplate: "[Auto-Remediation] Fix policy violations: "
commitMessageTemplate: "Auto-fix: Remediate policy violations: "
customLabels:
- "auto-remediation"
systemLabels:
- "clusterName"
- "namespace"
EOF

Prefer using the Nirmata GitHub App over a personal access token — it avoids managing secrets manually and provides automatic token rotation.

2. LLMConfig (AI provider)

The Helm chart creates a default LLMConfig using Nirmata AI automatically. If you need to create it manually:

kubectl apply -f - <<EOF
apiVersion: serviceagents.nirmata.io/v1alpha1
kind: LLMConfig
metadata:
  name: nirmata-agent-llm
  namespace: nirmata
spec:
  type: nirmataAI
  nirmataAI:
    model: ""
EOF

3. Remediator

Local Mode (scans the cluster where the agent is installed):

# Create a ConfigMap mapping Git repos to namespaces
kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: repo-namespace-mapping
  namespace: nirmata
data:
  mapping: |
    [
      {
        "repo": "https://github.com/your-org/your-repo",
        "branch": "main",
        "path": "k8s/",
        "targetNamespace": "default"
      }
    ]
EOF

# Create the Remediator
kubectl apply -f - <<EOF
apiVersion: serviceagents.nirmata.io/v1alpha1
kind: Remediator
metadata:
  name: remediator-local
  namespace: nirmata
spec:
  environment:
    type: localCluster
  target:
    localCluster:
      repoNamespaceMappingRef:
        name: repo-namespace-mapping
        namespace: nirmata
        key: mapping
  remediation:
    triggers:
      - schedule:
          crontab: "0 */6 * * *"
    llmConfigRef:
      name: nirmata-agent-llm
      namespace: nirmata
    gitCredentials:
      name: toolconfig-sample
      namespace: nirmata
    eventPolling:
      enabled: true
      intervalMinutes: 5
    actions:
      - type: CreatePR
        toolRef:
          name: toolconfig-sample
          namespace: nirmata
EOF
```yaml

---

## Uninstalling

```bash
helm uninstall nirmata-agent -n nirmata

Secrets you created manually are not removed — clean those up separately if needed.