Skip to content
🛥️🐳 KSail
KSail CLI showing ASCII art banner and help output KSail CLI showing ASCII art banner and help output

KSail Documentation

KSail bundles Kubernetes tooling into a single CLI for cluster management and cloud-native operations.
Get Started View on GitHub

Why KSail?

Section titled “Why KSail?”

Setting up and operating Kubernetes clusters often requires juggling multiple CLI tools, writing bespoke scripts, and dealing with inconsistent workflows. KSail removes the tooling overhead so you can focus on your workloads.

Key Features

Section titled “Key Features”
  • 📦 One Binary — Embeds cluster provisioning, GitOps engines, and deployment tooling. No tool sprawl.
  • ☸️ Simple Clusters — Spin up Vanilla, K3s, Talos, or VCluster clusters with one command. Same workflow across distributions.
  • 🔓 No Lock-In — Uses native configs (kind.yaml, k3d.yaml, Talos patches, vcluster.yaml). Run clusters with or without KSail.
  • 📥 Mirror Registries — Avoid rate limits, and store images once. Same mirrors used by different clusters.
  • 📄 Everything as Code — Cluster settings, distribution configs, and workloads in version-controlled files.
  • 🔄 GitOps Native — Built-in Flux or ArgoCD support with bootstrap, push, and reconcile commands.
  • ⚙️ Customizable Stack — Select your CNI, CSI, policy engine, cert-manager, and mirror registries.
  • 🔐 SOPS Built In — Encrypt, decrypt, and edit secrets with integrated cipher commands.
  • 💾 Backup & Restore — Export cluster resources to a compressed archive and restore to any cluster with provenance labels.
  • 🤖 AI Assistant — Interactive chat powered by GitHub Copilot for configuration and troubleshooting.
  • 💻 VSCode Extension — Manage clusters from VSCode with wizards, sidebar views, and command palette.

Prerequisites

Section titled “Prerequisites”

KSail works on all major operating systems and CPU architectures:

OSArchitecture
🐧 Linuxamd64, arm64
macOSarm64
⊞ Windows (native untested; WSL2 recommended)amd64, arm64

Docker is required for local clusters. Install Docker Desktop/Engine and ensure docker ps works.

Supported distributions run on different infrastructure providers:

ProviderVanillaK3sTalosVCluster
Docker✅ (Kind)✅ (K3d)✅✅ (Vind)
Hetzner——✅—
Omni——✅—

Quick Start

Section titled “Quick Start”
Terminal window
# 1. Initialize a new project
ksail cluster init --name my-cluster --distribution Vanilla


# 2. Create and start the cluster
ksail cluster create


# 3. Add manifests to k8s/ directory


# 4. Deploy workloads
ksail workload apply -k ./k8s


# 5. Update cluster configuration (modify ksail.yaml, then run)
ksail cluster update            # Apply configuration changes


# 6. Connect with K9s
ksail cluster connect

How It Works

Section titled “How It Works”
flowchart TD
    Dev["🧑‍💻 Developer"]

    Dev -->|"edits"| Project
    Dev -->|"runs"| KSail

    subgraph Project ["📁 Project Repository"]
        Config["ksail.yaml"] ~~~ DistConfig["kind.yaml · k3d.yaml<br/>vcluster.yaml"] ~~~ Manifests["k8s/ manifests"]
    end

    KSail -->|"scaffolds & reads"| Project
    KSail -->|"provisions & operates"| Cluster

    subgraph KSail ["🛥️ KSail — One Binary"]
        CLI["CLI Commands"] ~~~ Tools["Kind · K3d · Talos · vCluster<br/>Flux · ArgoCD · SOPS<br/>Helm · Kustomize"]
    end

    subgraph Cluster ["☸️ Kubernetes Cluster"]
        Infra["CNI · CSI · Metrics<br/>Cert-Manager · Policy Engine"] ~~~ Workloads["Your Workloads ✅"]
    end

    Manifests -.->|"GitOps sync"| Workloads

    style Dev fill:#f59e0b,stroke:#d97706,color:#000
    style Project fill:#7c3aed22,stroke:#7c3aed
    style KSail fill:#10b98122,stroke:#10b981
    style Cluster fill:#3b82f622,stroke:#3b82f6
    style CLI fill:#10b981,stroke:#059669,color:#000
    style Tools fill:#065f46,stroke:#10b981,color:#fff
    style Infra fill:#1e40af,stroke:#3b82f6,color:#fff
    style Workloads fill:#166534,stroke:#22c55e,color:#fff
    style Config fill:#5b21b6,stroke:#7c3aed,color:#fff
    style DistConfig fill:#5b21b6,stroke:#7c3aed,color:#fff
    style Manifests fill:#5b21b6,stroke:#7c3aed,color:#fff

Getting Started

Section titled “Getting Started”

Installation

Install KSail and set up your environment. Learn more →

Features

Cluster provisioning, GitOps, secret management, VSCode extension, and more. Learn more →

Concepts

Kubernetes, CNI, CSI, GitOps, and related technologies. Learn more →

Architecture

Internal architecture, design decisions, and how components work together. Learn more →

Use Cases

Workflows for learning, development, and CI/CD. Learn more →

Support Matrix

Supported platforms, distributions, and components. Learn more →

Guides

Section titled “Guides”

Cluster Profiles

Pre-built templates with opinionated CNI, CSI, and GitOps settings via --profile. Learn more →

Ephemeral Clusters

Time-limited clusters that auto-destroy via --ttl for debugging and demos. Learn more →

Companion Tools

Use KSail alongside DevSpace, Telepresence, Tilt, Skaffold, and mirrord. Learn more →

KSail + mirrord

Run a local process as if it were inside the cluster with mirrord. Learn more →

Configuration

Section titled “Configuration”

Configuration Overview

Configuration sources, precedence, and when to use each. Learn more →

Declarative Configuration

Complete ksail.yaml reference. Learn more →

LoadBalancer

Configure LoadBalancer support across distributions and providers. Learn more →

Distributions

Section titled “Distributions”

Vanilla (Kind)

Standard upstream Kubernetes via Kind. Fast, Docker-only, no lock-in. Learn more →

K3s (K3d)

Lightweight K3s in Docker. Batteries-included defaults, ideal for CI/CD and resource-constrained environments. Learn more →

Talos

Immutable, API-driven OS for secure production workloads on Docker, Hetzner, or Omni. Learn more →

VCluster (Vind)

Virtual Kubernetes clusters in Docker. Ideal for multi-tenancy, feature branches, and CI isolation. Learn more →

Providers

Section titled “Providers”

Docker

Run Kubernetes nodes as Docker containers locally. Default provider for all distributions. Learn more →

Hetzner

Deploy Talos clusters on affordable Hetzner Cloud servers with real load balancers and persistent volumes. Learn more →

Omni (Sidero)

Manage Talos clusters through the Sidero Omni SaaS platform. Learn more →

Integrations

Section titled “Integrations”

VSCode Extension

Manage clusters from Visual Studio Code with wizards, sidebar views, and command palette. Learn more →

AI & Automation

Section titled “AI & Automation”

AI Chat Assistant

Interactive AI-powered chat for cluster configuration and troubleshooting. Learn more →

MCP Server

Expose KSail as an MCP server for AI assistants and automation tools. Learn more →

Help

Section titled “Help”

Development Guide

Development environment setup, coding standards, and CI/CD workflows. Learn more →

Troubleshooting

Common issues and solutions when using KSail. Learn more →

Resources

Section titled “Resources”

Resources

Presentations, tutorials, blog posts, and community projects. Learn more →