Cluster Onboarding

Bootstrap a production-ready Kubernetes stack with Dorgu

Prerequisites

Before onboarding a cluster, ensure 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

   Install Dorgu via go install:

   go install github.com/dorgu-ai/dorgu/cmd/dorgu@latest
   

   Verify the installation:

   dorgu version
   
2. Install the Dorgu Operator

   The operator manages ClusterPersona and ApplicationPersona CRDs on your cluster. Install it via Helm:

   helm repo add dorgu https://dorgu-ai.github.io/dorgu-operator
   helm repo update
   helm install dorgu-operator dorgu/dorgu-operator \
     --namespace dorgu-system \
     --create-namespace
   
3. Create a ClusterPersona

   Initialize a ClusterPersona resource that captures your cluster’s operational identity:

   dorgu cluster init --name my-cluster --environment development
   

   This discovers cluster metadata (nodes, Kubernetes version, platform type, installed add-ons) and creates the ClusterPersona CRD.

   Available environments: development, staging, production, sandbox.

4. Run the setup wizard

   Install the blessed stack of production-ready infrastructure components:

   dorgu cluster setup
   

   The setup command reads the ClusterPersona to determine the cluster environment and tailors component configuration accordingly (resource sizing, replica counts, storage classes).

   To preview what will be installed without making changes:

   dorgu cluster setup --dry-run
   
5. Verify the cluster

   Check that all components are healthy:

   dorgu cluster status
   

   This reports node capacity, Kubernetes version, platform type, installed add-ons, namespace summary, and ApplicationPersona count.

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 two CRDs:

applicationpersonas.dorgu.io
clusterpersonas.dorgu.io

Blessed Stack

The dorgu cluster setup command installs a curated set of production-ready components:

The versions below are upstream Helm chart versions for each third-party component — they are not Dorgu release versions.

Component	Chart Version	Description
cert-manager	v1.16.3	Automated TLS certificate management via Let’s Encrypt or internal CAs
ingress-nginx	4.11.3	HTTP/S ingress controller for routing external traffic
CloudNativePG	0.24.0	PostgreSQL operator, required by OpenObserve for metadata storage
OpenObserve	0.60.0	Unified observability platform — logs, metrics, and traces in one tool (15m Helm timeout)
Argo CD	7.8.28	Declarative GitOps continuous delivery engine
External Secrets	0.10.7	Sync secrets from cloud stores (AWS Secrets Manager, Vault, GCP Secret Manager) — optional

Components are installed in dependency order. For example, cert-manager is installed before ingress-nginx (which needs TLS), and CloudNativePG is installed before OpenObserve (which needs PostgreSQL).

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 — If you upgraded the operator, delete and re-apply CRDs: kubectl apply -f https://github.com/dorgu-ai/dorgu-operator/releases/latest/download/crds.yaml

ClusterPersona creation fails with 'resource not found'

The CRDs may not be registered. Install them manually:

kubectl apply -f https://github.com/dorgu-ai/dorgu-operator/releases/latest/download/crds.yaml

Then retry:

dorgu cluster init --name my-cluster --environment development

Helm install times out for a blessed stack component

Some components take longer to become ready. OpenObserve in particular uses an extended 15-minute Helm timeout (vs the default 5 minutes) because it depends on CloudNativePG PostgreSQL pods being fully provisioned first.

Re-run setup with verbose output to see real-time progress:

dorgu cluster setup --verbose

If a specific component fails, check its namespace for pending pods:

kubectl get pods -n cert-manager
kubectl get pods -n ingress-nginx
kubectl get pods -n cnpg-system
kubectl get pods -n openobserve
kubectl get pods -n argocd

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

GitOps Mode

Scaffold an ArgoCD App-of-Apps repository instead of imperative Helm install.

Manifest Generation

Deep dive into how Dorgu analyzes apps and generates manifests.

Cluster Commands

Full reference for dorgu cluster init and dorgu cluster status.

Cluster Setup

All flags and options for dorgu cluster setup.