Docs
  1. Introducing Cast AI
  2. Connecting your cluster

Connect using the Cast AI console

The Cast AI console guides you through connecting a cluster. When you start the connection flow in the console, you can choose between two options: castctl commands (recommended) or the legacy onboarding script.

Connect with castctl (recommended)

The console shows the castctl commands to run in your terminal. This is the fastest path and the same flow described in detail on the Connect using the castctl CLI page.

In summary:

  1. Log in to the Cast AI console and click Connect cluster.

  2. Select your operating system.

  3. Copy and run the commands shown in the console:

    castctl auth login
castctl cluster connect

  4. Follow the interactive prompts in your terminal.

  5. Once the connection completes, your cluster appears in the console.

For the full walkthrough — including installation, non-interactive mode, and all available options — see Connect using the castctl CLI.

Connect with the onboarding script (deprecated)

⚠️

Deprecated

The script-based connection flow is deprecated. Use castctl for new cluster connections. The script remains available for environments where castctl is not yet supported.

Prerequisites

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

General requirements

  • curl command line utility installed
  • kubectl command line utility installed
  • jq command line utility installed
  • yq command line utility installed
  • helm 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:

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.

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.

On the bottom click Switch to legacy script.

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
  • 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

Select the Script tab, then open your cloud shell or terminal and run the provided script. Make sure that kubectl is installed and 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.

See also

Updated 1 day ago

What’s Next