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:

• Kubernetes Documentation
• Kubernetes Concepts
• kubectl Reference

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:

• Kind Documentation
• Kind Configuration
• Kind Quick Start

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:

• K3s Documentation
• K3d Documentation
• K3d Configuration

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:

• Talos Documentation
• Talos Configuration Reference
• Talos Getting Started

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:

• Docker Documentation
• Docker Desktop

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:

• Hetzner Cloud Documentation
• Hetzner Cloud API
• Talos on Hetzner

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:

• Cilium Documentation
• Cilium Concepts
• Network Policies with Cilium

Calico

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

Key resources:

• Calico Documentation
• Calico Network Policy
• Calico Getting Started

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:

• Local Path Provisioner GitHub
• Kubernetes Persistent Volumes
• Storage Classes

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:

• Metrics Server GitHub
• Resource Metrics Pipeline
• Horizontal Pod Autoscaler

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:

• Kubelet CSR Approver GitHub
• Kubernetes TLS Bootstrapping
• Certificate Signing Requests

cert-manager

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

Key resources:

• cert-manager Documentation
• cert-manager Concepts
• Issuer Types

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:

• Kyverno Documentation
• Kyverno Policies
• Policy Reports

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:

• Gatekeeper Documentation
• OPA Documentation
• Gatekeeper Library

OCI Registries

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

Key resources:

• OCI Distribution Specification
• Docker Registry
• OCI Artifacts

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:

• Flux Documentation
• Flux Concepts
• FluxInstance CRD

ArgoCD

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

Key resources:

• Argo CD Documentation
• Argo CD Concepts
• Application CRD

SOPS

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

Key resources:

• SOPS Documentation
• age Encryption
• SOPS with Flux

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:

• Kustomize Documentation
• Kustomize Examples
• Kustomization File Reference

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:

• Helm Documentation
• Helm Charts
• HIP-0022: Wait With kstatus
• kstatus Documentation
• Artifact Hub – Find and publish Helm charts

Next Steps

• Features – Explore KSail capabilities
• Use Cases – Practical workflows and examples
• Configuration – Complete configuration reference