Installation

Install the Dorgu Operator via Helm, kustomize, or source build

Prerequisites

• Kubernetes cluster 1.24+
• kubectl configured for your cluster
• Helm 3.x (for Helm installation)
• Chart 0.11.1 or newer on arm64 nodes, including AWS Graviton and Apple Silicon kind or k3d clusters. Every image up to and including 0.11.0 was amd64-only. See Versions.

Helm (recommended)

Install the operator from the OCI registry:

helm install dorgu-operator oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator \
  --namespace dorgu-system \
  --create-namespace

That is the canonical install command, and it is the same one used in the CLI quickstart, the operator quickstart, and AI setup.

Failure detection is on out of the box as of chart 0.8.0. The health-check reconciler runs every 60 seconds, opens IncidentMemory records, and proposes RemediationAction fixes for what it finds. Nothing is ever applied without your approval.

Earlier charts defaulted healthCheck.enabled to false, which meant following this page produced an operator that detected nothing. If you are reading an older copy of these instructions, that is the difference.

AI

The AI planner is off by default, and for now that is also the recommendation. aiRemediation.enabled defaults to false, llm.provider defaults to empty, and the install commands in these docs leave both alone. A default install spends nothing on inference and sends nothing out of your cluster.

Rules always run. Detection, rule-based diagnosis, and rule-based remediation are local, free, deterministic, and are the floor the whole product stands on. They are what the clean-room runs have actually healed with.

The AI planner is an addition on top of that floor, and across three consecutive clean-room evaluations, meaning a stranger installing from these published docs and nothing else, it has been the weaker path: it invented specifics in the first, wrote a worse plan than the rules in the second, and in the third produced nine remediations of which none could change a workload. Operator v0.11.0 is the release that fixed that last one, and it is too recent to have an evaluation behind it yet.

This is not a retreat from AI. It is where the two halves have earned their place: deterministic detection and remediation, with AI for explanation. The setting that says exactly that is a provider with no planner, which gives you AI root-cause prose while the numbers that reach your cluster stay the rule engine’s:

--set llm.provider=claude --set llm.existingSecret=dorgu-llm    # AI explains
# aiRemediation.enabled stays false                              # rules decide

AI setup has the full walkthrough for both, and what each one costs you.

Versions

Current versions: CLI v0.14.1 with operator v0.13.1 (Helm chart 0.13.1; the chart version, the chart appVersion, and the operator version are always the same number). Newest of each is always the right answer, and this note is the only place in these docs that states which that is.

CLI v0.13.0 removed the manifest generation and cluster setup commands (generate, init, config, persona generate|apply, cluster setup|info|init, platform serve, watch, sync), so if you relied on one, read the CLI migration guide before upgrading.

On arm64 nodes, 0.11.1 is a floor and not a preference. Every operator image published before it, up to and including 0.11.0, was pushed as a single-platform amd64 manifest rather than a manifest list. That covers AWS Graviton nodegroups and any kind or k3d cluster on an Apple Silicon Mac. On containerd there is no manifest list to select from, so the pull succeeds and the container dies immediately with exec /manager: exec format error and exit code 255. The pod reads CrashLoopBackOff, not ImagePullBackOff. 0.11.1 is that image and nothing else: no API, CRD, controller, or chart-template change, which is why everything below still names v0.11.0 as the release each behaviour landed in.

CLI v0.14.0 and operator v0.13.0 are a pair, and the order you upgrade them in matters. v0.13.0 adds the approval-time re-check and the apply ticket. A CLI older than v0.14.0 does not read tickets, so it patches the Deployment from the plan with none of those checks, and the operator cannot stop it. Upgrade the CLI first, then the operator. Steps, breaking changes and new settings are in the upgrade guide.

CLI v0.14.1 and operator v0.13.1 are the patch release of that pair. They change no CRD, no RBAC and no flag or Helm value, and they are meant to move together: upgrade the CLI first, as before. dorgu report counts a refusal that has since cleared only with CLI v0.14.1 against operator v0.13.1. With an older half it reads the live ProposalRefused condition as it always did, and a refusal that cleared before the report ran is not counted. See the changelog.

Before that pair, every field either side had added was optional and additive, so a half that did not know about a field simply saw it absent and nothing had to move in lockstep. The ticket is the exception.

These mismatches change behaviour. Two are unsafe, the first and the last, and in both it is the old CLI that is the risk, not the old operator:

