Cluster Onboarding

Install Dorgu onto a cluster and bring the apps already running under its watch

Onboarding a cluster is two installs and one import. Dorgu does not install or manage anything else on your cluster: ingress, TLS, observability and GitOps stay with the tools you already use.

​

Prerequisites

Before onboarding a cluster, make sure you have:

• A running Kubernetes cluster (local or cloud)
• kubectl installed and configured to reach the cluster
• helm v3 installed

​

Environment Options

Choose a cluster environment based on your use case:

Option	Best For	Command
Kind	Quick local testing	kind create cluster --name dorgu-dev
vCluster	Isolated testing on an existing cluster	vcluster create dorgu-dev -n dorgu-vcluster && vcluster connect dorgu-dev
Cloud	Full integration testing	Point kubectl at your EKS, GKE, or AKS cluster

vCluster avoids TLS certificate issues that are common with Kind behind corporate proxies. It creates a lightweight virtual cluster inside your existing cluster, giving you full isolation without provisioning new infrastructure.

​

Onboarding Steps

1. Install the CLI

   Binary (no Go)

   # Set OS to linux or darwin, ARCH to amd64 or arm64
   OS=linux ARCH=amd64
   curl -fLO "https://github.com/dorgu-ai/dorgu/releases/latest/download/dorgu_${OS}_${ARCH}.tar.gz"
   tar -xzf "dorgu_${OS}_${ARCH}.tar.gz" dorgu
   sudo mv dorgu /usr/local/bin/
   

   Verify the installation:

   dorgu version
   

   See installation for pinned versions, checksums, and Windows.

2. Install the Dorgu Operator

   The chart is published to an OCI registry, so there is no Helm repo to add:

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

   Failure detection is on out of the box. See the installation guide for version pinning and how to turn detection off.

   The operator creates a ClusterPersona named dorgu-cluster on startup and fills it with what it discovers: nodes, capacity, Kubernetes version, platform, and add-ons. There is nothing to create by hand.

3. See what Dorgu cannot watch yet

   dorgu health
   

   Dorgu only watches workloads that have an ApplicationPersona. The Unmonitored section names every Deployment without one and prints the import command for its namespace.

4. Import personas for the apps already running

   dorgu persona import -n apps --all > personas.yaml   # read them first
   dorgu persona import -n apps --all --apply           # then create them
   

   Read the warnings on stderr before you apply, particularly any about inferred resource limits. See dorgu persona import for what is inferred and why.

5. Verify

   dorgu persona list -n apps
   dorgu cluster status
   

   Phase Active means each persona resolved to its Deployment. cluster status reports node capacity, Kubernetes version, platform type, installed add-ons, namespace summary, and ApplicationPersona count.

The brownfield quickstart continues from here: it breaks one of the imported apps and walks the loop through diagnosis, review, and heal, including what happens when Helm or ArgoCD owns the workload.

​

Verify Operator Installation

Confirm that the operator pods are running and CRDs are registered:

# Check operator pods
kubectl get pods -n dorgu-system

# Verify CRDs are registered
kubectl get crds | grep dorgu.io

You should see all five CRDs:

applicationpersonas.dorgu.io
clusterpersonas.dorgu.io
dorguevents.dorgu.io
incidentmemories.dorgu.io
remediationactions.dorgu.io

Fewer than five means an incomplete install. See Verify installation.

​

Troubleshooting

Operator pods are in CrashLoopBackOff

Check the operator logs for errors:

kubectl logs -n dorgu-system -l app.kubernetes.io/name=dorgu-operator --tail=50

Common causes:

• Insufficient RBAC: The operator service account needs cluster-wide permissions to watch CRDs. Re-run the Helm install to ensure RBAC resources are created.
• CRD version mismatch: Helm only installs the CRDs on first install, never on upgrade. After upgrading the operator, re-apply them from the chart (see below).

dorgu persona import or cluster status reports 'resource not found'

The CRDs may not be registered. They ship inside the Helm chart, so pull the chart and apply them manually:

helm pull oci://ghcr.io/dorgu-ai/dorgu-operator-charts/dorgu-operator --untar
kubectl apply -f dorgu-operator/crds/

Then retry the command.

Kind cluster TLS or networking issues

Kind clusters run inside Docker and may have networking limitations, especially behind corporate proxies. Consider using vCluster instead:

vcluster create dorgu-dev -n dorgu-vcluster
vcluster connect dorgu-dev

If you need to stick with Kind, ensure your Docker daemon has access to the internet and that no proxy settings interfere with Helm chart downloads.

dorgu cluster status shows no add-ons detected

The operator discovers add-ons by scanning namespaces for known deployments. If you installed components before the operator, restart the operator to trigger a re-scan:

kubectl rollout restart deployment -n dorgu-system dorgu-operator

Wait a few seconds and re-check:

dorgu cluster status

​

Next Steps

Brownfield quickstart

Break an imported app and heal it, end to end.

Working with personas

What a persona holds and how the operator uses it.

Cluster commands

Full reference for dorgu cluster status.

Ownership model

Which workloads Dorgu patches, and which it only advises on.