Ensure the following tools are installed and accessible:

• kubectl (v1.19+) configured to access your cluster
  Install kubectl

• Helm (v3.0+) for deploying Cast AI components
  Install Helm

The onboarding script handles component installation via Helm automatically.

Your cluster must meet these requirements:

• Amazon EKS cluster with Karpenter version 0.32.0 or later installed and operational
• kubectl access with cluster-admin or equivalent permissions to create namespaces and deploy workloads
• Outbound internet access to api.cast.ai and grpc.cast.ai

The IAM principal running the onboarding script needs permissions to:

• Create IAM roles and policies
• Create instance profiles
• Manage EC2 security groups

For the minimal required permissions policy, see Cloud permissions.

If you don't have a Cast AI account, sign up here. The savings report and basic features are available on the free tier.

The onboarding script installs Cast AI components in the castai-agent namespace:

For more details, see Hosted components.

If you deselected features during connection, those cards will show an Install button instead of data. You can install them anytime:

1. Click Install on the feature card
2. Follow the installation prompts
3. The feature will appear as active once installation completes

The Get started page always reflects what's currently deployed in your cluster.

Cast AI analyzed your cluster after onboarding:

• Inventoried all Nodes, Pods, and workloads
• Measured actual CPU and memory usage
• Identified over-provisioned resources
• Compared your current instance types against more optimal alternatives
• Calculated potential consolidation opportunities

This analysis runs continuously, so the numbers stay current as your cluster changes.

Enable now if: You want fully automated, continuous optimization. Evictor runs safely in the background and only consolidates when it won't disrupt workloads.

Enable later if: You prefer to run Rebalancer manually first to see how Cast AI optimizes your cluster, then enable continuous consolidation once you're comfortable.

Either approach works—Rebalancer provides immediate, one-time optimization, while Evictor provides ongoing efficiency.

You'll see a Node overlays tab marked "Coming soon." Node overlays (a Karpenter 1.6+ feature) let clusters override scheduler decisions for special hardware, OS configs, or capacity types. Cast AI support for Node overlays is planned for a future release.

When you start rebalancing:

1. Cast AI creates new NodeClaims through Karpenter for the optimized instance types
2. Karpenter provisions the new nodes
3. Workloads are drained using standard Kubernetes eviction
4. Old nodes are deleted once empty

The entire process respects Pod Disruption Budgets and coordinates with Karpenter's native lifecycle management.

Currently, for Karpenter clusters, the Cast AI console may not show detailed progress during rebalancing. For full visibility, inspect the Rebalancing CRD directly:

kubectl get rebalancing -n castai-agent
kubectl describe rebalancing <name> -n castai-agent

The Rebalancing CRD contains:

• Current phase and stage
• Status messages
• Related events for each step
• Failure reasons if something goes wrong

This is the source of truth for rebalancing status.

If pods in the castai-agent namespace are not reaching Running status:

1. Check pod events:

   Bash

   kubectl describe pod -n castai-agent <pod-name>

2. Check component logs:

   Bash

   kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-agent

3. Verify IAM permissions were created correctly by the onboarding script.

If your cluster doesn't appear after running the script:

1. Verify the agent is running:

   Bash

   kubectl get pods -n castai-agent -l app.kubernetes.io/name=castai-agent

2. Check agent logs for connection errors:

   Bash

   kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-agent -c agent

3. Ensure your cluster has outbound internet access to api.cast.ai and grpc.cast.ai.

If Cast AI doesn't detect Karpenter in your cluster:

1. Verify Karpenter is installed:

   Bash

   kubectl get pods -n karpenter

2. Check that Karpenter CRDs exist:

   Bash

   kubectl get crd | grep karpenter

If Karpenter is installed but not detected, contact Cast AI support with your cluster details.

If rebalancing won't start or shows errors:

1. Verify the Kentroller component is running:

   Bash

   kubectl get pods -n castai-agent -l instance=castai-kentroller

2. Check Kentroller logs:

   Bash

   kubectl logs -n castai-agent -l instance=castai-kentroller

3. Ensure Karpenter is operational and able to provision nodes:

   Bash

   kubectl get nodeclaims

Rebalancing requires both Cast AI and Karpenter to be fully operational.

