Import and apply cluster configuration with castctl

castctl cluster import-config reads your cluster's node group configuration from your cloud provider and translates it into Cast AI node configurations and node templates. Nodes provisioned by Cast AI then match the ones they replace, with the same subnets, images, security groups, labels, and taints.

Discovery is read-only against your cloud account: it never modifies or deletes your existing node groups. The import only creates the corresponding objects inside Cast AI.

What gets imported

Each cloud node group backing your cluster is converted into:

• A node configuration: the cloud-level settings used to build instances (subnets, image, disk, security groups, network placement, and provider-specific options).
• A node template: the Kubernetes-level placement rules for the group, such as labels, custom taints, Spot/On-Demand capacity, CPU architecture, OS, GPU-only, and instance-family constraints. Templates that describe the same node group are merged into one, with their constraints combined.

What discovery reads and captures per provider:

How it works

1. castctl reads the node group configuration for the cluster from your cloud provider.
2. Each node group is translated into a node configuration and a node template.
3. You review the result and confirm. castctl creates whatever is missing in Cast AI, leaving any node configuration or node template that already exists untouched.

📘

Safe to re-run

The import only creates what's missing. It never updates, overwrites, or deletes existing node configurations or node templates in Cast AI.

Run the import

With your kubeconfig pointing at the connected cluster, run:

castctl cluster import-config

castctl detects the Cast AI cluster from your kubeconfig (or use --cluster-id to select it explicitly), runs discovery, prints a summary such as:

Based on your cluster config we will create 3 node configuration(s) and 4 node template(s).

and opens an interactive review where you can inspect the discovered settings before confirming the apply.

To import without any prompts (useful in CI):

castctl cluster import-config --non-interactive

For the full list of import-config flags, see the castctl command reference.

Import during connect

You can run the import as part of connecting the cluster, instead of as a separate step:

castctl cluster connect --import-config

After a successful connect, the existing cluster configuration is discovered and imported automatically. This needs the same cloud read credentials as standalone import-config (see Requirements); a connect can succeed while the import step still fails if those credentials are missing. If the import fails, the cluster stays connected. castctl prints a warning, and you can retry at any time with castctl cluster import-config. The import step is skipped when --dry-run is set.

See Connect using the castctl CLI for the full connect flow.

The plan file

With --file, the discovered plan is written to disk instead of being applied. This lets you review the full plan, check it into git, apply it later, or hand it to another team.

castctl cluster import-config --file plan.yaml

The file is a ClusterBootstrapPlan, a plain YAML document:

apiVersion: castctl.cast.ai/v1
kind: ClusterBootstrapPlan
metadata:
  clusterId: 741c0e8e-6b67-4d48-a52a-2a4cbb1e0f61
nodeConfigurations:
  - name: prod-cluster-general-4f2a
    subnets:
      - subnet-0a1b2c3d4e5f6a7b8
    minDiskSize: 50
    containerRuntime: containerd
    tags:
      team: platform
    eks:
      instanceProfileArn: arn:aws:iam::123456789012:instance-profile/cast-prod-cluster-eks-741c0e8e
      securityGroups:
        - sg-0123456789abcdef0
      imageFamily: FAMILY_AL2023
      volumeType: gp3
nodeTemplates:
  - name: prod-cluster-general-spot-4f2a
    ncName: prod-cluster-general-4f2a
    isDefault: true
    isEnabled: true
    labels:
      workload: general
    constraints:
      spot: true
      onDemand: true
      architectures:
        - amd64

The document contains:

• metadata.clusterId: the Cast AI cluster the plan belongs to.
• nodeConfigurations: shared fields (name, subnets, image, minDiskSize, tags, containerRuntime, initScript, kubeletConfig) plus exactly one provider block (eks, gke, or aks) holding the provider-specific settings listed in the table above.
• nodeTemplates: each template binds to a configuration via ncName and carries isDefault, isEnabled, shouldTaint, labels, customTaints, and scheduling constraints.

The example above is illustrative. Field names and values follow the plan schema; your file will contain your cluster's actual discovered settings.

Apply a plan from a file

To apply a plan that was written to a file earlier (for example, after reviewing or editing it, or on a different machine), use:

castctl cluster apply-config --file plan.yaml

apply-config validates the plan before applying it:

• apiVersion must be castctl.cast.ai/v1 and kind must be ClusterBootstrapPlan.
• metadata.clusterId must match the cluster the command runs against. A plan produced for one cluster cannot be applied to another.

Apply then creates the node configurations and node templates described in the file, skipping anything that already exists.

Export to Terraform

If you manage your cluster with the Cast AI Terraform provider, export the discovered plan as apply-ready Terraform instead of YAML:

castctl cluster import-config --file main.tf --output tf

The generated HCL declares the castai provider, a sensitive castai_api_token variable, and a cluster_id variable, and contains one castai_node_configuration resource per node configuration and one castai_node_template resource per node template. When the plan references objects that already exist in Cast AI, the file includes import blocks so Terraform adopts them into state instead of attempting to create duplicates.

Apply it with:

terraform init
terraform apply

terraform apply prompts for castai_api_token interactively unless you supply it another way. Avoid typing the raw token into a -var flag or an export command: both land in your shell history and process list. Instead, populate TF_VAR_castai_api_token from a source that doesn't echo the value, such as your secret manager's CLI:

export TF_VAR_castai_api_token="<value from your secret manager>"
terraform apply

In CI, set TF_VAR_castai_api_token as a pipeline secret rather than a shell command.

Requirements

• The cluster is already connected to Cast AI.
• kubectl is configured for the cluster (used to auto-detect the Cast AI cluster ID), or pass --cluster-id.
• Cloud credentials with read access to the node group inventory:
  • EKS: the default AWS credential chain (SSO, environment variables, or shared profile) for the account and region the cluster runs in.
  • GKE: Application Default Credentials (for example, gcloud auth application-default login).
  • AKS: Azure credentials (for example, az login).

import-config and apply-config are supported for EKS, GKE, and AKS clusters.

See also