KSail is a CLI tool that bundles common Kubernetes tooling into a single binary. It provides one consistent interface to create clusters, deploy workloads, and operate cloud-native stacks across different distributions and providers.
Setting up and operating Kubernetes clusters is a skill of its own, often requiring juggling multiple CLI tools, writing bespoke scripts, and dealing with inconsistent developer workflows, all determined by the specific project. This complexity and inconsistency slow down development, make Kubernetes hard for newcomers, and make it difficult to maintain reproducible environments and ways of working. KSail removes the tooling overhead so you can focus on your workloads.
- 📦 One Binary — Embeds cluster provisioning, GitOps engines, and deployment tooling. No tool sprawl.
- ☸️ Simple Clusters — Spin up Vanilla, K3s, or Talos clusters with one command. Same workflow across distributions.
- 📄 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.
- 🤖 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.
KSail works on all major operating systems and CPU architectures:
| OS | Architecture |
|---|---|
| 🐧 Linux | amd64, arm64 |
| macOS | arm64 |
| ⊞ Windows (untested) | amd64, arm64 |
Docker is required for local clusters. Install Docker Desktop/Engine and ensure docker ps works.
Supported distributions run on different infrastructure providers:
| Provider | Vanilla | K3s | Talos |
|---|---|---|---|
| Docker | ✅ (Kind) | ✅ (K3d) | ✅ |
| Hetzner | — | — | ✅ |
Note
If you want to see more distributions or providers supported, please consider sponsoring development via GitHub Sponsors. Testing and maintaining distribution x cloud provider support comes with additional financial costs for me, so sponsorships help make that feasible.
Talos on Hetzner is supported because I use it for my personal homelab, and so the support is maintained as part of my own platform work.
See the Installation Guide for detailed installation instructions.
For VSCode users, install the KSail extension to manage clusters directly from your editor. See the extension documentation for features and usage.
# 1. Initialize a new project with your preferred stack
ksail cluster init \
--name <cluster-name> \
--distribution <Vanilla|K3s|Talos> \
--cni <Default|Cilium|Calico> \
--csi <Default|Enabled|Disabled> \
--metrics-server <Default|Enabled|Disabled> \
--cert-manager <Enabled|Disabled> \
--policy-engine <None|Kyverno|Gatekeeper> \
--gitops-engine <None|Flux|ArgoCD> \
--mirror-registry <host>=<upstream>
# 2. Create and start the cluster
ksail cluster create
# 3. Add your manifests to the k8s/ directory
# 4. Deploy your workloads
ksail workload apply -k ./k8s # kubectl workflow
ksail workload reconcile # gitops workflow
# 5. Connect to the cluster with K9s
ksail cluster connectBrowse the documentation at https://ksail.devantler.tech (GitHub Pages)
Contributions are welcome! Please read CONTRIBUTING.md for details on our development process, coding standards, and how to submit pull requests.
KSail is a powerful tool that can be used in many different ways. Here are some projects that use KSail in their setup:
| Project | Description | Type |
|---|---|---|
| devantler-tech/platform | My personal homelab | Platform |
If you use KSail in your project, feel free to open a PR to add it to the list, so others can see how you use KSail.
- KSail - a Kubernetes SDK for local GitOps development and CI - A presentation on KSail at KCD2024 (Early version of KSail that was built in .NET).
- Local Kubernetes Development with KSail and Kind
- Local Kubernetes Development with KSail and K3d
- Local Kubernetes Development with KSail and Talos
- Creating Kubernetes Clusters on Hetzner with KSail and Talos
- AI-first TUI for KSail with Copilot SDK and Bubbletea