Support Matrix

KSail supports multiple Kubernetes distributions, providers, and components. This matrix shows compatibility and support status.

Distribution × Provider Matrix

| Distribution | Docker | Kubernetes | Hetzner | Omni | AWS | | ---------------- | ------ | ---------- | ------- | ---- | ----- | | Vanilla (Kind) | ✅ | ✅ | ❌ | ❌ | ❌ | | K3s (K3d) | ✅ | ✅ | ❌ | ❌ | ❌ | | Talos | ✅ | ✅ | ✅ | ✅ | ❌ | | VCluster (Vind) | ✅ | ✅ | ❌ | ❌ | ❌ | | KWOK (kwokctl) | ✅ | ✅ | ❌ | ❌ | ❌ | | EKS | ❌ | ❌ | ❌ | ❌ | 🚧¹⁰ |

Notes:

Docker provider requires Docker Desktop or Docker Engine installed locally — see Docker Provider for setup details
Kubernetes provider runs nested cluster nodes as pods inside an existing host Kubernetes cluster — no Docker daemon required on the host; see Kubernetes Provider for setup details
Hetzner provider requires HCLOUD_TOKEN environment variable and a Talos ISO uploaded to your Hetzner account (x86: 125127 for Talos 1.12.4; for ARM, look up the matching ISO ID in the Hetzner Cloud Console — see Talos options) — see Hetzner Provider for setup details
Omni provider requires a Sidero Omni account, an OMNI_SERVICE_ACCOUNT_KEY environment variable, and an Omni API endpoint configured via spec.provider.omni.endpoint in your KSail configuration — see Omni Provider for setup details
¹⁰ AWS provider requires AWS credentials and an AWS account with EKS permissions — see AWS Provider for setup details; ksail cluster create is not yet functional for EKS
VCluster uses the Vind Docker driver to run the control plane and optional worker nodes directly as Docker containers
KWOK uses the kwokctl Docker runtime to run etcd, kube-apiserver, and kwok-controller as Docker containers — nodes and pods are simulated at the API level

Component × Distribution Matrix

| Component | Vanilla | K3s | Talos | VCluster | KWOK | EKS | | ----------------------------- | ------- | -------- | ------------------- | -------- | -------- | ---------------- | | CNI | | Cilium | ✅ | ✅ | ✅ | N/A¹ | ❌¹¹ | ❌ | | Calico | ✅ | ✅ | ✅ | N/A¹ | ❌¹¹ | ❌ | | Amazon VPC CNI | ❌ | ❌ | ❌ | ❌ | ❌ | Built-in | | CSI | | Local Path Provisioner | ✅ | Built-in | ✅ (Docker) | N/A² | ❌¹² | ❌ | | Hetzner CSI Driver | ❌ | ❌ | ✅ (Hetzner) | ❌ | ❌ | ❌ | | Amazon EBS CSI Driver | ❌ | ❌ | ❌ | ❌ | ❌ | Built-in | | LoadBalancer | | LoadBalancer Support | ✅ | Built-in | ✅ (Docker/Hetzner) | N/A³ | Sim⁷ | Built-in | | Cloud Provider KIND | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | MetalLB | ❌ | ❌ | ✅ (Docker) | ❌ | ❌ | ❌ | | Hetzner CCM | ❌ | ❌ | ✅ (Hetzner) | ❌ | ❌ | ❌ | | AWS Load Balancer Controller | ❌ | ❌ | ❌ | ❌ | ❌ | 🚧¹⁰ | | GitOps | | Flux | ✅ | ✅ | ✅ | ✅ | ❌⁹ | 🚧¹⁰ | | ArgoCD | ✅ | ✅ | ✅ | ✅ | Sim⁷ | 🚧¹⁰ | | Observability | | Metrics Server | ✅ | Built-in | ✅ | N/A⁴ | Sim⁷ | 🚧¹⁰ | | Security | | cert-manager | ✅ | ✅ | ✅ | ✅ | ❌¹² | 🚧¹⁰ | | Kyverno | ✅ | ✅ | ✅ | ✅ | ❌⁸ | 🚧¹⁰ | | Gatekeeper | ✅ | ✅ | ✅ | ✅ | ❌⁸ | 🚧¹⁰ | | Registry | | Local Registry | ✅ | ✅ | ✅ | ✅ | Sim⁷ | ❌ | | Mirror Registries | ✅ | ✅ | ✅ | ✅ | Sim⁷ | ❌ | | External Registries with Auth | ✅ | ✅ | ✅ | ✅ | Sim⁷ | 🚧¹⁰ | | Image Verification | | Image Verification | ✅⁶ | ❌ | ✅ (1.13+) | ❌ | ❌ | ❌ |

Notes:

