Helm charts

This page covers how to install and manage Cast AI components using Helm. The recommended approach is the umbrella Helm chart (castai-helm/castai), which installs all required components for your chosen operating mode in a single release. Individual chart installs are available for advanced use cases.

📘

Simplest option: castctl

For the fastest way to connect a cluster, use the castctl CLI. It auto-detects your cloud provider, handles IAM setup, and runs the Helm install in a single command. The steps below are for users who prefer direct Helm control or need GitOps-compatible manifests.

Prerequisites

• helm v3.14.0 or higher (required for the --reset-then-reuse-values flag)
• kubectl configured for your target cluster
• A Cast AI organization-level API key from console.cast.ai → Service Accounts

Add the Cast AI Helm repository:

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

Umbrella chart

The umbrella chart (castai-helm/castai) uses Helm tags to control which components are installed. Each tag activates a different operating mode. You switch between modes by flipping tags in a single helm upgrade command.

For provider-specific walkthroughs that include the Terraform configuration needed for node autoscaling and full modes, see the GitOps onboarding guides:

Operating modes

Choose the mode that matches the level of automation you need:

• readonly — Cost visibility and security telemetry only. No changes to workloads or nodes. Start here if you want to evaluate Cast AI before enabling automation.
• workload-autoscaler — Automatically right-sizes workload CPU and memory requests based on actual usage. No cloud IAM setup or Terraform required.
• node-autoscaler — Automated node provisioning, bin-packing, and Spot Instance management. Requires Terraform for cloud IAM. Includes Container Live Migration.
• full — Combines node autoscaling with Workload Autoscaler. The most complete mode.

📘

Note

Only one mode tag should be true at a time. The full mode combines node autoscaling with Workload Autoscaler.

Install in read-only mode

Read-only mode installs observability components. No Terraform or cloud IAM setup is needed.

helm upgrade -i castai castai-helm/castai -n castai-agent --create-namespace \
  --set global.castai.apiKey="<your-castai-api-key>" \
  --set global.castai.provider="<eks|gke|aks>" \
  --set tags.readonly=true

Replace <eks|gke|aks> with your cloud provider.

  kubectl get pods -n castai-agent

Install in Workload Autoscaler mode

Workload Autoscaler mode automatically right-sizes workload CPU and memory requests based on actual usage. No Terraform or cloud IAM setup is needed.

helm upgrade -i castai castai-helm/castai -n castai-agent --create-namespace \
  --set global.castai.apiKey="<your-castai-api-key>" \
  --set global.castai.provider="<eks|gke|aks>" \
  --set tags.workload-autoscaler=true

Configure scaling policies and workload-level settings from the Cast AI console or via annotations.

  kubectl get pods -n castai-agent

Install in node autoscaler or full mode

Node autoscaler and full modes require cloud IAM resources for node management. Use Terraform to create them, then install the Helm release. See the provider-specific GitOps guides linked above for the complete Terraform configuration:

helm upgrade -i castai castai-helm/castai -n castai-agent --create-namespace \
  --set global.castai.apiKey="<your-castai-api-key>" \
  --set global.castai.provider="<eks|gke|aks>" \
  --set tags.full=true

Replace tags.full=true with tags.node-autoscaler=true if you do not need Workload Autoscaler.

  kubectl get pods -n castai-agent

Upgrade between modes

Flip the relevant tags and pass --reset-then-reuse-values. The chart enforces that exactly one mode tag is true at a time — if multiple tags are enabled, helm upgrade fails with a validation error. Always explicitly disable the previous mode when enabling the new one. Existing component overrides carry forward automatically.

For example, upgrading from read-only to full:

helm upgrade castai castai-helm/castai -n castai-agent \
  --reset-then-reuse-values \
  --set tags.readonly=false \
  --set tags.full=true

Or from workload-autoscaler to full:

helm upgrade castai castai-helm/castai -n castai-agent \
  --reset-then-reuse-values \
  --set tags.workload-autoscaler=false \
  --set tags.full=true

📘

Note

Moving to node-autoscaler or full from a Helm-only mode requires completing the Terraform configuration first, since those modes need cloud IAM resources. See the provider-specific GitOps guides above.

Upgrade to a newer chart version

To upgrade all components to the latest chart version while preserving your existing values:

helm repo update castai-helm
helm upgrade castai castai-helm/castai -n castai-agent --reset-then-reuse-values

Customize chart values

The umbrella chart passes values through to each sub-component. Create a values.yaml file and use the -f flag:

helm upgrade -i castai castai-helm/castai -n castai-agent --create-namespace \
  --set global.castai.apiKey="<your-castai-api-key>" \
  --set global.castai.provider="<eks|gke|aks>" \
  --set tags.readonly=true \
  -f custom-values.yaml

Example custom-values.yaml:

global:
  tolerations:
    - key: "dedicated"
      operator: "Equal"
      value: "castai"
      effect: "NoSchedule"

You can also override values for a specific component using the component's key as a prefix. For example, to set a custom resource limit on the evictor:

