Concepts
Native Configuration Philosophy
Section titled “Native Configuration Philosophy”KSail is a superset, not a replacement. KSail works with native distribution configurations rather than creating proprietary formats. When you run ksail cluster init, KSail generates standard configuration files: kind.yaml (Kind) for Vanilla, k3d.yaml (K3d) for K3s, talos/ patches (Talos), vcluster.yaml (vCluster) for VCluster, and kwok/ (KWOK) for KWOK.
No vendor lock-in: These files work directly with underlying tools without KSail, providing freedom to migrate, use native CLI tools alongside KSail, and maintain team flexibility. Your configurations match official documentation and remain valid even if you stop using KSail.
Unified workflow: KSail provides consistent commands (cluster init, create, update, delete) across all distributions, making it easy to switch between Kubernetes flavors or work on multiple projects.
Kubernetes
Section titled “Kubernetes”Kubernetes is an open-source container orchestration platform for automating deployment, scaling, and management of containerized applications. See documentation, concepts, and kubectl reference.
Distributions
Section titled “Distributions”Kubernetes distributions package core components with additional tooling for specific use cases. KSail supports five distributions: Vanilla, K3s, Talos, VCluster, and KWOK. All can run on Docker; Talos can also run on Hetzner Cloud and Sidero Omni.
Vanilla (Kind)
Section titled “Vanilla (Kind)”Vanilla uses Kind to run standard upstream Kubernetes in Docker containers, ideal for testing against unmodified Kubernetes behavior. See documentation, configuration, and quick start.
K3s (K3d)
Section titled “K3s (K3d)”K3s is a lightweight, certified Kubernetes distribution for resource-constrained environments. KSail uses K3d to run K3s clusters in Docker with embedded load balancer, storage, and metrics. See K3s docs, K3d docs, and configuration.
Talos Linux is a minimal, immutable OS designed for Kubernetes with API-driven configuration and no shell access for enhanced security. See documentation, configuration reference, and getting started.
vCluster (Vind)
Section titled “vCluster (Vind)”vCluster creates virtual Kubernetes clusters. KSail uses the Vind Docker driver to run control plane and optional workers as containers, requiring only Docker. This enables fast creation with a small footprint. See documentation, configuration, and Vind driver.
KWOK (kwokctl)
Section titled “KWOK (kwokctl)”KWOK (Kubernetes WithOut Kubelet) creates simulated Kubernetes clusters where nodes and pods exist at the API level without running real containers. KSail uses kwokctl's Docker runtime to run etcd, kube-apiserver, and the kwok-controller as Docker containers. Ideal for control-plane testing, CI/CD speed optimization, and scale testing. See documentation, user guide, and GitHub.
Providers
Section titled “Providers”Providers are infrastructure backends that run cluster nodes. KSail abstracts provider-specific operations for consistent workflows.
Docker
Section titled “Docker”Runs Kubernetes nodes as Docker containers locally. Default provider for all distributions, requires only Docker. Supported distributions: Vanilla, K3s, Talos, VCluster, KWOK. See Docker Provider, Docker docs, and Docker Desktop.
Hetzner
Section titled “Hetzner”Creates nodes as Hetzner Cloud servers for production-grade clusters. Supported distributions: Talos. Requirements: HCLOUD_TOKEN environment variable and Talos ISO. See Hetzner Provider, Hetzner Cloud docs, API, and Talos on Hetzner.
Kubernetes (Nested)
Section titled “Kubernetes (Nested)”Runs nested cluster nodes as pods inside an existing host Kubernetes cluster. No Docker daemon is required on the host machine — the nested cluster's API server is exposed via Gateway API (TCPRoute), LoadBalancer, or NodePort, making it routable after ksail exits. Supported distributions: Vanilla, K3s, Talos, VCluster, KWOK. See Kubernetes Provider.
Manages Talos clusters through the Sidero Omni SaaS API. Supported distributions: Talos. Requirements: a Sidero Omni account, a service account key, and an Omni API endpoint. See Omni Provider, Omni docs, and Talos on Omni.
Container Network Interface (CNI)
Section titled “Container Network Interface (CNI)”CNI is a specification for configuring network interfaces in Linux containers, providing pod networking, policies, and observability.
Cilium
Section titled “Cilium”Cilium is an eBPF-based CNI offering networking, security, and observability with features like transparent encryption and service mesh.
KSail-specific configuration:
- Gateway API is enabled by default (
gatewayAPI.enabled: true); experimental Gateway API CRDs are pre-installed automatically - Without a LoadBalancer (Docker-based): host network mode (
gatewayAPI.hostNetwork.enabled: true) routes traffic via the Docker bridge using port mappings - With a LoadBalancer (e.g. Cloud Provider KIND for Vanilla, MetalLB for Talos on Docker, or
hcloud-cloud-controller-managerfor Talos on Hetzner): host network mode is skipped; traffic flows via LoadBalancer external IPs
See documentation, Gateway API guide, and Gateway API with KSail.
Calico
Section titled “Calico”Calico provides networking and network security with strong policy enforcement. See documentation, network policy, and getting started.
Container Storage Interface (CSI)
Section titled “Container Storage Interface (CSI)”CSI is a standard for exposing storage systems to containerized workloads, providing persistent storage for stateful applications.
Local Path Provisioner
Section titled “Local Path Provisioner”Local Path Provisioner creates PersistentVolumes using local storage on nodes, suitable for development and single-node clusters. See GitHub, persistent volumes, and storage classes.
Metrics Server
Section titled “Metrics Server”Metrics Server collects resource metrics from kubelets and exposes them via the Kubernetes API, required for HPA and kubectl top. See GitHub, resource metrics pipeline, and HPA.
Kubelet CSR Approver
Section titled “Kubelet CSR Approver”KSail automatically approves Certificate Signing Requests (CSRs) for kubelet serving certificates when metrics-server is enabled. When serverTLSBootstrap: true is active, kubelets request proper TLS certificates via CSR instead of self-signed certificates, enabling secure TLS communication with metrics-server. KSail handles this automatically using a distribution-appropriate implementation.
See TLS bootstrapping and CSRs.
cert-manager
Section titled “cert-manager”cert-manager automates TLS certificate management in Kubernetes, supporting ACME (Let's Encrypt), self-signed, and external CA certificates. See documentation, concepts, and issuer types.
Policy Engines
Section titled “Policy Engines”Policy engines enforce security, compliance, and best practices through admission control and continuous validation.
Kyverno
Section titled “Kyverno”Kyverno is a Kubernetes-native policy engine with policies written as YAML resources without new languages. See documentation, policies, and policy reports.
Gatekeeper
Section titled “Gatekeeper”OPA Gatekeeper brings Open Policy Agent to Kubernetes with policies in Rego. See Gatekeeper docs, OPA docs, and library.
OCI Registries
Section titled “OCI Registries”OCI Distribution defines a standard for storing and distributing container images and artifacts. See specification, Docker Registry, and OCI Artifacts.
GitOps
Section titled “GitOps”GitOps uses Git as the single source of truth for declarative infrastructure and applications.
Flux keeps clusters in sync with configuration in Git or OCI registries. See documentation, concepts, and FluxInstance CRD.
ArgoCD
Section titled “ArgoCD”Argo CD provides declarative GitOps with a web UI for visualizing application state. See documentation, concepts, Application CRD, and ArgoCD ApplicationSet guide.
SOPS (Secrets OPerationS) edits encrypted files with multiple key management backends. See documentation, age encryption, and SOPS with Flux.
Key Management Systems
Section titled “Key Management Systems”| Provider | Documentation | | --------------- | ----------------------------------------------------------------------------------- | | age | age-encryption.org | | PGP | GnuPG | | AWS KMS | AWS KMS | | GCP KMS | Cloud KMS | | Azure Key Vault | Azure Key Vault | | HashiCorp Vault | Vault |
Kustomize
Section titled “Kustomize”Kustomize is a template-free customization tool using overlays to patch base configurations. See documentation, examples, and file reference.
Helm is the package manager for Kubernetes, using charts to define, install, and upgrade applications.
KSail uses Helm v4 with kstatus-based waiting for reliable resource readiness checks, including custom resources and status conditions. See Helm docs and Artifact Hub.