"Built-in" means the distribution includes this component by default
K3s includes local-path-provisioner, metrics-server, and ServiceLB (load balancer) out of the box
Talos CSI support is provider-dependent: Local Path Provisioner for Docker, Hetzner CSI Driver for Hetzner Cloud
LoadBalancer support by distribution — see LoadBalancer Configuration for full details:
- Vanilla (Kind) on Docker: Uses cloud-provider-kind (runs as external Docker container)
- K3s on Docker: Uses built-in ServiceLB (Klipper-LB)
- Talos on Docker: Uses MetalLB with default IP pool (172.18.255.200-172.18.255.250)
- Talos on Hetzner: Uses Hetzner Cloud Load Balancer (cloud provider integration)
VCluster footnotes:
- ¹ CNI is managed internally by the vCluster control plane — Vind configures networking within the Docker containers
- ² CSI is managed internally by vCluster — no separate CSI driver needed
- ³ LoadBalancer is delegated to the host cluster by vCluster — spec.cluster.loadBalancer has no effect on VCluster and KSail does not install any LoadBalancer controller
- ⁴ Metrics Server is managed internally by vCluster
⁷ KWOK Simulation: Components are installed as API objects and their pods appear Running via KWOK's Stage simulation. They do not execute real workloads — KWOK simulates pod lifecycle at the API level. See KWOK Distribution for details.
⁸ KWOK Policy Engines: Kyverno and Gatekeeper are not installed on KWOK. Both register global MutatingWebhookConfigurations that intercept all Kubernetes API requests. On KWOK, no real pod serves the webhook endpoint, so every webhook call times out — breaking all subsequent Helm installs. KSail silently skips policy engine installation when spec.cluster.distribution: KWOK is set and emits a warning at cluster creation time.
⁹ KWOK Flux: Flux is not installed on KWOK. KSail skips Flux installation and configuration entirely (with a warning) because Flux cannot function on KWOK. GitOps reconciliation is not functional on KWOK, including with ArgoCD, because controller pods are only simulated and cannot sync resources. Use a non-KWOK distribution for real GitOps syncing, or use ksail workload apply on KWOK for non-GitOps manifest application.
¹⁰ EKS (Planned): Full component installer support for EKS is in progress. ksail cluster init is available, but ksail cluster create is not yet functional. See EKS Distribution for details.
¹¹ KWOK CNI: Cilium and Calico are not installed on KWOK. KWOK runs simulated pods with no real network dataplane, so CNI plugins are never functional and are always skipped. If a non-default CNI is configured in ksail.yaml for a KWOK cluster, KSail emits a warning and skips installation. The spec.cluster.cni setting has no effect on KWOK clusters.
¹² KWOK CSI and cert-manager: Local Path Provisioner (CSI) and cert-manager are not installed on KWOK. The Local Path Provisioner Deployment pod and cert-manager webhook pods require real container processes that KWOK does not provide, so readiness never becomes true and installation would time out. KSail skips installation of these components when spec.cluster.distribution: KWOK is set and emits a warning at cluster creation time.

Secret Management × Provider Matrix

| Provider | Encryption | Decryption | Edit | | --------------- | ---------- | ---------- | ---- | | age | ✅ | ✅ | ✅ | | PGP | ✅ | ✅ | ✅ | | AWS KMS | ✅ | ✅ | ✅ | | GCP KMS | ✅ | ✅ | ✅ | | Azure Key Vault | ✅ | ✅ | ✅ | | HashiCorp Vault | ✅ | ✅ | ✅ |

Notes:

Cloud KMS providers require appropriate credentials configured
See SOPS documentation for provider-specific setup

CLI Commands

| Command Group | Commands Available | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ksail cluster | init, create, update, delete, start, stop, info, list, connect, switch, backup, restore | | ksail workload | apply, create, delete, describe, edit, exec, explain, export, expose, gen, get, images, import, install, logs, push, reconcile, rollout, scale, validate, wait, watch | | ksail cipher | encrypt, decrypt, edit, import |

Update Behavior

The ksail cluster update command applies configuration changes to a running cluster. Changes are classified by impact: in-place (no disruption), reboot-required (node restart needed), or recreate-required (full cluster recreation).

