Documentation menu

Connect a Cluster

Deploy the DataAgent agent with Helm in under 5 minutes.

1. Get your install command

In the dashboard, go to Clusters → Connect Cluster. The flow shows an install command pre-filled with your auth token, cluster name, chart version, and image pull password. The auth token is unique to your organisation and valid for 60 minutes.

Copying the command from the dashboard is the most reliable path. The command below is for reference.

2. Install the Helm chart

helm upgrade --install dataagent oci://ghcr.io/data-agent-co/dataagent-chart \
  --version <version> \
  --namespace dataagent \
  --create-namespace \
  --set config.authToken=<your-token> \
  --set config.clusterName=<your-cluster-name> \
  --set imageCredentials.password=<pull-password> \
  --wait --timeout 10m

Replace:

  • <version> — the chart version shown in the dashboard
  • <your-token> — the auth token from the dashboard
  • <your-cluster-name> — a human-readable name shown in the dashboard (e.g. prod-eu-west-1)
  • <pull-password> — the image pull password from the dashboard. It pulls the agent images from ghcr.io and fetches the agent’s CA certificate. You do not need to create a GitHub token

The dashboard’s command does not include --wait --timeout 10m; we recommend adding it. Helm then waits until every pod is ready, so a failed install shows up as an error here instead of later. The first install pulls several images and can take a few minutes.

The bundled monitoring pods pull public images from quay.io, registry.k8s.io, and docker.io. On a cluster with restricted egress, check Prerequisites → Network first — otherwise the agent pod starts but the monitoring pods stay in ImagePullBackOff, and --wait fails after 10 minutes.

3. Verify the agent is running

kubectl get pods -n dataagent

Expected output (pod name suffixes will differ):

NAME                                               READY   STATUS    RESTARTS   AGE
dataagent-7d9f8b6c4-xk2p9                          5/5     Running   0          2m
dataagent-kube-state-metrics-6b7c9d8f5-q2wzl       1/1     Running   0          2m
dataagent-prometheus-node-exporter-7xk9p           1/1     Running   0          2m
dataagent-prometheus-server-5c8d7f6b9-m4ntr        2/2     Running   0          2m

The agent pod runs 5 containers, and all 5 should be Running:

  • orchestrator — connects to DataAgent and forwards findings
  • topology-analyzer — maps your cluster’s resources and runs K8sGPT analysis every 30 seconds
  • metrics-collector — collects pod, node, and workload metrics
  • watcher — watches Kubernetes Warning events and ConfigMap changes
  • log-watcher — scans pod logs for known error patterns

The chart also installs 3 monitoring pods: prometheus-server, kube-state-metrics, and node-exporter (one node-exporter pod per node). To skip them, see the Helm chart reference.

4. Confirm connection in the dashboard

Go to Clusters. Your cluster should appear with a green Connected status within 60 seconds.

If the cluster does not appear after 2 minutes, check Agent not connecting.

Upgrading

helm upgrade dataagent oci://ghcr.io/data-agent-co/dataagent-chart \
  --namespace dataagent \
  --reset-then-reuse-values

Customising the installation

See the Helm chart reference for all available values.

Cookie Settings