EKS via GitOps

This guide covers onboarding an EKS cluster to Cast AI using a GitOps approach with the umbrella Helm chart (castai-helm/castai).

The umbrella chart uses Helm tags to control which Cast AI components are installed. Each tag activates a different operating mode — for example, --set tags.readonly=true installs only observability components, while --set tags.full=true installs the complete suite for EKS. You switch between modes by flipping tags in a single helm upgrade command. For more background on the umbrella chart, see Terraform provider.

Choose the mode that fits your needs. If you start with a lighter mode, you can upgrade later without reinstalling (see Upgrading between modes).

Umbrella chart modes on EKS

The table below shows which components each mode installs on EKS.

📘

Note

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

Prerequisites

All modes require:

• A Cast AI account and an organization-level API key from console.cast.ai → Service Accounts
• helm v3.14.0 or higher (required for the --reset-then-reuse-values flag)
• The castai-helm Helm repository added:

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

Node autoscaler and full modes additionally require:

• terraform v1.3.2 or higher
• AWS CLI configured with permissions to create IAM resources in your AWS account

Installing in read-only mode (Helm only)

Read-only mode installs observability components that let Cast AI monitor your cluster without making any changes to workloads or nodes. No Terraform 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" \
  --set tags.readonly=true

After the pods become ready, your cluster appears as Read only in the Cast AI console.

  kubectl get pods -n castai-agent

Installing in Workload Autoscaler mode (Helm only)

Workload Autoscaler mode for automatically right-sizing workload CPU/memory requests based on actual usage. No Terraform 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" \
  --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

Installing in node autoscaler or full mode (Terraform + Helm)

Node autoscaler and full modes enable node provisioning, bin-packing, Spot Instance handling, and workload eviction. These modes require an AWS IAM role with permissions for node management. Terraform creates it.

• tags.node-autoscaler=true for Node autoscaling only (includes Container Live Migration).
• tags.full=true for Node autoscaling + Workload Autoscaler (includes Container Live Migration).

Create the Terraform configuration

Create the following files in your Terraform project directory.

versions.tf

terraform {
  required_version = ">= 1.3.2"
  required_providers {
    castai = {
      source  = "castai/castai"
      version = ">= 3.11.0"
    }
    aws = {
      source  = "hashicorp/aws"
      version = ">= 2.49"
    }
  }
}

providers.tf

provider "castai" {
  api_url   = var.castai_api_url
  api_token = var.castai_api_token
}

provider "aws" {
  region = var.aws_cluster_region
}

variables.tf

variable "aws_account_id" {
  type        = string
  description = "AWS account ID where the EKS cluster is located."
}

variable "aws_cluster_region" {
  type        = string
  description = "Region of the EKS cluster to be connected to Cast AI."
}

variable "aws_cluster_name" {
  type        = string
  description = "EKS cluster name in AWS account."
}

variable "aws_cluster_vpc_id" {
  type        = string
  description = "VPC ID of the EKS cluster."
}

variable "delete_nodes_on_disconnect" {
  type        = bool
  description = "Optionally delete Cast AI created nodes when the cluster is destroyed."
  default     = false
}

variable "castai_api_token" {
  type        = string
  description = "Cast AI API token created in console.cast.ai API Access keys section."
}

variable "castai_api_url" {
  type        = string
  description = "Cast AI API URL."
  default     = "https://api.cast.ai"
}

castai.tf

resource "castai_eks_cluster" "this" {
  account_id = var.aws_account_id
  region     = var.aws_cluster_region
  name       = var.aws_cluster_name

  delete_nodes_on_disconnect = var.delete_nodes_on_disconnect
  assume_role_arn            = module.castai-eks-role-iam.role_arn
}

module "castai-eks-role-iam" {
  source           = "castai/eks-role-iam/castai"
  version          = "~> 1.0"
  aws_account_id   = var.aws_account_id
  aws_cluster_vpc_id = var.aws_cluster_vpc_id
  aws_cluster_region = var.aws_cluster_region
  aws_cluster_name   = var.aws_cluster_name
}

outputs.tf

output "cluster_id" {
  value       = castai_eks_cluster.this.id
  description = "Cast AI cluster ID."
}

output "cluster_token" {
  value       = castai_eks_cluster.this.cluster_token
  description = "Cast AI cluster token used by Castware to authenticate to SaaS."
  sensitive   = true
}

tf.vars.example

castai_api_token    = "PLACEHOLDER"
aws_account_id      = "PLACEHOLDER"      # e.g. "123456789012"
aws_cluster_region  = "PLACEHOLDER"      # e.g. "us-east-1"
aws_cluster_name    = "PLACEHOLDER"
aws_cluster_vpc_id  = "PLACEHOLDER"      # e.g. "vpc-0abc1234def56789"

Run Terraform

Copy the example variables file, fill in your values, and apply:

cp tf.vars.example terraform.tfvars
# Edit terraform.tfvars with your AWS account details

terraform init
terraform apply

Terraform registers the cluster with Cast AI and creates the AWS IAM role. Capture the outputs. You'll need them for the Helm release:

terraform output cluster_id
terraform output -raw cluster_token

⚠️

Warning

The cluster_token expires after a few hours if no Cast AI component connects. Run the Helm install promptly after this step.

Install the Helm release

For a fresh install, use helm upgrade -i with the mode tag that matches your needs:

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" \
  --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

Upgrading between modes

If you installed a lighter mode and later want to move to a more capable one, flip the relevant tags and pass --reset-then-reuse-values. Any component overrides you previously set carry forward automatically.

📘

Note

Moving to node-autoscaler or full from a Helm-only mode requires completing the Terraform configuration first, since those modes need AWS IAM resources.

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

The shared components that were already running from the previous mode are patched in place with no pod restarts. Only the new components required by the target mode are created.

Next steps