Concepts
KSail builds upon established Kubernetes technologies and patterns. This page provides an overview of key concepts with links to upstream documentation for deeper understanding.
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), and vcluster.yaml (vCluster) for VCluster.
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 four distributions: Vanilla, K3s, Talos, and VCluster. 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.
Providers
Section titled âProvidersâProviders are infrastructure backends that run cluster nodes. KSail abstracts provider-specific operations for consistent workflows.
Runs Kubernetes nodes as Docker containers locally. Default provider for all distributions, requires only Docker. Supported distributions: Vanilla, K3s, Talos, VCluster. See 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 Cloud docs, API, and Talos on Hetzner.
Manages Talos clusters through the Sidero Omni SaaS platform API. Supported distributions: Talos. Requirements: a Sidero Omni account, a service account key provided via an environment variable (default name OMNI_SERVICE_ACCOUNT_KEY, configurable via spec.cluster.omni.serviceAccountKeyEnvVar), and an Omni API endpoint configured via spec.cluster.omni.endpoint. See 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 is an eBPF-based CNI offering networking, security, and observability with features like transparent encryption and service mesh. See documentation, concepts, and network policies.
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âKubelet CSR Approver automatically approves Certificate Signing Requests for kubelet serving certificates. When serverTLSBootstrap: true is enabled, kubelets request proper TLS certificates via CSR instead of self-signed certificates. This controller approves those requests, enabling secure TLS communication with metrics-server. KSail auto-installs this on Vanilla and Talos when metrics-server is enabled. See GitHub, 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 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.
Argo CD provides declarative GitOps with a web UI for visualizing application state. See documentation, concepts, and Application CRD.
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.
kstatus Wait Support
Section titled âkstatus Wait SupportâKSail uses Helm v4 with HIP-0022 support for enhanced resource waiting via kstatus. When Wait: true is enabled, Helm uses kstatus to wait for custom resources, ensure full reconciliation, and monitor status conditions. All KSail installers use kstatus-based waiting. See Helm docs, charts, HIP-0022, kstatus, and Artifact Hub.
Next Steps
Section titled âNext Stepsâ- Features â Explore KSail capabilities
- Use Cases â Practical workflows and examples
- Configuration â Complete configuration reference