Cluster Provisioning

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

Supports Vanilla, K3s, Talos, VCluster, and KWOK distributions
Generates native config files (kind.yaml, k3d.yaml, Talos patches, vcluster.yaml, kwok/) that work directly with upstream tools
Auto-configures CNI, CSI, metrics-server, cert-manager, and policy engines with automatic retry and exponential backoff

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

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.

Ephemeral Clusters

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

ksail cluster create --ttl 1h

Updating Clusters

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:

# 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

Drift Detection

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.

# 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.

High Availability Component Defaults

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
PodDisruptionBudgets — minAvailable: 1 to prevent simultaneous evictions
Topology spread constraints — ScheduleAnyway 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:

Component	HA Setting
cert-manager	controller + webhook replicas, PDB, topology spread
metrics-server	replicas, PDB, topology spread
Kyverno	admissionController replicas, PDB, topology spread
Gatekeeper	replicas, PDB, topology spread
ArgoCD	server + repoServer replicas, PDB
Cilium	operator replicas
Calico	Typha controlPlaneReplicas
kubelet-csr-approver	replicas
cluster-autoscaler	replicas
hcloud-ccm	replicaCount
hetzner-csi	controller replicaCount

Node Autoscaling

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

Version Upgrades

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.

# Upgrade both distribution and Kubernetes at once
ksail cluster update --update-distribution --update-kubernetes

Upgrade strategy by distribution:

Distribution	Strategy	Details
Talos	Rolling upgrade	Upgrades nodes in-place via the Talos API — no downtime for multi-node clusters
Vanilla (Kind)	Recreation	Cluster is deleted and recreated at the target version
K3s (K3d)	Recreation	Cluster is deleted and recreated at the target version
VCluster	Recreation	Cluster is deleted and recreated using KSail’s embedded vCluster/Kubernetes defaults; versions only advance when those defaults change (for example, after updating KSail)
KWOK	Not 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.

CLI Reference

ksail cluster

Declarative Configuration — ksail.yaml reference
Distributions — distribution-specific setup
Multi-Environment Workflows — manage dev/staging/prod from one project