Cluster Provisioning

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

• Supports Vanilla, K3s, Talos, VCluster, and KWOK distributions, with EKS scaffolding available
• 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.

The full lifecycle — create a real cluster, inspect it, deploy a workload, and tear it down:

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

Note

Flux Operator (single-replica with leader election), MetalLB controller (single-replica by design), and DaemonSet components are excluded — they are inherently HA or do not support replica scaling via Helm values.

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

Note

Other distributions currently ignore this setting; it is only active for Talos.

Version Upgrades

ksail cluster update reconciles the cluster’s distribution and Kubernetes versions declaratively on every run — there are no opt-in upgrade flags. Each version follows one of two rules:

• Unset → follow latest. When you do not declare a version, KSail upgrades toward the latest stable version available in the OCI registry.
• Set → pin. When you declare a version, KSail reconciles toward exactly that version (and never downgrades). Declare it in ksail.yaml (spec.cluster.kubernetesVersion and, for Talos, spec.cluster.talos.version) or per invocation with --kubernetes-version / --distribution-version. Precedence is flag > environment variable > config file > default.

# Follow the latest stable versions (nothing pinned)
ksail cluster update

# Pin a specific Kubernetes version for this run
ksail cluster update --kubernetes-version v1.34.0

# Pin the Talos OS version
ksail cluster update --distribution-version v1.13.3

The same fields apply at creation time: ksail cluster create provisions at the declared version, or at KSail’s built-in default (the latest version this KSail build supports) when unset.

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	KWOK has no version reconciliation; 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 target version. You will be prompted for confirmation before any recreation; pass --force or --yes (-y) to skip the prompt.

CLI Reference

ksail cluster

Related

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