Quickstart

Get a cluster reporting to KubeSpend in ~60 seconds.

1. Get an API key

Sign in to the KubeSpend console and create an API key for your organization (SaaS: https://console.kubespend.io). For self-hosted, use your own console URL.

2. Install the agent

Minimal install — just your API key. The cluster name is auto-detected.

helm install kubespend-agent oci://public.ecr.aws/kubespend.io/charts/kubespend-agent \
  --version 0.1.0 \
  --namespace kubespend --create-namespace \
  --set apiKey="<YOUR_API_KEY>"

The charts are published as OCI artifacts on Amazon ECR Public, next to the agent images, so there is no helm repo add step and no credentials are needed to pull. --version pins the release; drop it to take the latest.

The cluster name is auto-detected (eksctl cluster-name label if present, else a stable id from the kube-system namespace UID). To force a name, add --set clusterId="my-cluster". You can also rename it later in the console.

3. Verify

kubectl -n kubespend rollout status deploy/kubespend-agent
kubectl -n kubespend logs -l app.kubernetes.io/name=kubespend-agent -f

Expect one kubespend-agent pod, whatever the node count. It is a single Deployment that reads the whole cluster; the per-node pods come from the network agent in step 4. Your cluster should appear in the console within a minute.

If helm install fails, see Troubleshooting. The two most common causes are a stale public.ecr.aws login, and objects left by an earlier install that did not use Helm.

4. (Optional) Add network measurement

# the chart in step 2 names its Service after the release: kubespend-agent here
kubectl get svc -n kubespend -l app.kubernetes.io/name=kubespend-agent

helm install kubespend-ebpf-agent oci://public.ecr.aws/kubespend.io/charts/kubespend-ebpf-agent \
  --version 0.1.0 \
  --namespace kubespend \
  --set relay.service="kubespend-agent"

# one kubespend-ebpf-agent pod per node, plus the one kubespend-agent pod
kubectl -n kubespend get pods -o wide

relay.service is required. It has no default and the chart refuses to render without one, so leaving it out fails helm install rather than the running pod.

No API key here. The eBPF agent sends its flow records to the kubespend-agent you installed in step 2, which aggregates them into its own batches and makes the single outbound push. It authenticates to that in-cluster relay with a projected ServiceAccount token, so no ingest credential is ever placed on your nodes.

The free trial includes network data up to a lifetime allowance of flow records (see what the trial includes); the paid network add-on removes the cap. Nodes must run Linux with kernel 6.6+ (for TCX).

The cluster name must match the metrics agent's. It is auto-detected the same way on both charts, so leaving clusterId unset on both is fine. If you set --set clusterId=… on kubespend-agent (as the console's command does when you name the cluster), pass the same value here, or the relay rejects every flow window and no network data appears. See installation.

Prerequisites

• Kubernetes 1.24+
• metrics-server installed (kubectl top nodes should work) — the free agent reads CPU/memory from it.
• Helm 3.8+ (OCI chart support)