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.
• Prometheus + Alertmanager are required for incident signals; install kube-prometheus-stack if you don’t already have them.
• The Alertmanager → agent webhook pipeline (PrometheusRule + receiver wiring) is enabled separately after the agent is connected — contact support for the Prometheus/Alertmanager wiring guide.

Requirements

Cluster prerequisites

In-cluster observability

If you don’t already have Prometheus and Alertmanager

This is the recommended install — we’ve validated it end-to-end with the agent. It includes Prometheus, Alertmanager, the Prometheus Operator, and kube-state-metrics, with chart defaults the agent’s discovery recognises out of the box:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm upgrade --install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring --create-namespace \
  --version 73.2.0

Bring your own — what the agent looks for

The agent discovers Prometheus in two phases — Prometheus Operator CRD first (any namespace), then a Service-name scan in well-known namespaces. You don’t configure anything; the agent picks up whatever matches below.

• Namespaces scanned: monitoring, prometheus, kube-system, observability, default.
• Service names matched: prometheus, prometheus-server, kube-prometheus-stack-prometheus, prometheus-operated, prometheus-kube-prometheus-prometheus.
• Labels matched: app=prometheus or app.kubernetes.io/name=prometheus.
• Port preference: named http-web / http / web, then 9090, then the first port (with a warning).
• Operator CRD: if prometheuses.monitoring.coreos.com exists and any Prometheus CR is present, the agent connects to a Service whose name matches the CR’s name, in the CR’s namespace, on the port from the CR’s spec.port (default 9090). Multiple CRs → first by namespace/name order, with a warning.

Custom Prometheus setups

• Multiple Prometheus instances: the agent picks the first by namespace/name order. Label or rename so only one matches if you need to pin selection.
• Token- or basic-auth-protected Prometheus (returns HTTP 401): appears as auth required in the dashboard. Prometheus-sourced signal ingestion is paused until auth support lands.
• HTTPS-only Prometheus (no plain-HTTP Service): appears as unreachable. The agent probes http:// only — expose a plain-HTTP Service in a recognised namespace, or wait for TLS support.
• Custom alert rules: with default kube-prometheus-stack, your PrometheusRule resources need labels.release: prometheus to be evaluated. To evaluate rules cluster-wide, set prometheus.prometheusSpec.ruleSelectorNilUsesHelmValues: false on the chart.

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

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 four containers by default (orchestrator, K8sGPT, metrics collector, topology analyzer). 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.12 or newer with OCI registry support.

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:

kubectl run -n default --rm -i --restart=Never net-check --image=busybox:1.37 -- \
  sh -c "nc -zv -w5 tunnel.data-agent.co 443 && nc -zv -w5 ghcr.io 443"

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.

Both 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 \
  --namespace dataagent --create-namespace \
  --set 'imageCredentials.password=<GHCR_PAT>' \
  --set 'config.authToken=<TOKEN_FROM_DASHBOARD>' \
  --set 'config.clusterName=<YOUR_CLUSTER_NAME>'

Replace <GHCR_PAT>, <TOKEN_FROM_DASHBOARD>, and <YOUR_CLUSTER_NAME> with the values provided during the Connect flow. The hub endpoint defaults to the production tunnel, so no config.hubUrl override is needed.

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 PAT into a shell variable (not into argv) and piping the Secret manifest through stdin keeps the PAT off the command line:

kubectl create namespace dataagent
read -srp 'GHCR PAT: ' GHCR_PAT && 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' "<user>:$GHCR_PAT" | base64 | tr -d '\n')"}}}
EOF
unset GHCR_PAT

Then reference it via imagePullSecrets in your values file.

Step 3 — Verify

kubectl -n dataagent get pods

The pod should reach Running within about 60 seconds. 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 discovery completes (typically within 30 seconds of pod readiness).

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

Step 4 — Enable the Alertmanager signal pipeline

Step 2 brings the agent up read-only against your cluster. Turning on Prometheus-sourced incident signals — the production signal source — is a separate setup step: finding your Prometheus ruleSelector, creating a shared webhook bearer token, enabling the agent’s alertWebhook + default PrometheusRule, and pointing Alertmanager at the agent’s /alerts endpoint. Contact support to set this up.

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.