Skip to content

Cluster Provisioning

Create and manage local Kubernetes clusters with a single command. KSail:

Use --benchmark during cluster create or cluster update to show per-component install durations.

Terminal window
ksail cluster init --name my-cluster --distribution Vanilla --cni Cilium
ksail cluster create

The generated config files work directly with kind, k3d, talosctl, and vcluster — KSail is a superset.

Use --ttl to create a cluster that auto-destroys after a set duration. See Ephemeral Clusters for usage patterns and tips.

Terminal window
ksail cluster create --ttl 1h

ksail cluster update applies changes from ksail.yaml to a running cluster. Changes are classified as in-place (no disruption), reboot-required, recreate-required, or wipe-required. Use --dry-run to preview changes without applying them. Use --output json for a machine-readable diff in CI pipelines or MCP tools:

Terminal window
# Preview changes without applying
ksail cluster update --dry-run
# Machine-readable diff for CI gating or MCP consumption
ksail cluster update --dry-run --output json | jq .recreateRequired

ksail cluster diff compares the desired configuration in ksail.yaml against the live cluster state and reports any drift — without applying changes. Use it in CI pipelines or monitoring workflows to catch unintended drift early.

Terminal window
# Report drift in human-readable form
ksail cluster diff
# Machine-readable output for CI gating
ksail cluster diff --output json | jq .recreateRequired
# Return exit code 2 when drift is detected (useful for CI gate steps)
ksail cluster diff --exit-code

Changes are classified the same way as cluster update: in-place, reboot-required, recreate-required, or wipe-required. Unlike cluster update --dry-run, cluster diff is a pure read operation — it never applies or stages any changes.

When a cluster has 3 or more nodes (control planes + workers ≥ 3), KSail automatically applies HA-ready defaults to supported Helm-based component installers. Below the 3-node threshold, no HA values are injected to avoid unschedulable pods on single-node or dual-node clusters.

The possible HA settings are:

  • Replicas ≥ 2 — fast failover for controller workloads
  • PodDisruptionBudgetsminAvailable: 1 to prevent simultaneous evictions
  • Topology spread constraintsScheduleAnyway by hostname to distribute pods across nodes

Each component receives the subset of these settings it supports. The table below is the source of truth for which settings are applied per component:

ComponentHA Setting
cert-managercontroller + webhook replicas, PDB, topology spread
metrics-serverreplicas, PDB, topology spread
KyvernoadmissionController replicas, PDB, topology spread
Gatekeeperreplicas, PDB, topology spread
ArgoCDserver + repoServer replicas, PDB
Ciliumoperator replicas
CalicoTypha controlPlaneReplicas
kubelet-csr-approverreplicas
cluster-autoscalerreplicas
hcloud-ccmreplicaCount
hetzner-csicontroller replicaCount

When an external node autoscaler (such as Cluster Autoscaler, Karpenter, or Omni dynamic allocation) manages your node counts, set spec.cluster.autoscaler.node.enabled: true in ksail.yaml to prevent ksail cluster update from interfering.

By default (false), KSail reconciles spec.cluster.controlPlanes and spec.cluster.workers on every ksail cluster update. With autoscaling enabled, those diffs are skipped — the external autoscaler is the single source of truth for node counts. ksail cluster create is unaffected; initial node counts are still applied on first provision.

spec:
cluster:
autoscaler:
node:
enabled: true

Two flags let you upgrade a running cluster to the latest stable versions without editing config files:

  • --update-distribution — upgrades distributions that have a separate distribution image (for example, Talos) to the latest stable OCI image tag. This is a no-op for Vanilla (Kind) and K3s (K3d) since their distribution version is tied to the Kubernetes version.
  • --update-kubernetes — upgrades the Kubernetes control plane to the latest stable version. For Vanilla (Kind) and K3s (K3d), this also upgrades the distribution since both are bundled into a single image.
Terminal window
# Upgrade both distribution and Kubernetes at once
ksail cluster update --update-distribution --update-kubernetes

Upgrade strategy by distribution:

DistributionStrategyDetails
TalosRolling upgradeUpgrades nodes in-place via the Talos API — no downtime for multi-node clusters
Vanilla (Kind)RecreationCluster is deleted and recreated at the target version
K3s (K3d)RecreationCluster is deleted and recreated at the target version
VClusterRecreationCluster is deleted and recreated using KSail’s embedded vCluster/Kubernetes defaults; versions only advance when those defaults change (for example, after updating KSail)
KWOKNot supported--update-kubernetes and --update-distribution are not supported for KWOK; the controller image is pinned to the version bundled with KSail

For Talos (rolling upgrades), KSail steps through intermediate versions sequentially before reaching the final target. For recreation-based distributions, KSail skips intermediate versions and recreates the cluster once at the latest available target version. You will be prompted for confirmation before any recreation; pass --force or --yes (-y) to skip the prompt.

ksail cluster