Monitor Multiple Clusters

CostPilot supports multiple Kubernetes clusters under a single account with no limit on cluster count. Each cluster gets its own agent installation and API key, but all cost data is aggregated into a unified view — letting you compare clusters, set per-cluster budgets, and understand your total infrastructure spend across regions and cloud providers.

Step 1: Register each cluster in Settings

Before installing the agent, register the cluster in CostPilot to obtain an API key.

Navigate to Settings → Clusters.
Click Add cluster.
Enter a descriptive name (e.g. prod-eu-west-1, staging-us-east-1).
Select the cloud provider and region (used for pricing lookups).
Click Create. CostPilot generates a unique API key for this cluster.
Copy the API key — you will need it in the next step.

ℹ Note

Each cluster has its own API key scoped exclusively to that cluster. Rotating one cluster’s key does not affect others. Keys are not displayed again after creation — store them in your secrets manager immediately.

Repeat this for every cluster you want to monitor.

Step 2: Install the agent in each cluster

Deploy a separate Helm release into each cluster. Switch your kubectl context before each installation.

# Switch to the target cluster context
kubectl config use-context <cluster-context>

# Create the namespace
kubectl create namespace costpilot

# Store the API key as a secret
kubectl create secret generic cp-agent-secret \
  --namespace costpilot \
  --from-literal=cluster-api-key=<cluster-api-key>

# Install the agent (defaults to EU region)
helm upgrade --install costpilot costpilot/agent \
  --namespace costpilot

For US clusters, set the region:

helm upgrade --install costpilot costpilot/agent \
  --namespace costpilot \
  --set backend.ingesterEndpoint=us

Repeat for each cluster, using the corresponding API key.

ℹ Note

The cluster display name is configured in Settings → Clusters when you register the cluster — not via Helm. The agent identifies itself to CostPilot using the API key, which maps to the cluster you registered. No additional Helm values are needed to set the cluster name.

GitOps / Flux / ArgoCD

If you manage cluster add-ons via GitOps, create a HelmRelease per cluster in your repository. Each HelmRelease references the cluster-specific secret from your secrets store (e.g. External Secrets Operator pulling from Vault or AWS Secrets Manager).

Step 3: Compare clusters in the Dashboard

Once metrics are flowing from multiple clusters (allow 5–10 minutes per cluster after installation), the Dashboard shows a cluster selector in the top navigation bar.

All clusters view: aggregated spend, efficiency, and idle cost across your entire account
Per-cluster view: filter to a single cluster for detailed analysis

The Idle cost breakdown and Efficiency score cards both update to reflect the selected scope.

Step 4: Use the Cluster dimension in Cost Explorer

In Cost Explorer, set the Group by dimension to Cluster to see a side-by-side cost breakdown.

This view is useful for:

Comparing the cost-efficiency of clusters across cloud providers
Identifying which cluster has the highest idle cost as a percentage
Allocating shared platform costs across business units that own separate clusters

You can combine the Cluster dimension with other dimensions using filters. For example: filter to cluster = prod-eu-west-1, then group by Namespace to see namespace-level costs for that specific cluster.

Step 5: Set per-cluster alerts

Create separate alert rules for each cluster to catch budget overruns at the cluster level.

Navigate to Settings → Alerts and click New alert.
Set the Scope to Cluster and select the cluster from the dropdown.
Choose an alert type:
- Daily budget: fires if the cluster spends more than X per day
- Absolute threshold: fires if monthly spend exceeds X
- Percentage change: fires if week-over-week spend increases by more than X%
Add a notification channel (email, Slack, or webhook).
Save.

✦ Tip

A useful starting configuration for each cluster is two alerts: a daily budget alert at 110% of your expected daily rate, and a percentage change alert at +30% week-over-week. Together these catch both sudden spikes and gradual creep.

Multi-cloud and multi-region considerations

Different cloud providers

CostPilot handles pricing differences between cloud providers automatically. Each cluster’s metrics are priced using the node instance types and pricing data from the registered provider and region. AWS, GCP, and Azure are all supported.

When comparing clusters across providers in Cost Explorer, costs are displayed in a common currency so comparisons are meaningful.

Clusters in multiple regions

Register each cluster with its correct region so CostPilot uses the right on-demand pricing. Instance prices vary significantly by region — us-east-1 is typically cheaper than eu-west-1 for equivalent instance types.

Cluster tagging for attribution

If your clusters map to business units, environments, or products, use the cluster name to encode that context (e.g. prod-payments-eu, staging-ml-us). This makes Cost Explorer’s Cluster dimension immediately readable without additional label configuration.

Common issues

Issue	Cause	Resolution
Cluster shows no data	Wrong API key	Verify the secret in the `costpilot` namespace matches the key from Settings
Cluster shows up twice	Two agents with same key	Remove one installation; each key should map to exactly one agent
Costs look lower than expected	Wrong region registered	Update the cluster’s region in Settings → Clusters
Missing namespaces	RBAC insufficient	Ensure the agent ServiceAccount has ClusterRole permissions to list pods across all namespaces