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.

Kubernetes

Kubernetes is an open-source container orchestration platform for automating deployment, scaling, and management of containerized applications.

Key resources:

Distributions

Kubernetes distributions package the Kubernetes components with additional tooling for specific use cases. KSail supports three distributions: Vanilla, K3s, and Talos. All distributions can run on the Docker provider; Talos can also run on the Hetzner provider.

Vanilla (implemented with Kind)

Vanilla uses Kind (Kubernetes in Docker) to run standard upstream Kubernetes clusters using Docker containers as nodes. This distribution provides upstream Kubernetes without modifications, making it ideal for testing against standard Kubernetes behavior.

Key resources:

K3s (implemented with K3d)

K3s is a lightweight, certified Kubernetes distribution built for resource-constrained environments. KSail uses K3d to run K3s clusters in Docker containers. K3s includes sensible defaults like an embedded load balancer, local storage provisioner, and metrics server.

Key resources:

Talos

Talos Linux is a minimal, immutable operating system designed specifically for Kubernetes. Provides enhanced security through API-driven configuration with no shell access.

Key resources:

Providers

Providers are the infrastructure backends that run cluster nodes. KSail abstracts provider-specific operations so you can use the same workflow regardless of where your cluster runs.

Docker

The Docker provider runs Kubernetes nodes as Docker containers on your local machine. This is the default provider for all distributions and requires only Docker to be installed.

Supported distributions: Vanilla, K3s, Talos

Key resources:

Hetzner

The Hetzner provider creates Kubernetes nodes as Hetzner Cloud servers. This provider enables running production-grade clusters on Hetzner’s infrastructure with full lifecycle management.

Supported distributions: Talos

Requirements:

  • Hetzner Cloud API token (set via HCLOUD_TOKEN environment variable)
  • Talos ISO available in your Hetzner account

Note

KSail only enables Hetzner-backed operations when HCLOUD_TOKEN is set; if it’s unset, Hetzner is skipped.

Key resources:

Container Network Interface (CNI)

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

Cilium

Cilium is an eBPF-based CNI providing networking, security, and observability. Offers advanced features like transparent encryption and service mesh.

Key resources:

Calico

Calico provides networking and network security for Kubernetes. Known for its network policy enforcement capabilities.

Key resources:

Container Storage Interface (CSI)

CSI is a standard for exposing storage systems to containerized workloads. CSI drivers provide 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.

Key resources:

Metrics Server

Metrics Server collects resource metrics from kubelets and exposes them via the Kubernetes API. Required for Horizontal Pod Autoscaler (HPA) and kubectl top.

Key resources:

Kubelet CSR Approver

Kubelet CSR Approver automatically approves Certificate Signing Requests (CSRs) for kubelet serving certificates. When serverTLSBootstrap: true is enabled on kubelets, they request proper TLS certificates via CSR instead of using self-signed certificates. This controller approves those requests, enabling secure TLS communication between components like metrics-server and kubelets.

Why it matters:

  • Metrics-server requires secure TLS communication with kubelets
  • Without approved CSRs, kubelets use self-signed certificates that metrics-server rejects
  • KSail automatically installs kubelet-csr-approver when metrics-server is enabled on Vanilla or Talos

Key resources:

cert-manager

cert-manager automates TLS certificate management in Kubernetes. Supports ACME (Let’s Encrypt), self-signed, and external CA certificates.

Key resources:

Policy Engines

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

Kyverno

Kyverno is a Kubernetes-native policy engine designed for ease of use. Policies are written as Kubernetes resources using YAML, without requiring a new language.

Key resources:

Gatekeeper

OPA Gatekeeper brings Open Policy Agent (OPA) to Kubernetes as an admission controller. Policies are written in Rego, a declarative policy language.

Key resources:

OCI Registries

OCI Distribution defines a standard for storing and distributing container images and other artifacts.

Key resources:

GitOps

GitOps is an operational framework using Git as the single source of truth for declarative infrastructure and applications.

Flux

Flux is a GitOps toolkit for Kubernetes that keeps clusters in sync with configuration stored in Git or OCI registries.

Key resources:

ArgoCD

Argo CD is a declarative GitOps continuous delivery tool with a web UI for visualizing application state.

Key resources:

SOPS

SOPS (Secrets OPerationS) is an editor for encrypted files supporting multiple key management backends.

Key resources:

Key Management Systems

SOPS supports multiple key management backends:

Provider Documentation
age age-encryption.org
PGP GnuPG
AWS KMS AWS KMS Documentation
GCP KMS Cloud KMS Documentation
Azure Key Vault Azure Key Vault Documentation
HashiCorp Vault Vault Documentation

Kustomize

Kustomize is a template-free customization tool for Kubernetes manifests. It uses overlays to patch base configurations.

Key resources:

Helm

Helm is the package manager for Kubernetes. It uses charts to define, install, and upgrade applications.

kstatus Wait Support

KSail uses Helm v4 which includes support for HIP-0022 – enhanced resource waiting using kstatus. When Wait: true is enabled in chart installations, Helm leverages kstatus to:

  • Wait for custom resources to be ready (not just built-in resources)
  • Ensure full reconciliation of all resources (including cleanup of old pods in deployments)
  • Monitor status conditions using the standard Kubernetes ready condition

All KSail component installers use kstatus-based waiting to ensure reliable deployments.

Key resources:

Next Steps