Quick Start

Before you start

You need

• Required

  Kubernetes 1.24+

  EKS, GKE, AKS, OpenShift, kubeadm, kops, or Rancher.

• Required

  Helm 3

  For the chart install (helm version).

• Required

  kubectl

  With cluster admin access.

• Required

  metrics-server

  Running in the cluster (kubectl get deployment metrics-server -n kube-system). EKS, GKE, and AKS include it by default. Without it, no rightsizing recommendations.

• Required

  Outbound HTTPS

  To ingest.kubeadapt.io from the cluster.

• Optional

  AWS account

  Connect for Reserved Instance and Savings Plan visibility. Multi-account (Organizations) is supported.

1. 1

   Step 1 — Add the Helm repository

   Wire up the chart repo so Helm knows where to fetch Kubeadapt from.

   bashCopy

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

   Confirm it appears:

   bashCopy

   helm repo list | grep kubeadapt

2. 2

   Step 2 — Generate an agent token

   The dashboard generates a per-cluster token. Tokens are cluster-scoped and revocable.

   1. Open app.kubeadapt.io.
   2. Navigate to Clusters → Add Cluster.
   3. Pick your provider: AWS, GCP, Azure, or Self-hosted.
   4. Choose the environment type — production-like or non-production-like. This affects alert thresholds and recommendation aggressiveness.
   5. Copy the generated install command, or just the token.

   The dashboard also offers a one-click AWS account integration if you want RI and Savings Plan discounts reflected in pricing. You can connect this later under Clusters → Cloud Accounts.

3. 3

   Step 3 — Install the agent

   Paste the dashboard's command, or use this template:

   bashCopy

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

   The chart provisions a single agent deployment, a service account with read-only RBAC, and a ConfigMap. No CRDs, no admission webhooks, no cluster-wide mutating permissions.

4. 4

   Step 4 — Verify the install

   Check the agent pod is running:

   bashCopy

   kubectl get pods -n kubeadapt

   Expected output

   plaintextCopy

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

   Tail the logs to confirm snapshots are leaving the cluster:

   bashCopy

   kubectl logs -n kubeadapt -l app.kubernetes.io/component=agent --tail=10

   Expected output

   plaintextCopy

   cluster capabilities detected  metrics_server=true  provider=aws
   snapshot delivered             duration=1.2s  compressed_size=45KB

   If snapshots aren't delivering, 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 60 seconds.
   3. Wait 5–30 minutes for the first cost snapshot to be priced.
   4. Full multi-day breakdowns and rightsizing recommendations require 1–24 hours of usage data, depending on cluster activity.

   That's it. You're collecting cost data.

What's next

Six paths to explore from here.

• Connect your cloud account

  Wire up AWS for RI and Savings Plan discounts. GCP CUDs and Azure RI/SP are on the roadmap.

• Understand cost attribution

  How dollars flow from cloud bill to container.

• Apply rightsizing

  Follow the rightsizing guide. Most teams see 20–40% savings in week one.

• Use the CLI

  Query costs and recommendations from your terminal with the kubeadapt CLI.

• Hit the REST API

  Build dashboards or pipe data into your warehouse with the REST API.

• Tune the agent

  Resource limits, eBPF networking, auto-upgrade.

Troubleshooting

Common gotchas, sorted by frequency.

• Pod stuck in Pending

  Likely insufficient node capacity. The default request is small (50m CPU, 64Mi memory) but constrained clusters can still hit it. Increase the cluster or reduce another workload.

• Pod stuck in ImagePullBackOff

  Outbound HTTPS to the container registry (Docker Hub by default) is blocked. Mirror the image to an internal registry and override agent.image.repository.

• Snapshots not delivering

  Check outbound HTTPS to ingest.kubeadapt.io. The agent retries with exponential backoff; persistent failures show in the logs as snapshot delivery failed.

• No rightsizing recommendations after 24 hours

  Verify metrics-server is healthy: kubectl top nodes should return data. Without metrics, the agent can record costs but not utilisation.

helm uninstall kubeadapt --namespace kubeadapt
kubectl delete namespace kubeadapt

Revoke the token under Clusters → [cluster name] → Settings in the dashboard once the agent stops.