Skip to content
Start free

Getting Started

~5 Minutes

Quick Start

This guide installs the Kubeadapt agent with Helm and connects your cluster to the dashboard. It takes about five minutes; the first cost figures appear within 30 minutes.

  • 5 steps
  • ~5 min
  • Helm 3

Before you start

You need

  • Required

    Kubernetes 1.24 to 1.35

    EKS, GKE, AKS, OpenShift, kubeadm, kops, or Rancher. GKE Autopilot and EKS Fargate run the cost agent; the network agent needs standard nodes.

  • Required

    Helm 3

    For the chart install (helm version).

  • Required

    kubectl

    With rights to create a namespace and cluster-wide RBAC.

  • Required

    metrics-server

    Running in the cluster (kubectl get deployment metrics-server -n kube-system). GKE and AKS include it; EKS and kind clusters need it installed. Without it, the agent records cost but not usage, so there are no rightsizing recommendations.

  • Required

    Outbound HTTPS

    To ingest.kubeadapt.io from the cluster.

  • Optional

    AWS account

    Connect it later so Reserved Instance and Savings Plan discounts show in your prices.

  1. 1

    Step 1: Add the Helm repository

    Add the chart repository so Helm can find the Kubeadapt chart.

    bash
    helm repo add kubeadapt https://kubeadapt.github.io/kubeadapt-helm
helm repo update

    Confirm it appears:

    bash
    helm repo list | grep kubeadapt
  2. 2

    Step 2: Get an agent token

    Each cluster gets its own token from the dashboard. The agent sends it as a bearer token over HTTPS.

    1. Open app.kubeadapt.io.
    2. Navigate to Clusters → Add Cluster.
    3. Pick your provider: Amazon EKS, Google GKE, Azure AKS, or On-Premises.
    4. Name the cluster and choose Production or Non-Production.
    5. Copy the install command, or just the token.

    The install step also has a switch for auto-upgrade, which adds a --set flag to the command. NVIDIA GPUs are picked up automatically when DCGM Exporter runs. To reflect AWS Reserved Instance and Savings Plan discounts, connect your AWS account afterwards (see AWS integration).

  3. 3

    Step 3: Install the agent

    Keep the token in a Secret, so it never appears in the Helm command, your shell history or helm get values:

    bash
    kubectl create namespace kubeadapt
kubectl create secret generic kubeadapt-agent-token \
  --namespace kubeadapt --from-literal=token="<your-token>"
helm install kubeadapt kubeadapt/kubeadapt \
  --namespace kubeadapt \
  --set agent.config.existingSecret=kubeadapt-agent-token

    For a quick try, paste the dashboard’s command, or use this one:

    bash
    helm install kubeadapt kubeadapt/kubeadapt \
  --namespace kubeadapt --create-namespace \
  --set agent.config.token="<your-token>"

    The chart creates the agent Deployment and Service, a ServiceAccount, a ClusterRole with list and watch on cluster resources, a Role in the kubeadapt namespace (Jobs, ConfigMaps, and read access to Secrets), and a Secret that holds the token. It adds no CRDs and no admission webhooks. With agent.config.existingSecret set, the chart reads the token from your Secret (key token) and creates none. From chart 1.0.8 the agent pod meets the Kubernetes restricted Pod Security Standard: it runs as a non-root user, with a read-only root filesystem and no privilege escalation.

    On OpenShift, add these flags so the restricted-v2 SCC can assign the user and group:

    bash
    --set agent.podSecurityContext.runAsUser=null \
--set agent.podSecurityContext.runAsGroup=null \
--set agent.podSecurityContext.fsGroup=null
  4. 4

    Step 4: Verify the install

    Check that the agent pod is running:

    bash
    kubectl get pods -n kubeadapt

    Expected output

    plaintext
    NAME                              READY   STATUS    RESTARTS   AGE
kubeadapt-agent-7fbd9d8c4-xq2nm   1/1     Running   0          45s

    Then check the logs. The agent logs one line when it starts and one each time a snapshot reaches Kubeadapt, about once a minute:

    bash
    kubectl logs -n kubeadapt deploy/kubeadapt-agent \
  | grep -E "capabilities detected|agent is ready|snapshot sent"

    Expected output

    plaintext
    … INFO cluster capabilities detected metrics_server=true vpa=false karpenter=false dcgm_exporter=false provider=aws
… INFO agent is ready state=…
… INFO snapshot sent successfully snapshot_id=… quota_plan=… within_quota=true

    If no “snapshot sent successfully” line appears after two minutes, see Troubleshooting below.

  5. 5

    Step 5: Open your cluster in the dashboard

    1. Return to app.kubeadapt.io.
    2. Your new cluster appears in the Clusters list once the first snapshot arrives, usually within a minute.
    3. The first cost figures appear within 30 minutes.
    4. Rightsizing recommendations use a 7-day usage window, so the first ones appear about a week after install.

    Your cluster is now sending data to Kubeadapt.

What’s next

Troubleshooting

  • Pod stuck in Pending

    Usually not enough free capacity on any node. The agent requests 100m CPU and 256Mi memory. Free up capacity or add a node.

  • Pod stuck in ImagePullBackOff

    Outbound HTTPS to the image registry (public.ecr.aws) is blocked. Mirror the image to an internal registry and override agent.image.repository.

  • Snapshots not reaching Kubeadapt

    Check outbound HTTPS to ingest.kubeadapt.io and that the token is correct. The agent retries failed sends; each failure is logged as snapshot send failed with the error.

  • No rightsizing recommendations after 7 days

    Verify metrics-server is healthy: kubectl top nodes should return data. Without metrics, the agent records cost but not usage.

Still stuck? Email support@kubeadapt.io with the agent logs.

Uninstalling

bash
helm uninstall kubeadapt --namespace kubeadapt
kubectl delete namespace kubeadapt

helm uninstall leaves the kubeadapt namespace and any Secret you created yourself; deleting the namespace removes both. Then delete the cluster on the Clusters page in Kubeadapt, which revokes its token.

Uninstalling stops data collection. Data already sent remains in your Kubeadapt organization. An admin can delete the organization in Settings → General, which removes everyone’s access at once. To have its stored data erased, write to support@kubeadapt.io.