autoscaler:
  castai-evictor:
    resources:
      limits:
        memory: 512Mi

Inject a custom CA certificate

If your environment requires components to trust a private CA — for example, to pull images from a private registry over TLS — you can provide a CA certificate via a Kubernetes secret and reference it with trustedCACertSecretRef on each component.

⚠️

Key name inconsistency

Components expect the certificate under different secret keys:

Secret key	Components
TLS_CA_CERT_FILE	castai-agent, castai-cluster-controller, castai-spot-handler
TLS_CA_CERT	castai-workload-autoscaler

Until this is standardized, populate the secret with both key names pointing to the same certificate file.

castai-kvisor does not support trustedCACertSecretRef. castai-live mounts the secret as a volume and does not read an environment variable key, so no special key handling is required for it.

Create the secret with both keys:

kubectl create secret generic castai-ca-cert \
  -n castai-agent \
  --from-file=TLS_CA_CERT_FILE=ca.crt \
  --from-file=TLS_CA_CERT=ca.crt

Then reference the secret across all supporting components when upgrading the umbrella chart:

helm upgrade castai castai-helm/castai -n castai-agent \
  --reset-then-reuse-values \
  --set autoscaler.castai-agent.trustedCACertSecretRef="castai-ca-cert" \
  --set autoscaler.castai-cluster-controller.trustedCACertSecretRef="castai-ca-cert" \
  --set autoscaler.castai-spot-handler.trustedCACertSecretRef="castai-ca-cert" \
  --set autoscaler.castai-workload-autoscaler.trustedCACertSecretRef="castai-ca-cert" \
  --set autoscaler.castai-live.trustedCACertSecretRef="castai-ca-cert"

Individual chart installs (advanced)

In most cases, the umbrella chart is the recommended approach. Individual chart installs are available for environments where you need to manage each component's lifecycle independently, such as when using a GitOps tool that requires separate Helm releases per component.

⚠️

Warning

When installing components individually, you are responsible for ensuring that all required components for your desired functionality are installed and kept compatible. The umbrella chart handles this automatically.

Create the castai-agent namespace before installing the first component if it does not already exist:

kubectl create namespace castai-agent --dry-run=client -o yaml | kubectl apply -f -

Cluster controller

helm upgrade -i cluster-controller castai-helm/castai-cluster-controller -n castai-agent --create-namespace \
  --set castai.apiKey="<your-api-key>" \
  --set castai.clusterID="<your-cluster-id>"

For AKS clusters, add --set aks.enabled=true.

Evictor

helm upgrade -i castai-evictor castai-helm/castai-evictor -n castai-agent --create-namespace \
  --set castai.apiKey="<your-api-key>" \
  --set castai.clusterID="<your-cluster-id>" \
  --set dryRun=false

Learn more about bin-packing and Evictor.

Spot Handler

helm upgrade -i castai-spot-handler castai-helm/castai-spot-handler -n castai-agent --create-namespace \
  --set castai.clusterID="<your-cluster-id>" \
  --set castai.provider="<aws|gcp|azure>"

Learn more about Spot Handler.

Kvisor

helm upgrade -i castai-kvisor castai-helm/castai-kvisor -n castai-agent --create-namespace \
  --set castai.apiKey="<your-api-key>" \
  --set castai.clusterID="<your-cluster-id>" \
  --set controller.extraArgs.cloud-provider="<eks|gke|aks>" \
  --set castai.apiURL="https://api.cast.ai"

📘

Note

If your cluster is not in the US region, set castai.apiURL to your regional endpoint. See Communication requirements for the full list.

Workload Autoscaler

Workload Autoscaler consists of two charts that work together:

helm upgrade -i castai-workload-autoscaler castai-helm/castai-workload-autoscaler -n castai-agent --create-namespace \
  --set castai.apiKey="<your-api-key>" \
  --set castai.clusterID="<your-cluster-id>"

helm upgrade -i castai-workload-autoscaler-exporter castai-helm/castai-workload-autoscaler-exporter -n castai-agent --create-namespace \
  --set castai.apiKey="<your-api-key>" \
  --set castai.clusterID="<your-cluster-id>"

When upgrading, update both charts together:

helm repo update castai-helm
helm upgrade -i castai-workload-autoscaler castai-helm/castai-workload-autoscaler -n castai-agent --reset-then-reuse-values
helm upgrade -i castai-workload-autoscaler-exporter castai-helm/castai-workload-autoscaler-exporter -n castai-agent --reset-then-reuse-values

Container Live Migration controller

helm upgrade -i castai-live castai-helm/castai-live -n castai-agent --create-namespace \
  --set castai.apiKey="<your-api-key>" \
  --set castai.clusterID="<your-cluster-id>"

For Container Live Migration requirements and supported providers, see Container Live Migration.

Kentroller (Karpenter integration)

helm upgrade -i castai-kentroller castai-helm/castai-kentroller -n castai-agent --create-namespace \
  --set castai.apiKey="<your-api-key>" \
  --set castai.clusterID="<your-cluster-id>"

See Karpenter Enterprise suite for details.

Next steps