Installing the Agent on Amazon EKS

How to install the DataAgent agent on your Amazon EKS cluster — requirements, pre-install validation, the install command, and post-install verification. The agent runs on any conformant Kubernetes (v1.24+); EKS is the worked example.

Just getting started? The Quickstart is the fastest path to a connected cluster. This guide is the production-grade install reference — full requirements, network, security, and customisation.

TL;DR

• Generate a registration token in the dashboard (Clusters → Connect), then run the helm upgrade --install command it gives you.
• The agent needs outbound 443 only to the hub — no inbound ports from outside the cluster.
• The chart installs its own Prometheus, kube-state-metrics, and node-exporter, and the agent uses only that bundled Prometheus. A monitoring stack of your own is optional — keep it for your application metrics; the agent does not integrate with it.

Requirements

Cluster prerequisites

In-cluster observability

The chart installs its own Prometheus, kube-state-metrics, and node-exporter (da-monitoring.enabled=true, the default). The agent reads metrics and firing alerts from that bundled Prometheus, and it is the only Prometheus integration the agent supports — connecting the agent to a Prometheus you already run is not supported.

Your own monitoring stack is optional. If you run one for your application metrics, keep it: the bundled stack scrapes infrastructure metrics only and does not interfere with it. Nothing needs to be installed before the agent.

Prometheus-based detection requires the bundled stack, so leave da-monitoring.enabled at true unless you are prepared to go without it.

Network requirements

The agent makes outbound-only connections on port 443 to destinations outside the cluster. No inbound ports from outside the cluster need to be opened.

Outbound from the cluster

The last three are needed only for the bundled monitoring pods, which pull public images and do not use the image pull password. With --set da-monitoring.enabled=false, only the first two are needed.

In-cluster only

• Private clusters — if your cluster has no direct internet egress, configure a NAT Gateway or HTTP proxy for the outbound destinations above.
• VPC security groups — the node group security group must allow outbound TCP 443. Most default EKS configurations already permit this.

Security

The agent operates read-only on your workloads — it observes your Deployments, Pods, Services, and configurations but cannot modify any of them. With the default analyzers enabled it also has cluster-wide read on Secrets and ConfigMaps for diagnosis. The agent does not write to Secrets or ConfigMaps in your workload namespaces — the only Secret it creates is its own mTLS credentials Secret in the dataagent namespace at first install.

For the full per-rule breakdown — every Role and ClusterRole the chart creates, what each rule does, and why — see Agent Permissions Reference.

AWS IAM — the agent requires no AWS IAM roles or policies. No IRSA or EKS Pod Identity configuration is needed.

Pod security — the agent runs as a non-root user (UID 1000) with a read-only root filesystem, all Linux capabilities dropped, and the RuntimeDefault seccomp profile.

Resource footprint

The agent runs as a single pod with one replica and five containers (orchestrator, topology analyzer, metrics collector, watcher, log watcher). K8sGPT analysis runs inside the topology analyzer — there is no separate K8sGPT container. The chart also installs three monitoring pods (prometheus-server, kube-state-metrics, node-exporter). Together they request about 910m CPU and 3.2Gi memory. See Agent Resource Requirements for the per-container breakdown and how to tune it for large clusters.

Pre-install validation

Confirm your environment before running the install.

1. Verify kubectl context

You’re about to install the agent in whatever cluster kubectl currently points at. Confirm it’s the right one:

kubectl config current-context

If you need to switch (EKS example):

aws eks update-kubeconfig --name <your-cluster> --region <your-region>

2. Verify Kubernetes version

kubectl version

The server version must be v1.24 or newer.

3. Verify Helm version

helm version --short

Must be v3.14 or newer.

4. Verify outbound connectivity from a node

The agent needs outbound access to tunnel.data-agent.co:443 and ghcr.io:443 from cluster nodes, and the bundled monitoring needs quay.io, registry.k8s.io, and docker.io (see Network requirements above):

kubectl run -n default --rm -i --restart=Never net-check --image=busybox:1.37 -- \
  sh -c "for h in tunnel.data-agent.co ghcr.io quay.io registry.k8s.io registry-1.docker.io; do nc -zv -w5 \$h 443; done"

The check pod’s own busybox image comes from Docker Hub, so if the pod cannot start at all, docker.io is blocked.

