Install the CloudZero Kubernetes Agent

The CloudZero Agent for Kubernetes collects pod-level CPU, memory, and GPU usage from your clusters and sends it to CloudZero. CloudZero combines this usage data with the actual cost of each VM from your cloud provider bill to allocate Kubernetes costs by cluster, namespace, workload, and label.

The agent is read-only. It collects metrics and does not modify your clusters.

Overview

Installing the CloudZero Agent takes four steps:

1. Create a CloudZero API key
2. Install the agent with Helm
3. Validate the installation
4. (Optional) Configure Kubernetes labels

Supported platforms

• AWS Elastic Kubernetes Service (EKS)
• Azure Kubernetes Service (AKS)
• Google Kubernetes Engine (GKE)
• Self-managed Kubernetes on AWS, Azure, or Google Cloud

What you need

• A CloudZero user with permissions to create API keys
• A Kubernetes v1.23+ cluster with a CRI-compliant runtime (for example, containerd)
• Helm v3+
• Network egress on port 443 to:
  • api.cloudzero.com (CloudZero API)
  • *.s3.amazonaws.com (metrics delivery)
• If your cluster uses NetworkPolicies, allow traffic from the Kubernetes API server to the cloudzero namespace (the agent's admission webhook receives requests from the API server)

Step 1: Create a CloudZero API key

The agent authenticates with CloudZero using an API key. Create a new API key and assign it the following five scopes:

• container-metrics_v1:abandon
• container-metrics_v1:get-status
• container-metrics_v1:legacy
• container-metrics_v1:upload
• insights:read_insights

Step 2: Install the agent

The install command requires four parameters:

Finding your cloudAccountId:

Option A: Helm install (recommended)

1. Add the CloudZero Helm repository and update your local chart index:

helm repo add cloudzero https://cloudzero.github.io/cloudzero-charts
helm repo update

2. Run the install command, replacing the placeholder values with your own:

helm install cloudzero-agent cloudzero/cloudzero-agent \
    --namespace cloudzero --create-namespace \
    --set apiKey=<CLOUDZERO_API_KEY> \
    --set clusterName=<CLUSTER_NAME> \
    --set-string cloudAccountId=<CLOUD_ACCOUNT_ID> \
    --set region=<REGION>

3. Confirm Helm displays a success message when the installation completes.

Option B: Raw YAML manifests

If your organization does not use Helm for deployments, you can generate flat Kubernetes manifests and apply them directly.

helm repo add cloudzero https://cloudzero.github.io/cloudzero-charts
helm repo update

helm template cloudzero-agent cloudzero/cloudzero-agent \
    --namespace cloudzero \
    --set apiKey=<CLOUDZERO_API_KEY> \
    --set clusterName=<CLUSTER_NAME> \
    --set-string cloudAccountId=<CLOUD_ACCOUNT_ID> \
    --set region=<REGION> > cloudzero-agent.yaml

kubectl create namespace cloudzero
kubectl apply -f cloudzero-agent.yaml -n cloudzero

Step 3: Validate the installation

1. Confirm the agent pods are running:

kubectl -n cloudzero get pods

All pods should show a Running status within a few minutes.

2. Check the agent validation logs for any issues:

kubectl -n cloudzero logs -l app.kubernetes.io/part-of=cloudzero-agent,app.kubernetes.io/name=server -c env-validator-run

A successful validation shows all checks passing. If any check fails, see the CloudZero Agent troubleshooting guide on GitHub.

Step 4 (optional): Configure Kubernetes labels

By default, the agent exports only the app.kubernetes.io/component label from pods and namespaces. To see your own labels in CloudZero, add them before your first data appears.

1. Create a Helm values file named values.yaml on the machine where you run Helm commands. This file overrides the chart's default configuration:

insightsController:
  labels:
    patterns:
      - 'app.kubernetes.io/component'
      - '^team'
      - 'environment'
      - 'app'
    resources:
      pods: true
      namespaces: true
      deployments: true

Patterns are regular expressions matched against label keys. For example, '^team' matches any label starting with "team."

2. Apply the configuration:

helm upgrade cloudzero-agent cloudzero/cloudzero-agent \
    --namespace cloudzero \
    -f values.yaml

For annotations, resource type options, and disambiguation rules, see Advanced Agent Configuration.

What to expect

After the agent is installed, CloudZero begins collecting metrics immediately. Cost data appears in CloudZero within 48 hours.

Once data is available, you can view Kubernetes cost breakdowns and resource efficiency in Explorer. CloudZero also generates rightsizing recommendations for over-provisioned CPU and memory workloads. You can check on your connected clusters at any time from the Kubernetes Integration page in Settings.

Advanced configuration

For Kubernetes Secrets, annotations, TLS certificates, Istio compatibility, and custom kube-state-metrics, see Advanced Agent Configuration.