Features

KSail provides a unified CLI for Kubernetes development with built-in support for cluster provisioning (local Docker-based clusters for all distributions, plus Hetzner Cloud for Talos), workload management, GitOps workflows, and secret encryption.

Cluster Provisioning

Create and manage local Kubernetes clusters with a single command. KSail supports multiple distributions and automatically configures networking, storage, and observability components.

ksail cluster init --name my-cluster --distribution Vanilla --cni Cilium
ksail cluster create

Capabilities:

  • Multi-distribution support – Vanilla, K3s, and Talos distributions
  • Component installation – CNI (Cilium, Calico), CSI, metrics-server with kubelet-csr-approver, cert-manager, and policy engines
  • Custom cluster naming – Set container, registry, and context names via --name
  • Node configuration – Control-plane and worker node counts via --control-planes and --workers
  • Connection management – Automatic kubeconfig and context configuration

Commands: ksail cluster

Command Description
ksail cluster init Initialize a new project
ksail cluster create Create a cluster
ksail cluster delete Delete a cluster
ksail cluster start Start a stopped cluster
ksail cluster stop Stop a running cluster
ksail cluster info Show cluster information
ksail cluster list List clusters
ksail cluster connect Connect to cluster with K9s

Configuration: Declarative Configuration

Workload Management

Deploy and manage Kubernetes workloads using familiar kubectl and Helm patterns wrapped in consistent commands.

ksail workload apply -k k8s/
ksail workload get pods
ksail workload logs deployment/my-app

Capabilities:

  • Apply manifests – Kustomize directories, Helm charts, or raw YAML
  • Generate resources – Create deployments, services, secrets, and more
  • Debug workloads – Logs, exec, describe, and explain commands
  • Validate manifests – Schema validation before applying

Commands: ksail workload

Command Description
ksail workload apply Apply manifests to cluster
ksail workload get Get resources
ksail workload describe Describe resources
ksail workload logs View container logs
ksail workload exec Execute command in container
ksail workload gen Generate Kubernetes manifests
ksail workload validate Validate manifests against schemas
ksail workload install Install Helm charts
ksail workload scale Scale deployments
ksail workload rollout Manage rollouts
ksail workload wait Wait for conditions

GitOps Workflows

Enable GitOps with Flux or ArgoCD for declarative, Git-driven deployments. KSail scaffolds the required CRs and provides commands for pushing and reconciling workloads.

ksail cluster init --gitops-engine Flux --local-registry
ksail cluster create
ksail workload push
ksail workload reconcile

Capabilities:

  • Engine installation – Automatic Flux or ArgoCD setup
  • CR scaffolding – FluxInstance or ArgoCD Application generated automatically
  • OCI artifact packaging – Package manifests and push to local registry
  • Reconciliation triggers – Force sync and wait for completion

Workflow:

  1. Initialize with GitOps engine and local registry enabled
  2. Create cluster (installs GitOps controllers)
  3. Edit manifests in source directory
  4. Push manifests as OCI artifact
  5. Trigger reconciliation

Commands:

Command Description
ksail workload push Package and push manifests to registry
ksail workload reconcile Trigger GitOps sync and wait

Registry Management

Run local OCI registries for faster development cycles, configure mirror registries to avoid rate limits, or use external registries with authentication.

Local Registry 

ksail cluster init --local-registry --local-registry-port 5050
ksail cluster create

docker tag my-app localhost:5050/my-app
docker push localhost:5050/my-app

Benefits: Faster image pulls, GitOps integration, isolated development

With authentication (for external registries):

ksail cluster init \
  --local-registry '${GITHUB_USER}:${GITHUB_TOKEN}@ghcr.io/myorg/myrepo'

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

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

Mirror Registries 

ksail cluster init \
  --mirror-registry docker.io=https://registry-1.docker.io \
  --mirror-registry gcr.io=https://gcr.io

Benefits: Avoid Docker Hub rate limits, offline development, faster CI/CD

With authentication:

ksail cluster init \
  --mirror-registry '${DOCKER_USER}:${DOCKER_TOKEN}@docker.io=https://registry-1.docker.io'

Format: [user:pass@]host[=endpoint]

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

Secret Management

Encrypt and decrypt secrets using SOPS with support for age, PGP, and cloud KMS providers.

ksail cipher encrypt secret.yaml
ksail cipher decrypt secret.enc.yaml
ksail cipher edit secret.enc.yaml
ksail cipher import AGE-SECRET-KEY-1...

Commands: ksail cipher

Command Description
ksail cipher encrypt Encrypt a file with SOPS
ksail cipher decrypt Decrypt a SOPS-encrypted file
ksail cipher edit Edit encrypted file in-place
ksail cipher import Import age private key

Supported KMS: See Key Management Systems for supported providers and documentation links.

Code Generation

Generate Kubernetes manifests, Helm releases, and Flux/ArgoCD resources using built-in generators.

ksail workload gen deployment my-app --image=nginx --port=80
ksail workload gen service my-app --port=80
ksail workload gen helmrelease my-chart --source=oci://registry/chart

Capabilities:

  • Kubernetes resources – Deployments, services, configmaps, secrets, ingress, and more
  • Helm releases – HelmRelease CRs for Flux
  • Source resources – OCIRepository, GitRepository, HelmRepository

Commands: ksail workload gen, ksail workload create

Declarative Configuration

Define cluster configuration in ksail.yaml for reproducible, version-controlled environments.

# ksail.yaml
apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  cluster:
    distribution: Vanilla
    cni: Cilium
    gitOpsEngine: Flux
    localRegistry: Enabled
  workload:
    sourceDirectory: k8s

Benefits: Team consistency, reproducible environments, Git-tracked configuration

Reference: Declarative Configuration

Next Steps

  • Use Cases – Workflows for learning, development, and CI/CD
  • Concepts – Understand the technologies KSail builds upon
  • Configuration – Complete configuration reference