If your cluster enforces restricted PodSecurity admission on the default namespace, this pod will be rejected. Run it in a namespace that allows the baseline profile (or temporarily use kubectl run -n kube-system …), then proceed.

Each host should report open. Connection refused or timeout means the cluster needs a NAT Gateway, HTTP proxy, or relaxed security-group rules — see Network requirements above.

Installation

Step 1 — Generate a registration token

If you haven’t already, log in at app.data-agent.co. Then open Clusters → Connect. The flow generates a registration token and shows the exact install command pre-filled with your token, cluster name, and chart version — copying it from there is the most reliable path. The command below is for reference.

Step 2 — Install via Helm

helm upgrade --install dataagent \
  oci://ghcr.io/data-agent-co/dataagent-chart \
  --version <CHART_VERSION> \
  --namespace dataagent --create-namespace \
  --set 'imageCredentials.password=<PULL_PASSWORD>' \
  --set 'config.authToken=<TOKEN_FROM_DASHBOARD>' \
  --set 'config.clusterName=<YOUR_CLUSTER_NAME>' \
  --wait --timeout 10m

Replace <CHART_VERSION>, <PULL_PASSWORD>, <TOKEN_FROM_DASHBOARD>, and <YOUR_CLUSTER_NAME> with the values provided during the Connect flow. The image pull password comes from the dashboard — you do not create a GitHub token. Always set config.clusterName, so the cluster has a readable name in the dashboard. The hub endpoint defaults to the production tunnel, so no config.hubUrl override is needed.

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 from helm instead of later.

Production hardening. Values passed via --set land in your shell history and are visible to other users on the machine via ps for the duration of the helm run. For production rollouts, prefer a gitignored values.yaml (or --set-file for the auth token), and a pre-created image-pull Secret instead of the inline imageCredentials.password. Reading the pull password into a shell variable (not into argv) and piping the Secret manifest through stdin keeps it off the command line:

kubectl create namespace dataagent
read -srp 'Pull password: ' PULL_PASSWORD && echo
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: ghcr-pull
  namespace: dataagent
type: kubernetes.io/dockerconfigjson
stringData:
  .dockerconfigjson: |
    {"auths":{"ghcr.io":{"auth":"$(printf '%s' "data-agent-co:$PULL_PASSWORD" | base64 | tr -d '\n')"}}}
EOF
unset PULL_PASSWORD

Then reference it via imagePullSecrets in your values file. Without imageCredentials.password the chart also skips the fetch-ca-cert init container that downloads the agent’s CA certificate, so set config.tlsCACert to the CA PEM (available from support) as well.

Step 3 — Verify

kubectl -n dataagent get pods

The agent pod should show 5/5 Running, alongside the three monitoring pods (prometheus-server, kube-state-metrics, and one node-exporter per node). If you added --wait, Helm returned only once they were ready. Your cluster appears in the DataAgent dashboard once the agent connects and sends its first heartbeat. The dashboard’s cluster detail page shows a Prometheus status card once the agent reaches the bundled Prometheus (typically within 30 seconds of pod readiness).

If the pod doesn’t reach Running, or the cluster doesn’t appear, see Troubleshooting below.

Uninstall

helm uninstall dataagent -n dataagent
kubectl delete namespace dataagent

This removes all agent resources, including the mTLS credentials Secret, from your cluster. The Secret is the agent’s identity — a subsequent reinstall registers as a new agent in the hub, with no incident history or cluster continuity. To change versions, use helm upgrade --install (see Upgrading the Agent), not uninstall + reinstall.

Troubleshooting

If you hit something not listed, check kubectl logs -n dataagent -l app.kubernetes.io/name=dataagent and contact support.

Other Kubernetes platforms

This guide uses Amazon EKS as the worked example because it’s our most-tested target. The same install works on EKS-Anywhere, self-managed Kubernetes on EC2, GKE, AKS, and on-prem. The only EKS-specific commands are the aws eks update-kubeconfig step (use your platform’s equivalent) and the AWS-STS account-ID detection, which is automatically skipped on non-AWS clusters — everything else is identical.

Related

• Quickstart — the fastest path to a connected cluster.
• Agent Permissions & Security Posture — every RBAC rule, with rationale.
• Upgrading the DataAgent Agent — day-2 upgrades, the support policy, and rollback.