Mismatch	What happens
CLI older than v0.14.0 against operator v0.13.0 or newer	Upgrade the CLI. An older CLI reads spec.steps[] and patches the Deployment without a ticket, so the approval-time re-check, the ticket checks and the ownership re-detection do not apply to that patch. The operator cannot prevent it.
CLI v0.14.0 against operator older than v0.13.0	Safe but limited. approve records the decision, waits up to 30 seconds, finds no ticket, patches nothing and says why. An older operator still patches the ApplicationPersona when it sees the approval, so the persona changes while the workload does not, and the two disagree until you upgrade the operator or revert the persona by hand. Use approve --no-heal only if you will apply the change yourself.
CLI v0.9.0 or older against operator v0.9.0 or newer	Upgrade the CLI. An older CLI never reads spec.workloadRef, so approve will patch a Deployment that Helm, ArgoCD, or Flux owns and break the owner’s next apply. The operator supplies the ownership facts; declining the patch is the CLI’s job. This is the one combination that silently does the thing the guard exists to prevent.
CLI v0.10.0 or newer against operator v0.8.1 or older	Conservative rather than dangerous. The operator writes no workloadRef, an absent record is treated as owned, and every remediation carrying a workload change is declined with exit 4. dorgu remediation approve <name> -n <ns> --no-heal records the decision until the operator is upgraded.
CLI v0.12.0 or newer against operator v0.10.0 or older	No guardrail verdicts. They are read from the optional spec.steps[].safety field that operator v0.11.0 adds. The field is absent, remediation list grows no GUARDRAIL column, and every command prints what it printed before.

One operator upgrade is worth doing on its own merits, with no CLI implication at all: with aiRemediation.enabled=true, operator v0.11.0 is the release that made AI-planned remediations appliable. On v0.10.0 and older, a plan that diagnosed a resource change could be persisted with nothing to apply. See AI setup.

Operator v0.12.0 is worth upgrading to on its own as well: it protects the namespace Dorgu is installed in from remediation, and it makes healthCheck.enabled=false mean no incidents and no proposals. It also removed the validating webhook, so an upgrade that still sets webhook.enabled=true fails until you drop the value. See Helm values.

Operator v0.13.0 is the release that makes an approval safe to give on a cluster you care about: the gate runs again at approval on the live cluster, and what is applied is a short-lived ticket. It also adds probe and restart detection and a complete set of metrics. It needs the CRDs applied and a v0.14.0 CLI. See How Dorgu decides.

Operator v0.12.1 is the one to install if you turn on AI: it keeps incidents in protected namespaces, including the namespace Dorgu runs in, out of every model call. On v0.12.0 the diagnosis call still sent them. No values, flags or RBAC change.

Both mismatch directions in full, with the ownership reasoning behind them: version coupling. Newest published releases: CLI and operator.

Read the ownership model before you upgrade a cluster that runs Helm or ArgoCD-managed apps. Persona writes are unaffected by any of it.

Turn detection off

To run the operator for validation and cluster discovery only:

helm install dorgu-operator oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator \
  --namespace dorgu-system \
  --create-namespace \
  --set healthCheck.enabled=false

From chart 0.12.0, off means off: the operator records each persona’s health and never opens an incident or proposes a fix. On chart 0.11.x and older, an older code path still opened OOMKilled incidents and wrote RemediationAction proposals with detection off, so upgrade if you depend on this.

Pin a chart version

The command above resolves the newest published chart. To pin an exact version for reproducibility, add --version:

helm install dorgu-operator oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator \
  --namespace dorgu-system \
  --create-namespace \
  --version 0.13.1

The chart version and the operator version are the same number, so --version 0.13.1 installs operator v0.13.1. If the literal above has fallen behind, Versions is the statement to trust on this page, and operator releases is the statement to trust over both.

Verify what you install (build provenance)

Releases from v0.13.1 carry a build provenance attestation for the operator image, the chart archive and the chart as it sits in the registry, signed by the release workflow of dorgu-ai/dorgu-operator. Check them with the GitHub CLI before you install. A passing check says the artifact was built by that workflow from a tagged commit, and the output names the commit.

VERSION=0.13.1

# The image: the manifest list the tag points at
gh attestation verify oci://ghcr.io/dorgu-ai/dorgu-operator:${VERSION} --owner dorgu-ai

# The chart archive from the GitHub release
gh release download v${VERSION} --repo dorgu-ai/dorgu-operator --pattern 'dorgu-operator-*.tgz'
gh attestation verify dorgu-operator-${VERSION}.tgz --owner dorgu-ai

Also check the chart in the registry, which is what helm install oci://... pulls:

VERSION=0.13.1
gh attestation verify oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator:${VERSION} --owner dorgu-ai