| Change | Vanilla (Kind) | K3s (K3d) | Talos | VCluster (Vind) | KWOK (kwokctl) | EKS | | ------------------------ | -------------- | --------- | -------- | --------------- | -------------- | ---------- | | Distribution | Recreate | Recreate | Recreate | Recreate | Recreate | 🚧¹⁰ | | Provider | Recreate | Recreate | Recreate | Recreate | Recreate | 🚧¹⁰ | | CNI | In-place | In-place | In-place | N/A | N/A¹¹ | 🚧¹⁰ | | CSI | N/A⁵ | In-place | In-place | N/A | ❌¹² | 🚧¹⁰ | | Metrics Server | In-place | In-place | In-place | N/A | Sim⁷ | 🚧¹⁰ | | Load Balancer | In-place | In-place | N/A¹ | N/A | Sim⁷ | 🚧¹⁰ | | cert-manager | In-place | In-place | In-place | In-place | ❌¹² | 🚧¹⁰ | | Policy Engine | In-place | In-place | In-place | In-place | ❌⁸ | 🚧¹⁰ | | GitOps Engine | In-place | In-place | In-place | In-place | Sim⁷ | 🚧¹⁰ | | Local Registry | Recreate | In-place | In-place | In-place | Sim⁷ | ❌ | | Mirrors Dir | Recreate | N/A | N/A | N/A | N/A | ❌ | | Control Planes | Recreate | Recreate | In-place | Recreate | Recreate | 🚧¹⁰ | | Workers | Recreate | In-place | In-place | N/A | N/A | 🚧¹⁰ | | Hetzner Server Type (CP) | N/A | N/A | Recreate | N/A | N/A | N/A | | Hetzner Location | N/A | N/A | Recreate | N/A | N/A | N/A | | Hetzner Network | N/A | N/A | Recreate | N/A | N/A | N/A |

Notes:

"In-place" changes are applied without cluster downtime via Helm or provider APIs
"Recreate" changes trigger a cluster recreation. ksail cluster update will prompt before proceeding; use --force (or -y / --yes) to skip the prompt for non-interactive runs, or run ksail cluster delete && ksail cluster create manually.
If no changes are detected, ksail cluster update exits immediately with no modifications (idempotent no-op)
Use ksail cluster update --dry-run to preview changes before applying; add --output json for machine-readable diff output (suitable for CI gating or MCP tools)
Talos supports the broadest set of in-place updates, including node scaling for both control-plane and worker nodes across all providers — including Omni (via declarative cluster template sync)
Kind does not support any structural node changes after creation
VCluster (Vind) runs control-plane and optional worker nodes as Docker containers — CNI, CSI, and metrics-server are managed by the vCluster Helm chart and are N/A for update operations; LoadBalancer services are provided by the host cluster, and spec.cluster.loadBalancer is ignored for VCluster and will not trigger a cluster update
¹ Load Balancer for Talos: For Talos, the provider determines which LoadBalancer implementation is used (MetalLB on Docker, Hetzner Cloud Controller Manager on Hetzner). The spec.cluster.loadBalancer setting controls whether KSail installs LoadBalancer support. See FAQ for details.
⁵ CSI for Vanilla (Kind): Kind bundles local-path-provisioner by default. KSail's detector reports it as CSIEnabled but cannot distinguish Kind's bundled CSI from a KSail-installed CSI driver, so CSI comparison is skipped entirely during ksail cluster update. To change CSI settings on a Vanilla cluster, recreate it with ksail cluster delete && ksail cluster create.
⁶ Image Verification for Vanilla (Kind): Uses the containerd io.containerd.image-verifier.v1.bindir plugin (requires containerd 2.x / Kind v0.31.0+ / kindest/node:v1.35.1+). Verifier binaries (e.g., Cosign, Notation) must be pre-installed in a custom Kind node image at /opt/image-verifier/bin. See Vanilla Image Verification.

Platform Requirements

| Requirement | Minimum | Recommended | | ----------- | ---------------------------------------- | ------------- | | Docker | Docker Desktop 4.x or Docker Engine 24.x | Latest stable | | RAM | 4 GB | 8 GB+ | | CPU | 2 cores | 4 cores+ | | Disk | 10 GB | 20 GB+ |

Operating System Support:

| OS | Support | | --------------------- | ------- | | macOS (Apple Silicon) | ✅ | | Linux (x86_64) | ✅ | | Linux (arm64) | ✅ | | Windows (WSL2) | ✅ | | Windows (native) | ❌ |

Version Compatibility

KSail embeds specific versions of Kubernetes tooling:

| Tool | Embedded Version | Purpose | | ------------ | ----------------- | -------------------------- | | kubectl | Latest | Kubernetes CLI | | Helm | v4 (with kstatus) | Package manager | | Kind | Latest | Vanilla clusters | | K3d | Latest | K3s clusters | | vCluster SDK | v0.34.0 | VCluster virtual clusters | | kwokctl | Latest | KWOK simulated clusters | | Flux | Latest | GitOps toolkit | | ArgoCD | Latest | GitOps continuous delivery | | SOPS | Latest | Secret encryption |

Notes:

Kubernetes versions depend on the distribution release
Component versions (CNI, CSI, etc.) are updated with KSail releases
See releases for specific version information