Connecting your cluster
Choose how to connect your Kubernetes cluster to Cast AI: using castctl, the web console, or Terraform.
Cast AI supports several ways to connect a Kubernetes cluster. Pick the method that fits your workflow.
Choose your method
A single command from your terminal that auto-detects the cluster, walks you through feature selection, and handles the install. Supports EKS, GKE, and AKS.
Start the connection flow from the web console. Also supports agentless cluster discovery with Cloud Connect. Works for EKS, GKE, AKS, OpenShift, kOps, and Cast AI Anywhere clusters.
You can also connect clusters as code with the Cast AI Terraform provider.
Before you start
Whichever method you pick, make sure you have:
- A Cast AI account (sign up).
- A Kubernetes cluster on a supported, compatible provider. See Cluster compatibility below.
kubectlconfigured with admin access to the cluster you want to connect.- Cloud-side permissions required for the connection. See Cloud permissions.
Cluster compatibility
Cast AI automation takes over node lifecycle management from your cluster. For this to work, Cast AI must be the sole autoscaler: running it alongside another node autoscaler (such as Kubernetes Cluster Autoscaler) will cause conflicts and unpredictable scaling behavior.
Compatible cluster types are those where you can remove any existing node autoscaler before enabling Cast AI:
- Standard GKE clusters
- Amazon EKS with self-managed or managed node groups
Not compatible are fully managed cluster modes where the cloud provider controls node provisioning, and the autoscaler cannot be removed or replaced:
- GKE Autopilot
- Amazon EKS Auto Mode
- Amazon EKS Fargate
- Azure AKS Automatic
- Clusters running Kubernetes Cluster Autoscaler
For managed servicesIf you're using GKE Autopilot, EKS Auto Mode, EKS Fargate, or AKS Automatic, you can still benefit from Cast AI's workload optimization and cost monitoring through Cast AI Anywhere. This provides workload autoscaling and resource optimization without requiring cluster-level node management permissions.
Network connectivity
If your cluster runs in a private network without direct internet access, use one of the dedicated connectivity guides before connecting:
- AWS PrivateLink for EKS clusters without internet access.
- GCP Private Service Connect for private GKE clusters.
What happens after connection
Once your cluster is connected, see the Legacy onboarding script reference for the cloud IAM permissions and Kubernetes components Cast AI creates so it can manage nodes. castctl and the console's script option both create largely the same things: castctl just does it automatically instead of you running the script yourself.
Two common follow-up scenarios, both handled by castctl:
- To translate your existing node group configuration into Cast AI node configurations and node templates, run castctl cluster import-config right after connecting.
- If the cluster was connected a while ago using individual Cast AI Helm releases rather than the umbrella chart, run castctl cluster migrate to consolidate them. Releases managed by ArgoCD, Flux, or Terraform should use the phased GitOps and IaC migration flow instead. Clusters connected with the Cast AI Terraform cluster modules migrate through the module itself: see the module umbrella migration guide.
See also
Updated 19 days ago