Migrate standalone Helm charts with castctl

If your cluster was previously connected using individual Cast AI Helm releases (one chart per component), castctl cluster migrate consolidates them into the unified umbrella chart. This preserves your cluster's Cast AI ID, carries forward any custom Helm values you supplied, and installs only the components that were already running.

The command also handles clusters where the Cast AI agent was installed via raw kubectl apply rather than Helm.

The castai-agent namespace and any non-chart-owned resources (including the castai-agent-metadata ConfigMap that holds the cluster ID) are not deleted.

⚠️

Brief downtime during migration

The migration uninstalls all standalone Helm releases before installing the umbrella chart. Cast AI components are absent from the cluster during this window. Node Autoscaling and Workload Autoscaling are paused until the umbrella chart install completes.

Run the migration

1. Switch your kubeconfig to the cluster you want to migrate.

2. Run:

   Shell

   castctl cluster migrate

   castctl reads the currently installed standalone releases, captures their values, uninstalls them, and then installs the umbrella chart with the reconstructed configuration.

3. Review the confirmation prompt and proceed. Use --yes to skip the prompt in scripts or CI.

4. On success, castctl confirms that all components are running under the unified chart.

For the full list of flags, including version pinning and recovery options, see the castctl command reference.

If the umbrella install fails

When the umbrella chart installation fails (for example, because an immutable field on an existing Deployment cannot be patched), castctl rolls back what it can and writes the captured standalone release values to a local file:

! Preserved standalone release values written to castai-migrate-values-<timestamp>.yaml
  Pass this file to `castctl cluster migrate --values-file <path>` or
  `helm upgrade castai castai/castai -f <path>` to reapply the custom configuration.

A debug snapshot ZIP is also saved to help diagnose the failure.

Fix the underlying issue (for example, delete the conflicting Deployment and let Helm recreate it), then pass the saved values file to retry. In --values-file mode, castctl skips standalone detection and uninstall entirely, running only the umbrella chart installation:

castctl cluster migrate --values-file castai-migrate-values-<timestamp>.yaml

Alternatively, apply the values directly with Helm:

helm upgrade castai castai/castai -f castai-migrate-values-<timestamp>.yaml

The dump file contains a top-level releases: map with per-release values and the cluster ID, so both approaches restore the original configuration.

See also