Legacy onboarding script reference

The Cast AI console still offers this script as an option alongside castctl (see Connect using the Cast AI console) for environments where castctl isn't yet supported. It creates the cloud IAM permissions and installs the Kubernetes components Cast AI needs to manage nodes, not just monitor them.

If you connected with castctl instead, it creates largely the same IAM roles and components, automatically, in a single step. This page is still useful as a reference for what exists in your cloud account and cluster either way. The prerequisites below (jq, yq, helm, cloud CLIs) are specific to running the script manually: castctl bundles its own Helm logic and doesn't need any of them.

This script connects a cluster read-only. To turn on Node Autoscaling and/or Workload Autoscaling, run it again with those options selected once the read-only agent is up: the script checks for it and exits with an error if it's missing.

Get the script by clicking the Enable Cast AI button in the console, or via the API.

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 started to learn more.

The following sections describe the prerequisites for the legacy script for each supported cloud provider and the actions it performs. Turning automation on or off for an already-connected cluster is a separate policy setting, not something this script controls: see the Node Autoscaler checklist.

EKS

Prerequisites

• AWS CLI– a command-line tool for working with AWS services using commands in your command-line shell. For more details, see Installing AWS CLI.

• jq – a lightweight command-line JSON processor. For more details, see the jq documentation.

• yq - a lightweight command-line YAML processor. For more details, see yq.

• kubectl – a Kubernetes command-line tool that allows running commands against Kubernetes clusters. For more details, see kubectl.

• helm – a command-line tool that simplifies deploying applications and services to Kubernetes clusters. For more details, see helm.

• IAM permissions – the IAM security principal you're using must have permission to work with AWS EKS, AWS IAM, and related resources. Additionally, you should have access to the EKS cluster that you wish to onboard into the Cast AI console.

• The Cast AI agent must be running on the cluster. Learn more about Installing the Cast AI agent

Here's an example of a policy of least privilege for the administrator account, with permissions needed to run the onboarding script. This policy is used once per cluster during onboarding.

{
    "Action": [
        "iam:CreateRole",
        "iam:CreatePolicy",
        "iam:GetPolicy",
      	"iam:GetPolicyVersion",
        "iam:ListPolicies",
        "iam:ListPolicyVersions",
        "iam:PutRolePolicy",
        "iam:AttachRolePolicy",
        "iam:CreateInstanceProfile",
        "iam:GetInstanceProfile",
        "iam:AddRoleToInstanceProfile",
        "iam:UpdateAssumeRolePolicy",
        "ec2:CreateSecurityGroup",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:AuthorizeSecurityGroupIngress"
    ]
}

If you'd rather grant this up front than have the check warn about it, expand the list below for every permission the preflight check evaluates.

{
    "Action": [
        "iam:SimulatePrincipalPolicy",
        "iam:GetRole",
        "iam:GetOpenIDConnectProvider",
        "iam:ListAttachedRolePolicies",
        "iam:CreatePolicyVersion",
        "iam:DeletePolicyVersion",
        "iam:CreateServiceLinkedRole",
        "iam:PassRole",
        "sts:GetCallerIdentity",
        "eks:DescribeCluster",
        "eks:ListNodegroups",
        "eks:DescribeNodegroup",
        "eks:ListAccessEntries",
        "eks:CreateAccessEntry",
        "eks:AssociateAccessPolicy",
        "eks:DescribeAccessEntry",
        "ec2:DescribeSecurityGroups",
        "ec2:CreateTags",
        "ec2:DescribeLaunchTemplateVersions",
        "autoscaling:DescribeAutoScalingGroups"
    ]
}

Actions the onboarding script performs

The script performs the following actions:

1. Creates a cast-eks-*cluster-name*-cluster-role IAM role and a CastEKSPolicy policy, attaching the AWS-managed AmazonEC2ReadOnlyAccess and IAMReadOnlyAccess policies plus custom permissions to manage instances, Auto Scaling groups, and EKS node groups within the cluster's VPC. See Cloud permissions for the full policy.

2. Creates the following roles:

   • cast-*cluster-name*-eks-####### used by instance profile with the following AWS-managed permission policies applied by default:
     • AmazonEKSWorkerNodePolicy
     • AmazonEC2ContainerRegistryReadOnly
     • AmazonSSMManagedInstanceCore
     • AmazonEBSCSIDriverPolicy
     • AmazonEKS_CNI_Policy
     • AmazonEKS_CNI_IPv6_Policy or create CastEC2AssignIPv6Policy for IPv6 support
     • Role ARN is printed and sent to the Cast AI console. The platform then uses it to assume the role when making AWS programmatic calls.

3. Installs the Kubernetes components needed to manage the cluster. See Hosted components for the current, complete list.

Manual credential onboarding

You can complete the steps listed above manually without using the script. However, keep in mind that when you create an Amazon EKS cluster, the IAM entity user or role (e.g., a federated user that creates the cluster) automatically gets system:masters permissions in the cluster's RBAC configuration in the control plane.

