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

Note

Default mirrors enabled: KSail now enables docker.io and ghcr.io mirrors by default to avoid rate limits and improve CI/CD performance.

# Mirrors are enabled by default (docker.io and ghcr.io)
ksail cluster init

# Add additional mirrors
ksail cluster init \
  --mirror-registry gcr.io=https://gcr.io

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

With authentication:

# Using GitHub Container Registry
export GITHUB_USER=your-username
export GITHUB_TOKEN=ghp_yourtoken

ksail cluster init \
  --mirror-registry '${GITHUB_USER}:${GITHUB_TOKEN}@ghcr.io=https://ghcr.io'

# Using Docker Hub to avoid rate limits
export DOCKER_USER=your-username
export DOCKER_TOKEN=your-token

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. The registry proxy will authenticate to the upstream registry using the provided credentials, preventing rate limit issues for unauthenticated requests.

How it works:

1. KSail creates a local pull-through cache registry container for each mirror
2. Credentials are resolved from environment variables at runtime
3. The registry authenticates to the upstream using REGISTRY_PROXY_USERNAME and REGISTRY_PROXY_PASSWORD
4. Images are pulled through the authenticated mirror, avoiding rate limits
5. Cached images persist across cluster restarts for faster subsequent pulls

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

AI Chat Assistant

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

ksail chat

Capabilities:

• Guided configuration – Get recommendations for distributions, CNI, and other settings
• Troubleshooting – Diagnose cluster issues with AI assistance
• Command execution – Run KSail commands with your approval
• Context-aware – Understands your ksail.yaml and project structure

Prerequisites: Requires GitHub Copilot CLI installed and authenticated.

Commands: ksail chat

VSCode Extension

Manage KSail clusters directly from Visual Studio Code with an integrated extension that provides cluster management, interactive wizards, and AI assistant integration.

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

Capabilities:

• Clusters sidebar view — View and manage clusters with status indicators (running/stopped)
• Interactive wizards — Step-by-step configuration for cluster init and create operations
• Command palette — Full access to all cluster lifecycle commands
• Keyboard shortcuts — Quick access to common operations (Cmd+Shift+K prefix)
• Smart context menus — Right-click actions based on cluster state
• MCP server provider — Exposes KSail as an MCP server for AI assistants

Features:

Feature	Description
Cluster tree view	Shows all clusters with provider and status info
Init wizard	Multi-step configuration for new clusters
Create wizard	Guided cluster creation with component selection
Command shortcuts	Cmd+Shift+K I (init), C (create), D (delete)
K9s integration	Open cluster in K9s terminal UI
MCP integration	Use KSail with Copilot and other AI tools

Prerequisites:

• KSail CLI installed and in PATH
• Docker running (for cluster operations)
• K9s (optional, for cluster connection)

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