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.

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 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, GitOps integration, and isolated development. Support external registries with authentication using format [user:pass@]host[:port][/path] where credentials can use ${ENV_VAR} placeholders.

Local Registry

ksail cluster init --local-registry localhost:5050
ksail cluster create

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

Mirror Registries

For Docker-based clusters (local Vanilla, K3s, Talos-on-Docker, and VCluster), KSail enables docker.io, ghcr.io, quay.io, and registry.k8s.io mirrors by default to avoid rate limits and improve CI/CD performance. For these clusters, mirror registries run as local pull-through cache containers that authenticate to upstream registries using credentials resolved from ${ENV_VAR} placeholders. Cached images persist across restarts via containerd hosts.toml injection for Vanilla and VCluster, or via K3d registries configuration for K3s and Talos-on-Docker. For Talos clusters on Hetzner, no mirrors are enabled by default. Instead, you can configure externally reachable mirror endpoints via config/flags, which are applied through Talos machine config patches.

# Default mirrors (docker.io, ghcr.io, quay.io, registry.k8s.io)
ksail cluster init

# Add authenticated mirrors (format: [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 resource manifests to a compressed archive and restore them to a target cluster. Backups capture resource YAML in dependency order (CRDs → namespaces → storage → workloads), strip server-assigned metadata for portability, and embed a backup-metadata.json file containing version, timestamp, cluster name, distribution, provider, KSail version, resource count, and resource types. Each restored resource is automatically labeled with ksail.io/backup-name (derived from the archive filename) and ksail.io/restore-name (unique per restore operation) for traceability.

# Backup all namespaces
ksail cluster backup --output ./backup.tar.gz

# Backup specific namespaces and exclude resource types
ksail cluster backup -o ./backup.tar.gz -n default,kube-system --exclude-types events,pods

# Restore, skipping already-existing resources
ksail cluster restore --input ./backup.tar.gz

# Restore, updating existing resources
ksail cluster restore -i ./backup.tar.gz --existing-resource-policy update

# Dry-run: preview what would be restored
ksail cluster restore --input ./backup.tar.gz --dry-run

# Query all resources from a specific backup archive (strip .tar.gz from the filename)
kubectl get all -l ksail.io/backup-name=backup --all-namespaces

# Inspect backup metadata (inside the archive)
tar -xOzf ./backup.tar.gz backup-metadata.json | jq .

Commands: ksail cluster backup, ksail cluster restore

Command	Description
ksail cluster backup	Export resources to a .tar.gz
ksail cluster restore	Apply resources from a .tar.gz

Note

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

Code Generation

Generate Kubernetes resources (Deployment, Service, ConfigMap, Secret, Ingress), Helm releases (HelmRelease CRs), and source resources (OCIRepository, GitRepository, HelmRepository) 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

Commands: ksail workload gen, ksail workload create

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.

Three modes are available:

• Agent (</>) for full execution with approval
• Plan (≡) for step-by-step guidance without execution
• Ask (?) for read-only investigation

Press Tab to cycle between modes. Requires GitHub Copilot CLI installed and authenticated.

ksail chat

Commands: ksail chat

Full Guide: AI Chat Assistant — Detailed mode explanations, keyboard shortcuts, and workflows

VSCode Extension

Manage KSail clusters directly from Visual Studio Code with cluster sidebar view, interactive wizards for init/create operations, command palette access, keyboard shortcuts (Cmd+Shift+K, then I/C/D), K9s integration, and MCP server provider for AI assistants. Requires KSail CLI and Docker installed; K9s optional for cluster connection.

# Install from VSCode Marketplace
# Search for "KSail" in Extensions view

Installation: See VSCode Extension Installation for setup instructions.

Repository: vsce/

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