Skip to content
KSail

Configuration

KSail supports multiple configuration sources, enabling flexibility from quick prototyping to production-ready GitOps workflows.

How Configuration Works

Section titled “How Configuration Works”

KSail configuration controls every aspect of cluster creation and workload management—from the Kubernetes distribution to component installation, networking, and GitOps settings.

Configuration can come from multiple sources, allowing you to:

  • Commit defaults in ksail.yaml for team consistency
  • Override temporarily with CLI flags for testing
  • Customize per-environment with environment variables
  • Leverage distribution features through native config files

Configuration Sources

Section titled “Configuration Sources”

KSail accepts configuration from four sources:

Source Description Use Case
ksail.yaml Declarative YAML file Project defaults, version control
CLI Flags Command-line arguments Temporary overrides, CI/CD
Environment Variables KSAIL_-prefixed variables Machine-specific settings, secrets
Distribution Config kind.yaml, k3d.yaml, talos/ Distribution-specific features

Configuration Precedence

Section titled “Configuration Precedence”

When the same setting is specified in multiple sources, KSail uses this order (highest to lowest priority):

1. CLI flags          (e.g., --metrics-server Disabled)
2. Environment vars   (e.g., KSAIL_SPEC_CLUSTER_DISTRIBUTION=K3s)
3. ksail.yaml         (nearest file in current or parent directories)
4. Built-in defaults

Example: If ksail.yaml sets distribution: Vanilla but you run ksail cluster create --distribution K3s, the CLI flag wins and K3s is used.

This precedence model means you can commit sensible defaults while still allowing temporary overrides without editing files.

When to Use What

Section titled “When to Use What”

ksail.yaml

Section titled “ksail.yaml”

Use declarative configuration for:

  • Project-wide defaults that should be version-controlled
  • Team consistency so everyone uses the same settings
  • Cluster identity (name, distribution, CNI, GitOps engine)
  • Reproducible environments across machines
# yaml-language-server: $schema=https://raw.githubusercontent.com/devantler-tech/ksail/main/schemas/ksail-config.schema.json
apiVersion: ksail.io/v1alpha1
kind: Cluster
metadata:
  name: my-cluster
spec:
  cluster:
    distribution: Vanilla
    cni: Cilium
    gitOpsEngine: Flux

Set metadata.name to pin the cluster name in version control. This takes priority over the distribution config name but is overridden by the --name CLI flag.

CLI Flags

Section titled “CLI Flags”

Use command-line flags for:

  • Temporary overrides during development
  • Testing different configurations without editing files
  • CI/CD pipelines with environment-specific settings
  • Quick experiments before committing changes
Terminal window
# Test with K3s instead of Vanilla (without changing ksail.yaml)
ksail cluster create --distribution K3s


# Disable metrics server for a lightweight test
ksail cluster create --metrics-server Disabled

Alternate Config File (--config)

Section titled “Alternate Config File (--config)”

The root --config flag points KSail to a specific config file instead of searching for ksail.yaml via directory traversal. This is useful for managing multiple environments from the same directory:

Terminal window
# Use a production config
ksail --config ksail.prod.yaml workload push


# Use a staging config
ksail --config ksail.staging.yaml cluster update

--config is a persistent flag inherited by all subcommands, so it can be placed immediately after ksail before any subcommand.

For multi-environment patterns (separate config files per environment, environment variable expansion, and CI/CD usage), see Multi-Environment Workflows.

Environment Variables

Section titled “Environment Variables”

Use environment variables for:

  • Machine-specific settings (different kubeconfig paths)
  • CI/CD secrets and credentials
  • Global preferences that apply across all projects
Terminal window
# Set distribution for all ksail commands in this shell
export KSAIL_SPEC_CLUSTER_DISTRIBUTION=K3s
ksail cluster create

Environment variables use the KSAIL_ prefix and follow the configuration path in uppercase with underscores:

Setting Environment Variable
spec.cluster.distribution KSAIL_SPEC_CLUSTER_DISTRIBUTION
spec.cluster.cni KSAIL_SPEC_CLUSTER_CNI
spec.cluster.gitOpsEngine KSAIL_SPEC_CLUSTER_GITOPSENGINE
spec.provider.hetzner.location KSAIL_SPEC_PROVIDER_HETZNER_LOCATION
spec.provider.omni.endpoint KSAIL_SPEC_PROVIDER_OMNI_ENDPOINT
spec.workload.tag KSAIL_SPEC_WORKLOAD_TAG

Variable Expansion (${VAR})

Section titled “Variable Expansion (${VAR})”

Values in ksail.yaml support ${VAR} expansion from the environment at runtime. This is distinct from the KSAIL_-prefixed overrides above: an override replaces a whole field, while ${VAR} substitutes an environment value into a field. It lets you keep one config in version control while values that vary per environment—or that are secret—come from the environment when KSail runs.

The canonical use is keeping credentials out of Git. Reference a token like ${GHCR_TOKEN} or ${HCLOUD_TOKEN} instead of committing the secret:

# yaml-language-server: $schema=https://raw.githubusercontent.com/devantler-tech/ksail/main/schemas/ksail-config.schema.json
apiVersion: ksail.io/v1alpha1
kind: Cluster
metadata:
  name: my-cluster
spec:
  cluster:
    localRegistry:
      registry: "user:${GHCR_TOKEN}@ghcr.io/org/platform/manifests"

This is how a single ksail.yaml serves many environments and stays credential-free in version control—see Multi-Environment Workflows and the Reference Architecture.

Distribution Config

Section titled “Distribution Config”

Use distribution configuration files for:

  • Distribution-specific features not exposed in ksail.yaml
  • Advanced customization (kernel parameters, extra mounts)
  • Node topology (control-plane/worker counts, port mappings)

These files follow the native schema for each distribution:

Configuration Guides

Section titled “Configuration Guides”