Skip to content
🛥️🐳 KSail

Support Matrix

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

Distribution × Provider Matrix

Section titled “Distribution × Provider Matrix”
DistributionDockerHetznerOmniAWS
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
  • Hetzner provider requires HCLOUD_TOKEN environment variable and a Talos ISO uploaded to your Hetzner account (x86: 122630, ARM: 122629 — 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

Section titled “Component × Distribution Matrix”
ComponentVanillaK3sTalosVClusterKWOKEKS
CNI
Cilium✅✅✅N/A¹Sim⁷❌
Calico✅✅✅N/A¹Sim⁷❌
Amazon VPC CNI❌❌❌❌❌Built-in
CSI
Local Path Provisioner✅Built-in✅ (Docker)N/A²Sim⁷❌
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✅✅✅✅Sim⁷🚧¹⁰
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. The flux-operator pod is simulated by KWOK stages and appears Running, but it never registers Flux CRDs — Flux reconciliation is not functional. Use ArgoCD for GitOps workflows on KWOK.
  • ¹⁰ 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.

Secret Management × Provider Matrix

Section titled “Secret Management × Provider Matrix”
ProviderEncryptionDecryptionEdit
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

Section titled “CLI Commands”
Command GroupCommands Available
ksail clusterinit, create, update, delete, start, stop, info, list, connect, switch, backup, restore
ksail workloadapply, create, delete, describe, edit, exec, explain, export, expose, gen, get, images, import, install, logs, push, reconcile, rollout, scale, validate, wait, watch
ksail cipherencrypt, decrypt, edit, import

Update Behavior

Section titled “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).

ChangeVanilla (Kind)K3s (K3d)TalosVCluster (Vind)KWOK (kwokctl)EKS
DistributionRecreateRecreateRecreateRecreateRecreate🚧¹⁰
ProviderRecreateRecreateRecreateRecreateRecreate🚧¹⁰
CNIIn-placeIn-placeIn-placeN/ASim⁷🚧¹⁰
CSIN/A⁵In-placeIn-placeN/ASim⁷🚧¹⁰
Metrics ServerIn-placeIn-placeIn-placeN/ASim⁷🚧¹⁰
Load BalancerIn-placeIn-placeN/A¹N/ASim⁷🚧¹⁰
cert-managerIn-placeIn-placeIn-placeIn-placeSim⁷🚧¹⁰
Policy EngineIn-placeIn-placeIn-placeIn-place❌⁸🚧¹⁰
GitOps EngineIn-placeIn-placeIn-placeIn-placeSim⁷🚧¹⁰
Local RegistryRecreateIn-placeIn-placeIn-placeSim⁷❌
Mirrors DirRecreateN/AN/AN/AN/A❌
Control PlanesRecreateRecreateIn-placeRecreateRecreate🚧¹⁰
WorkersRecreateIn-placeIn-placeN/AN/A🚧¹⁰
Hetzner Server Type (CP)N/AN/ARecreateN/AN/AN/A
Hetzner LocationN/AN/ARecreateN/AN/AN/A
Hetzner NetworkN/AN/ARecreateN/AN/AN/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

Section titled “Platform Requirements”
RequirementMinimumRecommended
DockerDocker Desktop 4.x or Docker Engine 24.xLatest stable
RAM4 GB8 GB+
CPU2 cores4 cores+
Disk10 GB20 GB+

Operating System Support:

OSSupport
macOS (Apple Silicon)✅
Linux (x86_64)✅
Linux (arm64)✅
Windows (WSL2)✅
Windows (native)❌

Version Compatibility

Section titled “Version Compatibility”

KSail embeds specific versions of Kubernetes tooling:

ToolEmbedded VersionPurpose
kubectlLatestKubernetes CLI
Helmv4 (with kstatus)Package manager
KindLatestVanilla clusters
K3dLatestK3s clusters
vCluster SDKv0.33.1VCluster virtual clusters
kwokctlLatestKWOK simulated clusters
FluxLatestGitOps toolkit
ArgoCDLatestGitOps continuous delivery
SOPSLatestSecret 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