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 supported distributions and providers.
π Everything as Code β Cluster settings, distribution configs, and workloads all live in version-controlled files.
π GitOps Native β Opt into Flux or ArgoCD. KSail handles the bootstrap and gives you push and reconcile commands.
βοΈ Customizable Stack β Select your CNI, CSI, policy engine, cert-manager, and mirror registries to match your setup.
π SOPS Built In β Encrypt, decrypt, and edit secrets with integrated cipher commands.
The binary works on all major operating systems and modern CPU architectures:
| OS | Arch |
|---|---|
| π§ Linux | amd64 and arm64 |
| ο£Ώ MacOS | arm64 |
| β Windows (untested) | amd64 and arm64 |
Docker is required to create local clusters (the Docker provider). Install Docker Desktop/Engine and ensure docker ps works.
The supported distributions (x-axis) run on different infrastructure providers (y-axis). You need to have access to at least one provider for your chosen distribution for KSail to create and manage the cluster.
| 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.
# 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|LocalPathStorage> \
--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)
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