Releases before v0.13.1 have no attestation: gh attestation verify answers 404 for them.

Install with a values file

To customize the installation, create a values.yaml file:

argocd:
  enabled: true

prometheus:
  enabled: true
  url: "http://prometheus-server.monitoring:9090"

safety:
  excludedNamespaces:
    - payments

Then install with your values:

helm install dorgu-operator oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator \
  --namespace dorgu-system \
  --create-namespace \
  -f values.yaml

See the Helm values reference for all available options.

Kustomize

Install CRDs and deploy the operator using kustomize:

# Clone the repository
git clone https://github.com/dorgu-ai/dorgu-operator.git
cd dorgu-operator

# Install CRDs
make install

# Deploy the operator
make deploy IMG=ghcr.io/dorgu-ai/dorgu-operator:0.13.1

To reverse it:

make undeploy    # removes the operator Deployment and its RBAC
make uninstall   # removes the five CRDs, and with them every Dorgu record

make uninstall deletes the CRDs, so it deletes every ApplicationPersona, IncidentMemory, RemediationAction and DorguEvent in the cluster along with them. Read Uninstall before you run it, particularly the part about your API key, which neither command touches.

Build from source

git clone https://github.com/dorgu-ai/dorgu-operator.git
cd dorgu-operator

# Build the binary
make build

# Run locally against your current kubeconfig
./bin/manager \
  --metrics-bind-address :8080 \
  --metrics-secure=false \
  --health-probe-bind-address :8081

Running locally connects to whatever cluster your kubeconfig points to. Make sure you are targeting the correct cluster before starting the operator.

Running the manager directly does not read the chart’s values, but from v0.12.0 its own defaults match the chart’s: --enable-health-check defaults to true in the binary as well. On older binaries it defaulted to false, so pass --enable-health-check there to get the detection loop a Helm install gives you. The binary reads its own namespace from POD_NAMESPACE, then from the mounted service account. Outside a pod neither exists, so set POD_NAMESPACE yourself if you want the deny-list to protect the namespace you installed into.

Build and push Docker image

make docker-build IMG=your-registry/dorgu-operator:latest
make docker-push IMG=your-registry/dorgu-operator:latest

Multi-platform builds (arm64, amd64) are supported:

make docker-buildx IMG=your-registry/dorgu-operator:latest PLATFORMS=linux/arm64,linux/amd64

Verify installation

The chart prints a post-install summary that reports whether detection is on, whether AI is on, and what to run next. Re-read it at any time with helm get notes dorgu-operator -n dorgu-system.

Check that the operator is running:

kubectl get pods -n dorgu-system

Expected output:

NAME                              READY   STATUS    RESTARTS   AGE
dorgu-operator-6d4b5c7f9-x2k4p   1/1     Running   0          30s

Verify all five CRDs are installed:

kubectl get crd | grep dorgu.io

Expected output:

applicationpersonas.dorgu.io   2026-08-16T00:00:00Z
clusterpersonas.dorgu.io       2026-08-16T00:00:00Z
dorguevents.dorgu.io           2026-08-16T00:00:00Z
incidentmemories.dorgu.io      2026-08-16T00:00:00Z
remediationactions.dorgu.io    2026-08-16T00:00:00Z

CRD	Scope	What it holds
applicationpersonas.dorgu.io	Namespaced	The operational identity of one app: resources, scaling, health, security, ownership
clusterpersonas.dorgu.io	Cluster	The cluster’s identity and the self-healing policy. Singleton, auto-created as dorgu-cluster
incidentmemories.dorgu.io	Namespaced	A detected incident with its root-cause diagnosis, confidence, and outcome
remediationactions.dorgu.io	Namespaced	A proposed fix as an ordered plan, with its approval state and rollback snapshot
dorguevents.dorgu.io	Namespaced	Classified and correlated Kubernetes events from the event pipeline

Fewer than five means an incomplete install. Detection cannot record anything without incidentmemories and cannot propose anything without remediationactions. Installing from a clone of an old chart was the usual cause; the published OCI chart has always carried all five. See Self-healing.

Confirm detection actually started:

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

Look for Phase 2a/2b health check and remediation enabled with the interval. If it is absent, detection is off.

Uninstall

Start with your Anthropic API key. helm uninstall does not remove it.

The AI setup walkthrough has you create the key as a Secret out of band, with kubectl create secret, precisely so it never passes through Helm values. The consequence is that Helm never owned it and never deletes it, so an operator you removed an hour ago leaves your key sitting in the cluster:

kubectl delete secret dorgu-llm -n dorgu-system

