Cluster Provisioning

Create and manage local Kubernetes clusters with a single command. KSail supports Vanilla, K3s, Talos, VCluster, and KWOK distributions, generates native configuration files (kind.yaml, k3d.yaml, Talos patches, vcluster.yaml, kwok.yaml) that work directly with upstream tools, and automatically configures CNI, CSI, metrics-server, cert-manager, and policy engines. Component installations use automatic retry with exponential backoff; the --benchmark flag shows per-component install durations during cluster create and cluster update.

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, or recreate-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

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

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

Related

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