Quickstart

Install the operator with AI self-healing on and watch it diagnose a real failure in 5 minutes

This guide installs the Dorgu Operator with the self-healing loop and AI planning enabled, then walks a real incident from detection to healed.

Step 1: Install the operator with self-healing on

The self-healing loop is off by default. healthCheck.enabled=true turns it on.

kubectl create namespace dorgu-system

# Optional — enables AI diagnosis and AI-written remediation plans
kubectl create secret generic dorgu-llm -n dorgu-system \
  --from-literal=ANTHROPIC_API_KEY=sk-ant-...

helm install dorgu-operator oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator \
  -n dorgu-system \
  --set healthCheck.enabled=true --set healthCheck.interval=30s \
  --set metricsServer.enabled=true \
  --set llm.provider=claude \
  --set llm.existingSecret=dorgu-llm --set llm.existingSecretKey=ANTHROPIC_API_KEY \
  --set aiRemediation.enabled=true

Omitting --version resolves the newest published chart. To pin an exact chart version, see the installation guide. Drop the llm and aiRemediation flags to run rule-based — detection, diagnosis, and remediation all work without a key.

kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=dorgu-operator \
  -n dorgu-system --timeout=120s

Confirm the loop and the planner started:

kubectl -n dorgu-system logs deploy/dorgu-operator | grep -i "AI \|health check"

Look for AI diagnosis enabled and AI remediation planning enabled. See AI setup if either is missing.

Step 2: Confirm cluster discovery

The operator auto-creates a cluster-scoped ClusterPersona named dorgu-cluster on startup and populates it with nodes, add-ons, capacity, Kubernetes version, and platform type — typically within seconds.

dorgu cluster status
dorgu health

dorgu health should report your nodes Ready, resource saturation, control-plane health, and Active Incidents: 0.

On a managed cluster (EKS, GKE, AKS) the control plane is not visible as pods, so it is reported as Healthy (external/managed). That is expected.

To manage the ClusterPersona yourself via GitOps instead, install with --set operator.autoCreateClusterPersona=false and apply your own.

Step 3: Give the operator something to watch

The operator only acts on applications that have an ApplicationPersona, and it correlates signals to personas by name prefix — so the persona name must match the pod names.

dorgu persona apply ./my-app -n demo

Or apply one directly:

apiVersion: dorgu.io/v1
kind: ApplicationPersona
metadata:
  name: nginx
  namespace: demo
spec:
  name: nginx
  type: web
  tier: standard
  resources:
    requests:
      cpu: 50m
      memory: 64Mi
    limits:
      cpu: 500m
      memory: 128Mi
  scaling:
    minReplicas: 1
    maxReplicas: 5
  health:
    livenessPath: /
    readinessPath: /
    port: 80
  policies:
    security:
      runAsNonRoot: true

Always declare resources.limits. Without a current limit the remediation proposer has no baseline to compute a bounded change from, and skips the persona with persona has no resource limits configured.

dorgu persona status nginx -n demo

The operator validates the running Deployment against the persona and reports issues in .status.validation.issues — missing resource requests, an unenforced runAsNonRoot, a missing liveness probe. The phase reflects the overall state (Active, Degraded, or Failed), and it re-validates every 60 seconds or immediately when the Deployment changes. See validation.

Step 4: Break something and watch the loop

The fastest way to see self-healing work is a deliberate OOM. The CLI quickstart has a ready-to-apply manifest: a container that allocates ~90 MB against a 64Mi limit, plus a matching persona.

Once it is crash-looping, one detection cycle later:

dorgu incidents list -n demo                       # OOMKilled + CrashLoopBackOff
dorgu incidents describe <incident-name> -n demo    # root cause, confidence, provider
dorgu remediation list -n demo                      # one proposal, PLAN: ai-anthropic
dorgu remediation diff <remediation-name> -n demo   # the ordered plan, with diffs

Step 5: Approve, and watch it heal

dorgu remediation approve <remediation-name> -n demo

The operator patches the ApplicationPersona spec — the app’s desired state — and moves the remediation to Applying. The CLI then patches the Deployment with your credentials so the pod actually recovers.

kubectl -n demo get pods

The remediation stays in Applying / Verifying for the verification window — 10 minutes by default — before it reports Completed. At the end of that window the operator re-runs detection and rolls the change back automatically if health regressed. Your pod is healthy well before then.

The operator never creates or modifies Deployments, Services, or any other workload resource. It updates Persona, Incident, and Remediation CRDs and recommends; applying workload changes stays with the CLI, ArgoCD, Flux, or kubectl.

Next steps

Self-healing in depth

Signals, guardrails, verification, and troubleshooting

AI setup

Key handling, verification, and turning AI off

Validation details

What the operator validates and how severity works

Configuration

Flags for webhooks, ArgoCD, Prometheus, and WebSocket