Run that first, before anything else on this page, and rotate the key at Anthropic if the cluster was shared or is one you no longer control. The only case where Helm does clean it up is llm.createSecret=true with llm.apiKey set, which the docs recommend against for exactly the reasons in AI setup.

1. Remove the release

helm uninstall dorgu-operator -n dorgu-system

That removes everything Helm actually owns: the operator Deployment, the ServiceAccount, the dorgu-operator-manager ClusterRole and ClusterRoleBinding, and the metrics Service. The operator stops within seconds and nothing further is detected, diagnosed, or proposed.

2. Know what is still there

Quite a lot, and none of it announces itself:

What survives	Why
All five CRDs	They are installed from the chart’s crds/ directory, and Helm never deletes those, by design. It is the standard behaviour and it is not a chart bug.
Every Dorgu record in the cluster, in every namespace	ApplicationPersona, ClusterPersona, IncidentMemory, RemediationAction and DorguEvent objects are ordinary namespaced resources. Deleting the release does not delete them, and with the operator gone the retention cleaner is gone too, so DorguEvent records that used to expire after 24 hours are now permanent.
The dorgu-system namespace	--create-namespace creates it but does not add it to the release, so helm uninstall leaves it.
A Secret you created yourself	Covered above, and it is the one that matters.

The volume is larger than it sounds. A clean-room evaluation, meaning a stranger installing from these published docs and nothing else, measured 176 custom resources across 12 namespaces, kube-system included, on a five-application test cluster after a single hour:

applicationpersona   10      incidentmemory    17      dorguevent   135
clusterpersona        1      remediationaction 13

DorguEvent records reach kube-system because they are written into the namespace of the object they describe, and Dorgu watches the whole cluster. That is worth knowing before you install, not after.

That run was on operator v0.12.x. From v0.13.0 the event pipeline is off by default, so no DorguEvent records are written unless you turn it on with eventPipeline.enabled=true, and the dorguevent count above is zero on a fresh install. The incidentmemory and remediationaction records remain.

3. Keep the history, if you want it

The incident and remediation records are the only account of what Dorgu saw. Step 4 destroys them, so export first if that matters:

kubectl get incidentmemories,remediationactions,applicationpersonas \
  --all-namespaces -o yaml > dorgu-history.yaml

4. Delete the CRDs

This is the step that completes the teardown. Deleting a CRD garbage-collects every custom resource of that kind, in every namespace, so five commands’ worth of cleanup is one command and no label selector is needed:

kubectl delete crd \
  applicationpersonas.dorgu.io \
  clusterpersonas.dorgu.io \
  dorguevents.dorgu.io \
  incidentmemories.dorgu.io \
  remediationactions.dorgu.io

Irreversible, and wider than the namespace you installed into. This removes Dorgu’s records from the entire cluster, including any you wrote by hand and any under GitOps. Re-installing the chart brings the CRDs back empty.

5. Delete the namespace

Only if Dorgu was the only thing in it:

kubectl delete namespace dorgu-system

This also removes the API key Secret, but do not rely on it for that. Someone who runs the obvious helm uninstall and stops there keeps the key, which is why it leads this section.

6. Verify

kubectl get crd | grep dorgu.io                 # no output
kubectl get ns dorgu-system                     # NotFound
kubectl get secret -A | grep dorgu              # no output
kubectl get clusterrole | grep dorgu            # no output

Four empty results mean Dorgu is gone. Anything printed is a leftover, and the section above says which step removes it.

Removing the operator but keeping the record

A common middle case: you are done evaluating, but the incident history is worth keeping, or the personas are under GitOps and you intend to reinstall. Run step 1 only, and stop:

helm uninstall dorgu-operator -n dorgu-system

The CRDs and every record stay, nothing reconciles them, and a later helm install picks the same objects straight back up. The two things to be deliberate about are that DorguEvent records will not be pruned while no operator is running, and that the API key Secret is still there. If you only want the records gone and the CRDs kept, delete the records directly instead of the CRDs:

kubectl delete applicationpersonas,incidentmemories,remediationactions,dorguevents \
  --all --all-namespaces
kubectl delete clusterpersonas --all

ClusterPersona is cluster-scoped, which is why it is a separate command.

Next steps

Quickstart

Apply your first persona and see the operator in action

Already have apps running?

Import personas from your live Deployments

Turn on AI

BYO Anthropic key for AI diagnosis and ordered plans

Security and permissions

The operator’s full ClusterRole and the verbs it does not have

Configuration

Customize flags and Helm values

Uninstall

Complete teardown, starting with your API key