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 Vanilla, K3s, Talos, and VCluster distributions, generates native configuration files (kind.yaml, k3d.yaml, Talos patches, vcluster.yaml) that work directly with upstream tools, and automatically configures CNI, CSI, metrics-server, cert-manager, and policy engines. Component installations use automatic retry with exponential backoff for transient failures. Use the global --benchmark flag anywhere in the command chain (for example, ksail --benchmark cluster create or ksail --benchmark cluster update); during cluster create and cluster update it displays per-component install durations (e.g., ✔ flux installed [5.2s]) for performance comparison across runs.

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

Tip

After ksail cluster init, you can use the generated configuration files directly:

• Vanilla: kind create cluster --config kind.yaml
• K3s: k3d cluster create --config k3d.yaml
• Talos: talosctl cluster create with generated patches
• VCluster: vcluster create my-cluster --values vcluster.yaml

KSail is a superset — you’re never locked in.

Commands: ksail cluster

Command	Description
ksail cluster init	Initialize a new project
ksail cluster create	Create a cluster
ksail cluster update	Update 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
ksail cluster switch	Switch active kubeconfig context
ksail cluster backup	Backup cluster resources
ksail cluster restore	Restore cluster resources

Configuration: Declarative Configuration

Workload Management

Deploy and manage Kubernetes workloads using familiar kubectl and Helm patterns. Apply Kustomize directories, Helm charts, or raw YAML; create, edit, delete, and inspect resources; debug with logs, exec, describe, and explain; expose services; export and import container images; and validate manifests against schemas.

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

Commands: ksail workload

Command	Description
ksail workload apply	Apply manifests to cluster
ksail workload create	Create resources imperatively
ksail workload get	Get resources
ksail workload describe	Describe resources
ksail workload delete	Delete Kubernetes resources
ksail workload edit	Edit a resource in-place
ksail workload explain	Get documentation for a resource type
ksail workload logs	View container logs
ksail workload exec	Execute command in container
ksail workload expose	Expose a resource as a service
ksail workload export	Export container images to tar archive
ksail workload import	Import container images from tar archive
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
ksail workload images	List required container images

GitOps Workflows

Enable GitOps with Flux or ArgoCD for declarative, Git-driven deployments. KSail automatically installs the GitOps engine, scaffolds FluxInstance or ArgoCD Application CRs, and provides commands to package manifests as OCI artifacts, push to the local registry, and trigger reconciliation.

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

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 image pulls and GitOps integration. External registries use format [user:pass@]host[:port][/path] with ${ENV_VAR} credential placeholders.

Local Registry

ksail cluster init --local-registry localhost:5050
ksail cluster create
docker build -t localhost:5050/my-app .
docker push localhost:5050/my-app

Mirror Registries

Docker-based clusters (Vanilla, K3s, Talos-on-Docker, VCluster) enable docker.io, ghcr.io, quay.io, and registry.k8s.io mirrors by default. These run as local pull-through cache containers with ${ENV_VAR} credential support. Talos on Hetzner requires explicit mirror configuration via flags or ksail.yaml.

ksail cluster init  # Default mirrors enabled

# Authenticated mirrors: [user:pass@]host[=endpoint]
ksail cluster init --mirror-registry '${GITHUB_USER}:${GITHUB_TOKEN}@ghcr.io=https://ghcr.io'

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.

Cluster Backup & Restore

Export cluster resources to a compressed archive and restore to any cluster. Backups capture YAML in dependency order (CRDs → namespaces → storage → workloads), strip server metadata, and include a backup-metadata.json file with metadata version, cluster identity (name, distribution, provider, KSail version), timestamp, and resource inventory (count and types). Restored resources receive ksail.io/backup-name and ksail.io/restore-name labels for traceability.

ksail cluster backup --output ./backup.tar.gz
ksail cluster restore --input ./backup.tar.gz
ksail cluster restore -i ./backup.tar.gz --existing-resource-policy update --dry-run

Commands: ksail cluster backup, ksail cluster restore

Note

This feature backs up resource manifests (YAML) only. Persistent volume data is not included.

Code Generation

Generate Kubernetes resources (Deployment, Service, ConfigMap, Secret, Ingress), Helm releases (HelmRelease CRs), and sources (OCIRepository, GitRepository, HelmRepository).

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

Commands: ksail workload gen

Declarative Configuration

Define cluster configuration in ksail.yaml for team consistency, reproducible environments, and Git-tracked configuration.

ksail.yaml

apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  cluster:
    distribution: Vanilla
    cni: Cilium
    gitOpsEngine: Flux
    localRegistry:
      registry: localhost:5050
  workload:
    sourceDirectory: k8s

Reference: Declarative Configuration

AI Chat Assistant

Get interactive help with cluster configuration and troubleshooting using an AI-powered chat session.

Two modes are available:

• Agent (</>) for full execution with approval
• Plan (≡) for step-by-step guidance without execution

Press Tab to cycle between modes. Requires an active GitHub Copilot subscription; KSail will prompt you to sign in on first use.

ksail chat

Full Guide: AI Chat Assistant

VSCode Extension

Manage clusters from Visual Studio Code with the Clusters View, polling-based cluster status view, status bar health indicator, interactive wizards, command palette (Cmd+Shift+K), K9s integration, and MCP server for AI assistants. Requires KSail CLI and Docker; K9s optional.

Marketplace: Visual Studio Marketplace

Next Steps

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