Declarative Configuration

KSail uses declarative YAML configuration files for reproducible cluster setup. This page describes ksail.yaml — the project-level configuration file that defines your cluster’s desired state.

What is ksail.yaml?

Each KSail project includes a ksail.yaml file describing the cluster and workload configuration. Run ksail cluster init to generate this file, which can be committed to version control and shared with your team.

The configuration file uses the ksail.io/v1alpha1 API version and follows the Cluster kind schema. It defines:

  • Cluster settings: distribution, networking, components
  • Connection details: kubeconfig path, context, timeouts
  • Workload configuration: manifest directory, validation preferences
  • Editor preferences: for interactive workflows

Minimal Example 

# yaml-language-server: $schema=https://raw.githubusercontent.com/devantler-tech/ksail/main/schemas/ksail-config.schema.json
apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  cluster:
    distribution: Vanilla
    distributionConfig: kind.yaml

This minimal configuration creates a Vanilla cluster (implemented with Kind) using defaults for all other settings.

Complete Example 

# yaml-language-server: $schema=https://raw.githubusercontent.com/devantler-tech/ksail/main/schemas/ksail-config.schema.json
apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  editor: code --wait
  cluster:
    distribution: Vanilla
    distributionConfig: kind.yaml
    connection:
      kubeconfig: ~/.kube/config
      context: kind-kind
      timeout: 5m
    cni: Cilium
    # CSI "Default" uses the distribution's built-in storage behavior:
    # - K3s: includes local-path-provisioner by default
    # - Vanilla and Talos: no CSI installed; use LocalPathStorage if needed
    csi: Default
    metricsServer: Enabled
    certManager: Enabled
    policyEngine: Kyverno
    localRegistry: Enabled
    gitOpsEngine: Flux
    localRegistryOptions:
      hostPort: 5050
  workload:
    sourceDirectory: k8s
    validateOnPush: true

Configuration Reference

Top-Level Fields

Field Type Required Description
apiVersion string Yes Must be ksail.io/v1alpha1
kind string Yes Must be Cluster
spec object Yes Cluster and workload specification (see below)

spec

The spec field is a Spec object that defines editor, cluster, and workload configuration.

Field Type Default Description
editor string – Editor command for interactive workflows
cluster ClusterSpec – Cluster configuration (distribution, components)
workload WorkloadSpec – Workload manifest configuration

spec.editor

Editor command used by KSail for interactive workflows like ksail cipher edit or ksail workload edit.

Examples: code --wait, vim, nano

If not specified, KSail falls back to standard editor environment variables (SOPS_EDITOR, KUBE_EDITOR, EDITOR, VISUAL) or system defaults (vim, nano, vi).

spec.cluster (ClusterSpec)

Field Type Default Description
distribution enum Vanilla Kubernetes distribution to use
provider enum Docker Infrastructure provider (Docker, Hetzner)
distributionConfig string (see below) Path to distribution-specific configuration
connection Connection – Cluster connection settings
cni enum Default Container Network Interface
csi enum Default Container Storage Interface
metricsServer enum Default Install metrics-server
certManager enum Disabled Install cert-manager
policyEngine enum None Policy engine to install
localRegistry LocalRegistry – Registry configuration (see below)
gitOpsEngine enum None GitOps engine to install
mirrorRegistries []string – Mirror registry specifications
kind object – Kind-specific options (Vanilla distribution)
k3d object – K3d-specific options (K3s distribution)
talos object – Talos-specific options
hetzner object – Hetzner Cloud provider options
cilium object – Cilium CNI options
calico object – Calico CNI options
flux object – Flux GitOps options
argocd object – ArgoCD GitOps options
helm object – Helm tool options (reserved)
kustomize object – Kustomize tool options (reserved)

distribution

Kubernetes distribution to use for the local cluster. See Distributions for detailed information about each distribution.

Valid values:

  • Vanilla (default) – Standard upstream Kubernetes (implemented with Kind)
  • K3s – Lightweight Kubernetes (implemented with K3d)
  • Talos – Talos Linux in Docker containers or Hetzner Cloud servers

provider

Infrastructure provider for running cluster nodes. See Providers for more details.

Valid values:

  • Docker (default) – Run nodes as Docker containers (local development)
  • Hetzner – Run nodes on Hetzner Cloud servers (requires HCLOUD_TOKEN)

Note: Hetzner provider is only supported with the Talos distribution.

distributionConfig

Path to the distribution-specific configuration file or directory. This tells KSail where to find settings like node counts, port mappings, and distribution-specific features.

Default values by distribution:

  • Vanilla → kind.yaml
  • K3s → k3d.yaml
  • Talos → talos/ (directory)

See Distribution Configuration below for details on each format.

connection (Connection)

Field Type Default Description
kubeconfig string ~/.kube/config Path to kubeconfig file
context string (derived) Kubeconfig context name
timeout duration – Timeout for cluster operations

Context defaults by distribution:

  • Vanilla → kind-kind
  • K3s → k3d-k3d-default
  • Talos → admin@talos-default

Timeout format: Go duration string (e.g., 30s, 5m, 1h)

cni

Container Network Interface to install. See CNI for more details.

Valid values:

  • Default – Uses the distribution’s built-in CNI (kindnetd for Vanilla, flannel for K3s)
  • Cilium – Installs Cilium for advanced networking and observability
  • Calico – Installs Calico for network policies

csi

Container Storage Interface to install. See CSI for more details.

Valid values:

  • Default – Uses the distribution’s built-in storage (K3s includes local-path-provisioner; Vanilla does not)
  • LocalPathStorage – Explicitly installs local-path-provisioner

metricsServer

