Connect your Kubernetes cluster to the Cast AI platform by deploying the Cast AI agent in your cluster. For GCP and AWS customers, we also offer an initial discovery option.

Prerequisites

Before connecting your cluster, ensure your environment meets the following requirements:

General Requirements

• curl command line utility installed
• kubectl command line utility installed
• Appropriate permissions to create resources in your cluster

EKS-Specific Requirements

⚠️

Critical for EKS Users

You must configure EC2 metadata service settings before installing the Cast AI agent to prevent deployment failures.

For Amazon EKS clusters, the Cast AI agent requires access to the EC2 metadata service to identify cluster properties. By default, EKS node groups have httpPutResponseHopLimit=1, which prevents pods from reaching the metadata service.

Required Configuration: Set http_put_response_hop_limit = 2

Choose one of the following methods to configure your EKS environment:

Method 1: For node groups with existing launch templates

If your node group already uses a launch template, create a new version with the correct metadata options:

aws ec2 create-launch-template-version \
    --launch-template-id lt-xxxxx \
    --version-description "Updated metadata options for Cast AI" \
    --launch-template-data '{
        "MetadataOptions": {
            "HttpPutResponseHopLimit": 2,
            "HttpTokens": "required"
        }
    }'

Then update your node group to use the new launch template version:

aws eks update-nodegroup-version \
    --cluster-name your-cluster-name \
    --nodegroup-name your-nodegroup-name \
    --launch-template id=lt-xxxxx,version=2

📘

Note

Replace version=2 with the actual version number returned by the create-launch-template-version command.

Method 2: For node groups without launch templates

📘

Need help with EKS configuration?

For detailed instructions on finding launch template IDs, creating launch templates, and managing EKS node groups, see the AWS EKS documentation.

For node groups that don't use launch templates, you'll need to create a new launch template and then create a new node group:

aws ec2 create-launch-template \
    --launch-template-name castai-nodegroup-template \
    --launch-template-data '{
        "MetadataOptions": {
            "HttpPutResponseHopLimit": 2,
            "HttpTokens": "required"
        }
    }'

⚠️

Important

You cannot directly update an existing node group that was created without a launch template to use one. You must create a new node group with the launch template and migrate your workloads.

Verification

After updating your configuration, verify that the metadata options are correctly set:

aws ec2 describe-launch-template-versions \
    --launch-template-id lt-xxxxx \
    --versions '$Latest'

Step 1: Log into the Cast AI console

Once logged in, you can see a button to connect a new Kubernetes cluster in the upper right corner. Click on this button.

If you're using GCP or AWS, you can use our Connect Cloud feature to discover your clusters before agent installation. Click on Connect Cloud in the navigation menu and run the provided script in your cloud shell. This will discover all your GKE/EKS clusters with basic information before you decide which ones to fully connect with the agent. See Getting starteddocumentation to learn more.

Step 2: Select your provider

Pick your managed Kubernetes service provider. You can choose from the following options:

• Amazon Elastic Kubernetes Service (EKS)
• Azure Kubernetes Service (AKS)
• Google Kubernetes Engine (GKE)
• Red Hat OpenShift service on AWS
• AWS Kops
• All Alternative Clouds (Cast AI Anywhere)

Pick your provider and click Next.

📘

AWS PrivateLink

For customers who wish to use Cast AI with EKS clusters that do not have direct internet access, we offer the Cast AI PrivateLink capability on AWS. Read more about it on our dedicated Github repository.

Step 3: Run the script

Open your cloud shell or terminal and run the provided script. Make sure that kubectl is installed, and it can access your cluster.

Copy the script and run it in your cloud shell or terminal.

📘

Note

Cast AI's read-only agent has no access to your sensitive data and doesn't change your cluster configuration. Read more about the security of our agent.

Once you're done, click I ran the script.

Step 4: Automated cluster connection

Cast AI will automatically connect your cluster to the platform.

Once that happens, you're ready to explore the platform and learn more about your cluster's cost performance.