If NodeClaims remain in Waiting or Provisioning state for more than 10-15 minutes:

1. Check NodePool CPU limits—this commonly blocks scaling:

   Bash

   kubectl get nodepool -o yaml | grep -A5 "limits:"

2. Review instance family and generation constraints. Overly strict filters cause most capacity failures:

   Bash

   kubectl get nodepool -o yaml | grep -A10 "requirements:"

3. For Spot capacity, check if the requested instance types have availability in your region.

4. Inspect the NodeClaim for specific errors:

   Bash

   kubectl describe nodeclaim <nodeclaim-name>

If NodeClaims remain stuck after checking these, contact Cast AI support.

If Evictor isn't taking consolidation actions:

1. Verify Evictor is running with replica count of 1:

   Bash

   kubectl get deployment castai-evictor -n castai-agent -o jsonpath='{.spec.replicas}'

2. Check that Cast AI labels are applied correctly to nodes:

   Bash

   kubectl get nodes -l karpenter.sh/do-not-disrupt

3. Review Evictor logs for blocked evictions:

   Bash

   kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-evictor --tail=100

4. Check if Evictor shows zero disruptable nodes:

   Bash

   kubectl logs -n castai-agent -l app.kubernetes.io/name=castai-evictor | grep -i "disruptable"

Note: Evictor respects Karpenter's consolidateAfter setting. If your NodePool has a long consolidation window (e.g., 30 minutes), Evictor will wait accordingly before consolidating.

If the Spot interruption prediction model is enabled but no predictions appear during active Spot usage:

1. Verify the interruption queue is configured in your Karpenter deployment:

   Bash

   kubectl get deployment -n karpenter karpenter -o yaml | grep -i queue

2. Check that IAM permissions for SQS access are correctly configured.

3. Confirm the prediction model is enabled in Cast AI Settings.

4. Verify Kentroller is running and connected:

   Bash

   kubectl logs -n castai-agent -l instance=castai-kentroller --tail=50

If predictions still don't appear during active Spot usage, contact Cast AI support.

If rebalancing operations fail or appear stuck:

1. Check the Rebalancing CRD for status and failure reasons:

   Bash

   kubectl get rebalancing -n castai-agent
   kubectl describe rebalancing <name> -n castai-agent

2. Review Kentroller logs for detailed error information:

   Bash

   kubectl logs -n castai-agent -l instance=castai-kentroller --tail=200

The Rebalancing CRD contains:

• Current phase and stage (including failures)
• Human-readable failure reasons
• Related events for each step

This CRD is the source of truth for diagnosing rebalancing issues. The UI may not show detailed progress, but the CRD provides full visibility.

Escalate to Cast AI support if:

• Rebalance plans fail repeatedly with the same error
• NodeClaims created during rebalancing are stuck for more than 15 minutes
• Kentroller logs show persistent connection or API errors

If nodes are being replaced unexpectedly:

1. Check if Karpenter's drift detection triggered the replacement:

   Bash

   kubectl get nodeclaim -o yaml | grep -A5 "disruption"

2. Review if node expiration (expireAfter) is configured in your NodePool:

   Bash

   kubectl get nodepool -o yaml | grep -i expireafter

3. Check Karpenter controller logs for consolidation or drift events:

   Bash

   kubectl logs -n karpenter -l app.kubernetes.io/name=karpenter --tail=100 | grep -i "disruption\|drift\|consolidat"

Common causes of unexpected replacements:

• NodePool expireAfter setting triggering periodic node repaving
• Drift detection from AMI updates, security group changes, or label modifications
• Karpenter's native consolidation (if Evictor isn't marking nodes with do-not-disrupt)

If Workload Autoscaler is enabled but not showing recommendations:

1. Verify the Workload Autoscaler pod is running:

   Bash

   kubectl get pods -n castai-agent -l app=castai-workload-autoscaler

2. Check that metrics-server is installed and working:

   Bash

   kubectl top nodes
   kubectl top pods -A

3. Review Workload Autoscaler logs for errors:

   Bash

   kubectl logs -n castai-agent -l app=castai-workload-autoscaler

Workload Autoscaler requires metrics-server for resource usage data. The onboarding script installs it automatically if not present.