Core Concepts

This page explains how KSail thinks, so the commands and configuration make sense. For the internals, see Architecture; for how a project grows, see Project Structure.

KSail is a superset, not a replacement

KSail bundles the Kubernetes tools you’d otherwise install and wire up yourself — kind, k3d, Talos, vCluster, Flux, ArgoCD, Helm, Kustomize, SOPS — behind one binary and one declarative config.

Crucially, it doesn’t invent proprietary formats. ksail project init generates native configuration files — kind.yaml, k3d.yaml, talos/ patches, vcluster.yaml, kwok/ — that work directly with the underlying tools. You can run those clusters, or migrate away, without KSail. KSail’s value is the consistent workflow layered on top: the same init → create → update → delete commands across every distribution.

Distribution vs Provider: what runs where

The single most important idea in KSail is the separation of two concerns:

• A distribution (internally, a provisioner) is what Kubernetes you run — Vanilla, K3s, Talos, VCluster, KWOK, or EKS. It decides the flavor and how the cluster is configured.
• A provider is where the nodes run — Docker (local containers), Kubernetes (nested pods), Hetzner (cloud servers), Omni (Talos via Sidero’s SaaS), or AWS (managed EKS).

# ksail.yaml — "what" and "where" are independent
spec:
  cluster:
    distribution: Talos    # what
    provider: Docker       # where (also Hetzner, Omni, …)

The same distribution can run on different providers — e.g. Talos on Docker locally and Talos on Hetzner in production — which is what makes local development a faithful rehearsal for production. Not every pairing is valid; the Choose your setup decision aid and the Support Matrix show what’s possible.

The declarative config

ksail.yaml is the source of truth for a cluster: its distribution, provider, networking (CNI), storage (CSI), GitOps engine, registries, and more. It’s meant to be committed to Git. Alongside it sit the native distribution configs (kind.yaml, talos/, …) for distribution-specific tuning.

Values support ${VAR} expansion so one config can stay credential-free in Git (registry: "user:${GHCR_TOKEN}@ghcr.io/org/…"). See Configuration for the full reference.

The cluster lifecycle

Every distribution and provider shares the same verbs:

ksail project init      # scaffold ksail.yaml + native configs + k8s/
ksail cluster create    # provision nodes and install components (CNI, CSI, GitOps, …)
ksail cluster update    # reconcile ksail.yaml changes onto a running cluster
ksail cluster delete    # tear it down

Workloads are then delivered with GitOps — ksail workload push compiles your manifests into an OCI artifact and ksail workload reconcile tells the in-cluster engine to apply it (with ksail workload apply as an imperative shortcut). See Deliver with GitOps.

Configuration precedence

When the same setting is specified in more than one place, KSail resolves it in this order (highest wins):

1. CLI flags (--distribution K3s)
2. Environment variables (KSAIL_…)
3. ksail.yaml
4. Built-in defaults

This lets you keep a stable ksail.yaml and override a value temporarily for one command — and target a specific environment’s config with --config ksail.prod.yaml. See Multi-Environment Workflows.

Cluster state

To run update correctly, KSail needs to know a cluster’s current state:

• Distributions that can introspect themselves (e.g. Talos) are read directly from the cluster.
• Distributions that can’t (e.g. Kind, K3d) have their spec persisted by KSail under ~/.ksail/clusters/<name>/ so it can compute an accurate diff.

This is why ksail cluster update can detect drift and classify changes as in-place, reboot-required, or recreate-required. See Architecture for the details.

---

Technologies KSail builds on

KSail is built on established, upstream Kubernetes technologies. This reference links each out to its official documentation.

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

KSail supports six distributions. Each has a dedicated reference page with setup and tuning details; the Choose your setup page helps you pick.

Distribution	Tool	Upstream docs
Vanilla	Kind	config
K3s	K3d	K3s · config
Talos	Talos Linux	config reference
VCluster	vCluster (Vind)	vcluster.yaml
KWOK	kwokctl	user guide
EKS	eksctl	EKS docs

Providers

Providers are infrastructure backends that run cluster nodes. KSail abstracts provider-specific operations behind the shared lifecycle. Each has a dedicated page: Docker, Kubernetes (Nested), Hetzner, Omni, and AWS.

Note

Hetzner and Omni are Talos-only. KSail enables Hetzner operations only when HCLOUD_TOKEN is set; Omni requires a Sidero Omni service account.

Container Network Interface (CNI)

CNI is a specification for configuring network interfaces in Linux containers, providing pod networking, policies, and observability.

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-manager for 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

Calico provides networking and network security with strong policy enforcement. See documentation, network policy, and getting started.

Container Storage Interface (CSI)

CSI is a standard for exposing storage systems to containerized workloads, providing persistent storage for stateful applications.

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

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

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

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

Policy engines enforce security, compliance, and best practices through admission control and continuous validation.

Kyverno

Kyverno is a Kubernetes-native policy engine with policies written as YAML resources without new languages. See documentation, policies, and policy reports.

Gatekeeper

OPA Gatekeeper brings Open Policy Agent to Kubernetes with policies in Rego. See Gatekeeper docs, OPA docs, and library.

OCI Registries

OCI Distribution defines a standard for storing and distributing container images and artifacts. KSail uses OCI registries both for images and for the manifest artifacts published by ksail workload push. See specification, Docker Registry, and OCI Artifacts.

GitOps

GitOps uses Git (or an OCI registry) as the single source of truth for declarative infrastructure and applications. Pick one engine per cluster at ksail project init --gitops-engine.

Flux

Flux keeps clusters in sync with configuration in Git or OCI registries. See documentation, concepts, and FluxInstance CRD.

ArgoCD

Argo CD provides declarative GitOps with a web UI for visualizing application state. See documentation, concepts, Application CRD, and ArgoCD ApplicationSet guide.

SOPS

SOPS (Secrets OPerationS) edits encrypted files with multiple key management backends. KSail manages these with ksail workload cipher; see Secret Management. Reference: documentation, age encryption, and SOPS with Flux.

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

Kustomize is a template-free customization tool using overlays to patch base configurations — the basis for KSail’s recommended layered project structure. See documentation, examples, and file reference.

Helm

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.