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”
Distribution Docker Kubernetes Hetzner Omni AWS GCP Azure
Vanilla (Kind) ✅ ✅ ❌ ❌ ❌ ❌ ❌
K3s (K3d) ✅ ✅ ❌ ❌ ❌ ❌ ❌
Talos ✅ ✅ ✅ ✅ ❌ ❌ ❌
VCluster (Vind) ✅ ✅ ❌ ❌ ❌ ❌ ❌
KWOK (kwokctl) ✅ ✅ ❌ ❌ ❌ ❌ ❌
EKS ❌ ❌ ❌ ❌ ✅¹⁰ ❌ ❌
GKE ❌ ❌ ❌ ❌ ❌ ✅¹³ ❌
AKS ❌ ❌ ❌ ❌ ❌ ❌ ✅¹⁴

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; cluster lifecycle (create/delete/start/stop/list/info) is supported via eksctl, and EKS’s managed CNI/CSI/LoadBalancer ship with the cluster. KSail-managed component installation and ksail cluster update for EKS are still in progress (the 🚧 cells below)
  • ¹³ GCP provider requires Application Default Credentials plus GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION — see GCP Provider for setup details; cluster lifecycle (create/delete/start/stop/list/info) is supported, and GKE’s managed CNI/CSI/LoadBalancer/metrics ship with the cluster
  • ¹⁴ Azure provider requires DefaultAzureCredential-resolvable credentials plus AZURE_SUBSCRIPTION_ID and AZURE_RESOURCE_GROUP — see Azure Provider for setup details; cluster lifecycle (create/delete/start/stop/list/info) is supported, and AKS’s managed CNI/CSI/LoadBalancer/metrics ship with the cluster
  • 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”
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: The EKS cluster lifecycle (create/delete/start/stop/list/info) is supported via eksctl, and ksail cluster update can apply node-group scaling changes in-place behind the experimental spec.cluster.eks.experimentalInPlaceUpdates opt-in (default: confirmation-gated recreate). Full KSail-managed component installer support (GitOps, security, and load-balancer add-ons beyond eksctl’s built-in VPC CNI / EBS CSI) is still in progress; the AWS Load Balancer Controller can be installed behind the experimental spec.cluster.eks.experimentalAWSLoadBalancerController opt-in together with loadBalancer: Enabled (IAM permissions and subnet tags are prerequisites KSail does not create; clusters following AWS’s IRSA setup can reuse their pre-created service account via spec.cluster.eks.awsLoadBalancerControllerServiceAccount). 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

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

Section titled “CLI Commands”

See the generated CLI Flags reference for the complete, always-current list of command groups, commands, and flags.

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

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

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

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