To allow additional AWS users or roles to interact with your cluster, you need to edit the aws-auth ConfigMap in Kubernetes. For more information, see Managing users or IAM roles for your cluster.

Using AWS services

Cast AI relies on the agent running inside your cluster. The operation consumes the following services:

• A portion of the EC2 node resources from your cluster. The Cast AI agent uses the cluster proportional vertical autoscaler to consume the minimum required resources depending on the cluster size.
• Low amount of network traffic to communicate with the Cast AI SaaS.
• EC2 instances, their storage, and intra-cluster network traffic to manage the Kubernetes cluster and perform autoscaling.
• IAM resources as detailed in the onboarding section

You can find a full overview of permissions used by the Cast AI-created IAM role here.

GKE

Prerequisites

• gcloud – A command-line tool for working with GKE services using commands in your command-line shell. For more details, see Installing gcloud.

• jq – a lightweight command-line JSON processor. For more details, see the jq documentation.

• IAM permissions – The IAM security principal that you use to onboard the cluster must include:

  • Access to the project where the cluster is created.
  • Permission to work with IAM, GKE, and compute resources.

• kubectl – a Kubernetes command-line tool allowing commands to be run against Kubernetes clusters. For more details, see kubectl.

• helm – a command-line tool that simplifies the deployment of applications and services to Kubernetes clusters helm.

• The Cast AI agent has to be running on the cluster. Learn more about installing Cast AI agent

Here's an example of the least privileged permissions for the administrator account needed to run the onboarding script, used once per cluster during its onboarding:

- serviceusage.services.enable
- servicemanagement.services.bind
- container.clusters.get
- container.clusters.list
- iam.serviceAccounts.get
- iam.serviceAccounts.create
- iam.roles.get
- iam.roles.update
- iam.roles.create
- iam.serviceAccountKeys.create

Actions the onboarding script performs

The Phase 2 onboarding script performs several actions to get the permissions required to manage GKE and GCP resources on your behalf:

• Enables the necessary GCP services and APIs for the project.
• Creates the IAM service account and assigns the required roles to it.
• Generates an IAM service account key that Cast AI components use to manage GKE and GCP resources on your behalf.
• Enables the following GCP services and APIs for the project in which the GKE cluster is running:

• Creates a dedicated GCP service account castai-gke-<cluster-name-hash> for CAST AI to request and manage GCP resources on your behalf.

• Creates a custom role castai.gkeAccess. See Cloud permissions for the full permission list.

• Attaches required roles to the castai-gke-<cluster-name-hash> service account.

• Installs the Kubernetes components needed to manage the cluster. See Hosted components for the current, complete list.

For a full overview of permissions a Cast AI-created service account uses, see GCP cloud permissions.

GKE node pools created by Cast AI

After the cluster is onboarded, Cast AI will create two GKE node pools:

• castpool – gathers necessary data required for creating Cast AI-managed GKE x86 nodes.
• castpool-arm – collects the data required for creating Cast AI-managed GKE ARM64 nodes. It's created only if the cluster region supports ARM64 VMs.

AKS

Prerequisites

• az CLI – a command-line tool for working with Azure services using commands in your command-line shell. For more details, see Installing az CLI.

• jq – a lightweight command-line JSON processor. For more details, see the jq documentation.

• Azure AD permissions – the Azure identity that you use to onboard the cluster must include:

  • Access to the subscription where the cluster was created.
  • Permission to work with AKS and compute resources.
  • Permission to create an App registration.

• kubectl – a Kubernetes command-line tool that allows running commands against Kubernetes clusters. For more details, see kubectl.

• helm – a command-line tool that simplifies the deployment of applications and services to Kubernetes clusters helm.

• The Cast AI agent has to be running on the cluster. Learn more about Installing Cast AI agent

Actions the onboarding script performs

The script performs the following actions:

• Create a CastAKSRole-${CASTAI_CLUSTER_ID:0:8} role to manage onboarded AKS Cluster.

• Create an app registration CAST.AI ${CLUSTER_NAME}-${CASTAI_CLUSTER_ID:0:8}" that uses the role CastAKSRole-${CASTAI_CLUSTER_ID:0:8}.

• Installs the Kubernetes components needed to manage the cluster. See Hosted components for the current, complete list.

For a full overview of permissions used by Cast AI-created service accounts, see Azure cloud permissions.

Azure agent pools created by Cast AI

After the cluster is onboarded, Cast AI will create two AKS agent pools:

• castpool– is used to schedule a node required for Cast AI AKS image creation. Cast AI AKS images are re-created after every AKS control plane upgrade or every 30 days. While the image creation process is in progress, the castpool node with the name aks-castpool-xxxxxxxx-vmssxxxxxx can be seen in the "Not Ready" state for some time.
• castworkers– is used as a container for Cast AI-managed AKS nodes. Removing this agent pool results in removing all Cast AI-created nodes.

Azure CNI Overlay support

Cast AI fully supports AKS clusters that use Azure CNI Overlay networking with Pod CIDR. Autoscaling decisions fully respect IP address limitations when adding nodes.