Whether to install metrics-server for resource metrics.

Valid values:

  • Default (default) – Uses distribution’s default behavior (K3s includes metrics-server; Vanilla and Talos do not)
  • Enabled – Install metrics-server
  • Disabled – Skip installation

When metrics-server is enabled on Vanilla or Talos, KSail automatically:

  1. Configures kubelet certificate rotation (serverTLSBootstrap: true)
  2. Installs kubelet-csr-approver to approve certificate requests
  3. Deploys metrics-server with secure TLS communication

Note: K3s includes metrics-server by default, so this setting has no effect on K3s.

certManager

Whether to install cert-manager for TLS certificate management.

Valid values:

  • Enabled – Install cert-manager
  • Disabled (default) – Skip installation

policyEngine

Policy engine to install for enforcing security, compliance, and best practices. See Policy Engines for more details about Kyverno and Gatekeeper.

Valid values:

  • None (default) – No policy engine
  • Kyverno – Install Kyverno for Kubernetes-native policy management
  • Gatekeeper – Install OPA Gatekeeper for OPA-based policy enforcement

localRegistry

Registry configuration for GitOps workflows. Supports local Docker registries or external registries with authentication.

Format: [user:pass@]host[:port][/path]

Examples:

  • localhost:5050 – Local Docker registry
  • ghcr.io/myorg/myrepo – GitHub Container Registry
  • ${USER}:${PASS}@ghcr.io:443/myorg – With credentials from environment variables

Note: Credentials support ${ENV_VAR} placeholders for secure handling.

gitOpsEngine

GitOps engine to install for continuous deployment workflows. See GitOps for more details about Flux and ArgoCD. When set to Flux or ArgoCD, KSail scaffolds a GitOps CR (FluxInstance or ArgoCD Application) into your source directory at gitops/flux/flux-instance.yaml or gitops/argocd/application.yaml.

Valid values:

  • None (default) – No GitOps engine
  • Flux – Install Flux CD and scaffold FluxInstance CR
  • ArgoCD – Install Argo CD and scaffold Application CR

Distribution and Tool Options

Advanced configuration options are direct fields under spec.cluster. See Schema Support for the complete structure.

Talos options (spec.cluster.talos):

  • controlPlanes – Number of control-plane nodes (default: 1)
  • workers – Number of worker nodes (default: 0)
  • config – Path to talosconfig file (default: ~/.talos/config)
  • iso – Cloud provider ISO/image ID for Talos Linux (default: 122630 for x86)

Hetzner options (spec.cluster.hetzner):

  • controlPlaneServerType – Server type for control-plane nodes (default: cx23)
  • workerServerType – Server type for worker nodes (default: cx23)
  • location – Datacenter location: fsn1, nbg1, hel1 (default: fsn1)
  • networkName – Private network name (default: <cluster>-network)
  • networkCidr – Network CIDR block (default: 10.0.0.0/16)
  • sshKeyName – SSH key name for server access (optional)
  • tokenEnvVar – Environment variable for API token (default: HCLOUD_TOKEN)

Kind options (spec.cluster.kind):

  • mirrorsDir – Directory for containerd host mirror configuration

spec.workload (WorkloadSpec)

Field Type Default Description
sourceDirectory string k8s Directory containing Kubernetes manifests
validateOnPush boolean false Validate manifests before pushing to registry

Distribution Configuration

KSail references distribution-specific configuration files to customize cluster behavior. The path to these files is set via spec.cluster.distributionConfig.

Vanilla (implemented with Kind) Configuration

Default: kind.yaml

The Vanilla distribution is configured via a YAML file following the Kind configuration schema. This allows you to customize:

  • Node images and versions
  • Extra port mappings
  • Extra mounts
  • Networking settings

Documentation: Kind Configuration

Example:

# kind.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30000
        hostPort: 30000

K3s (implemented with K3d) Configuration

Default: k3d.yaml

The K3s distribution is configured via a YAML file following the K3d configuration schema. This allows you to customize:

  • Server and agent counts
  • Port mappings
  • Volume mounts
  • Registry configurations

Documentation: K3d Configuration

Example:

# k3d.yaml
apiVersion: k3d.io/v1alpha5
kind: Simple
servers: 1
agents: 2
ports:
  - port: 8080:80
    nodeFilters:
      - loadbalancer

Talos Configuration

Default: talos/ directory

Talos uses a directory structure for Talos machine configuration patches. Each directory contains YAML patch files that modify the Talos machine configuration.

Documentation: Talos Configuration Reference

Directory structure and examples:

# talos/cluster/kubelet.yaml
# Patches applied to all nodes
machine:
  kubelet:
    extraArgs:
      max-pods: "250"

# talos/control-planes/api.yaml
# Patches for control-plane nodes only
machine:
  kubelet:
    extraArgs:
      feature-gates: "EphemeralContainers=true"

# talos/workers/custom.yaml
# Patches for worker nodes only
machine:
  sysctls:
    net.core.somaxconn: "65535"

Use spec.cluster.talos to configure node counts:

spec:
  cluster:
    distribution: Talos
    distributionConfig: talos
    talos:
      controlPlanes: 3
      workers: 2

Schema Support

KSail provides a JSON Schema for IDE validation and autocompletion. Reference it at the top of your ksail.yaml:

# yaml-language-server: $schema=https://raw.githubusercontent.com/devantler-tech/ksail/main/schemas/ksail-config.schema.json
apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  # ...

IDEs with YAML language support (like VS Code with the Red Hat YAML extension) will provide:

  • Field autocompletion
  • Inline documentation
  • Validation errors for invalid values
  • Enum suggestions for fields like distribution, cni, etc.