README
ΒΆ
π₯οΈπ³ KSail
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.
Why?
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.
Key Features
π¦ One Binary β Embeds cluster provisioning, GitOps engines, and deployment tooling. No tool sprawl.
βΈοΈ Simple Clusters β Spin up Kind, K3d, 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, enable cert-manager, add mirror registries to match your setup.
π SOPS Built In β Encrypt, decrypt, and edit secrets with integrated cipher commands.
Getting Started
Prerequisites
The binary works on all major operating systems and modern CPU archectures:
| OS | Arch |
|---|---|
| π§ Linux | amd64 and arm64 |
| ο£Ώ MacOS | arm64 |
| β Windows (untested) | amd64 and arm64 |
The supported distributions depend on different local and cloud providers:
| Distribution | Provider |
|---|---|
| Kind | Docker |
| K3d | Docker |
| Talos | Docker, Hetzner (π§ next) |
| EKS | Docker (π§ next) |
Installation
Homebrew
brew install --cask devantler-tech/tap/ksail
Go install
go install github.com/devantler-tech/ksail/v5@latest
Usage
Get up and running with a simple kind cluster in four steps:
# 1. Initialize a new project with your preferred stack
ksail cluster init
# 2. Create and start the cluster
ksail cluster create
# Add your manifests to the k8s/kustomization.yaml file
# 3. Deploy your workloads
ksail workload apply -k ./k8s
# 4. Connect to the cluster with k9s
ksail cluster connect
Documentation
For users
- Browse the documentation in
docs/(Markdown) or on https://ksail.devantler.tech (GitHub Pages).
For contributors
- CONTRIBUTING.md β Contribution guide, development prerequisites, and workflows
- API Documentation β Go package documentation
Related Projects
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.
Presentations
- 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).
Star History
Documentation
Source Files
Directories
ΒΆ
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
apis/cluster/v1alpha1
Package v1alpha1 provides model definitions for a KSail cluster.
|
Package v1alpha1 provides model definitions for a KSail cluster. |
|
cli
Package cli provides reusable helpers for command wiring and execution.
|
Package cli provides reusable helpers for command wiring and execution. |
|
cli/cmd
Package cmd provides the command-line interface for KSail.
|
Package cmd provides the command-line interface for KSail. |
|
cli/cmd/cipher
Package cipher provides the cipher command for integrating with SOPS.
|
Package cipher provides the cipher command for integrating with SOPS. |
|
cli/cmd/cluster
Package cluster groups all KSail cluster lifecycle Cobra commands under a single namespace.
|
Package cluster groups all KSail cluster lifecycle Cobra commands under a single namespace. |
|
cli/cmd/workload
Package workload provides the workload command namespace.
|
Package workload provides the workload command namespace. |
|
cli/cmd/workload/gen
Package gen provides the gen command namespace for generating Kubernetes resources.
|
Package gen provides the gen command namespace for generating Kubernetes resources. |
|
cli/create
Package create provides helpers for cluster creation workflows.
|
Package create provides helpers for cluster creation workflows. |
|
cli/create/registrystage
Package registrystage provides registry setup and connection stages for cluster creation.
|
Package registrystage provides registry setup and connection stages for cluster creation. |
|
cli/docker
Package docker provides Docker client lifecycle management for CLI commands.
|
Package docker provides Docker client lifecycle management for CLI commands. |
|
cli/editor
Package editor provides editor configuration resolution for CLI commands.
|
Package editor provides editor configuration resolution for CLI commands. |
|
cli/flags
Package flags provides flag handling utilities for CLI commands.
|
Package flags provides flag handling utilities for CLI commands. |
|
cli/kubeconfig
Package kubeconfig provides kubeconfig path resolution utilities.
|
Package kubeconfig provides kubeconfig path resolution utilities. |
|
cli/lifecycle
Package lifecycle provides cluster lifecycle command helpers.
|
Package lifecycle provides cluster lifecycle command helpers. |
|
cli/parallel
Package parallel provides utilities for executing independent operations concurrently with controlled parallelism using errgroup and semaphore.
|
Package parallel provides utilities for executing independent operations concurrently with controlled parallelism using errgroup and semaphore. |
|
cli/runner
Package runner provides helpers for executing Cobra commands while capturing output.
|
Package runner provides helpers for executing Cobra commands while capturing output. |
|
cli/ui
Package ui provides user interface components for KSail CLI.
|
Package ui provides user interface components for KSail CLI. |
|
cli/ui/asciiart
Package asciiart provides ASCII art printing functionality for KSail.
|
Package asciiart provides ASCII art printing functionality for KSail. |
|
cli/ui/error-handler
Package errorhandler centralizes Cobra command execution with KSail's error formatting rules.
|
Package errorhandler centralizes Cobra command execution with KSail's error formatting rules. |
|
cli/ui/notify
Package notify provides utilities for sending notifications to the user.
|
Package notify provides utilities for sending notifications to the user. |
|
cli/ui/timer
Package timer provides timing functionality for tracking command execution duration.
|
Package timer provides timing functionality for tracking command execution duration. |
|
client/argocd
Package argocd provides Argo CD GitOps integration for KSail-Go.
|
Package argocd provides Argo CD GitOps integration for KSail-Go. |
|
client/docker
Package docker provides client wrappers for Docker Engine API operations.
|
Package docker provides client wrappers for Docker Engine API operations. |
|
client/flux
Package flux provides a Flux client implementation using Flux Kubernetes APIs.
|
Package flux provides a Flux client implementation using Flux Kubernetes APIs. |
|
client/helm
Package helm provides client helpers for interacting with Helm in KSail.
|
Package helm provides client helpers for interacting with Helm in KSail. |
|
client/k9s
Package k9s provides a K9s client implementation.
|
Package k9s provides a K9s client implementation. |
|
client/kubeconform
Package kubeconform provides a client for validating Kubernetes manifests using kubeconform.
|
Package kubeconform provides a client for validating Kubernetes manifests using kubeconform. |
|
client/kubectl
Package kubectl provides a kubectl client implementation.
|
Package kubectl provides a kubectl client implementation. |
|
client/kustomize
Package kustomize provides a client for building Kubernetes manifests using kustomize.
|
Package kustomize provides a client for building Kubernetes manifests using kustomize. |
|
client/oci
Package oci provides OCI artifact management for Kubernetes workloads.
|
Package oci provides OCI artifact management for Kubernetes workloads. |
|
di
Package di exposes shared dependency injection helpers for KSail commands.
|
Package di exposes shared dependency injection helpers for KSail commands. |
|
io
Package io provides utilities for input and output operations.
|
Package io provides utilities for input and output operations. |
|
io/config-manager
Package configmanager provides centralized configuration management for KSail.
|
Package configmanager provides centralized configuration management for KSail. |
|
io/config-manager/helpers
Package helpers provides common functionality for config managers to eliminate duplication.
|
Package helpers provides common functionality for config managers to eliminate duplication. |
|
io/config-manager/k3d
Package k3d provides configuration management for K3d clusters.
|
Package k3d provides configuration management for K3d clusters. |
|
io/config-manager/kind
Package kind provides configuration management for Kind clusters.
|
Package kind provides configuration management for Kind clusters. |
|
io/config-manager/ksail
Package configmanager provides configuration management for KSail v1alpha1.Cluster configurations.
|
Package configmanager provides configuration management for KSail v1alpha1.Cluster configurations. |
|
io/config-manager/talos
Package talos provides configuration management for Talos cluster patches.
|
Package talos provides configuration management for Talos cluster patches. |
|
io/detector
Package detector provides utilities for detecting existing Kubernetes resources in the source directory, such as GitOps Custom Resources managed by KSail.
|
Package detector provides utilities for detecting existing Kubernetes resources in the source directory, such as GitOps Custom Resources managed by KSail. |
|
io/generator
Package generator provides an interface for generating files from code.
|
Package generator provides an interface for generating files from code. |
|
io/generator/argocd
Package argocd provides generators for ArgoCD GitOps resources.
|
Package argocd provides generators for ArgoCD GitOps resources. |
|
io/generator/flux
Package flux provides generators for Flux GitOps resources.
|
Package flux provides generators for Flux GitOps resources. |
|
io/generator/k3d
Package k3dgenerator provides utilities for generating K3d cluster configurations.
|
Package k3dgenerator provides utilities for generating K3d cluster configurations. |
|
io/generator/kind
Package kindgenerator provides utilities for generating Kind cluster configurations.
|
Package kindgenerator provides utilities for generating Kind cluster configurations. |
|
io/generator/kustomization
Package kustomizationgenerator provides utilities for generating kustomization.yaml files.
|
Package kustomizationgenerator provides utilities for generating kustomization.yaml files. |
|
io/generator/talos
Package talosgenerator provides a generator for Talos project scaffolding.
|
Package talosgenerator provides a generator for Talos project scaffolding. |
|
io/generator/yaml
Package yamlgenerator provides YAML generation functionality for arbitrary models.
|
Package yamlgenerator provides YAML generation functionality for arbitrary models. |
|
io/marshaller
Package marshaller provides functionality for marshaling and unmarshaling resources.
|
Package marshaller provides functionality for marshaling and unmarshaling resources. |
|
io/marshaller/yaml
Package yamlmarshaller provides functionality for marshaling and unmarshaling YAML documents.
|
Package yamlmarshaller provides functionality for marshaling and unmarshaling YAML documents. |
|
io/scaffolder
Package scaffolder provides utilities for scaffolding KSail project files and configuration.
|
Package scaffolder provides utilities for scaffolding KSail project files and configuration. |
|
io/validator
Package validator provides interfaces for configuration file validation.
|
Package validator provides interfaces for configuration file validation. |
|
io/validator/k3d
Package k3d provides K3d configuration validation functionality.
|
Package k3d provides K3d configuration validation functionality. |
|
io/validator/kind
Package kind provides Kind configuration validation functionality.
|
Package kind provides Kind configuration validation functionality. |
|
io/validator/ksail
Package ksail provides validation for KSail cluster configurations.
|
Package ksail provides validation for KSail cluster configurations. |
|
io/validator/metadata
Package metadata provides shared metadata validation utilities used across multiple validators.
|
Package metadata provides shared metadata validation utilities used across multiple validators. |
|
k8s
Package k8s provides Kubernetes utilities for resource management and readiness checking.
|
Package k8s provides Kubernetes utilities for resource management and readiness checking. |
|
svc/installer
Package installer provides functionality for installing and uninstalling components.
|
Package installer provides functionality for installing and uninstalling components. |
|
svc/installer/argocd
Package argocdinstaller installs Argo CD via Helm.
|
Package argocdinstaller installs Argo CD via Helm. |
|
svc/installer/cert-manager
Package certmanagerinstaller installs cert-manager via Helm.
|
Package certmanagerinstaller installs cert-manager via Helm. |
|
svc/installer/cni
Package cni provides unified CNI installer implementations and shared utilities for managing CNI providers on Kubernetes clusters.
|
Package cni provides unified CNI installer implementations and shared utilities for managing CNI providers on Kubernetes clusters. |
|
svc/installer/cni/calico
Package calicoinstaller provides an installer for installing Calico CNI on a Kubernetes cluster.
|
Package calicoinstaller provides an installer for installing Calico CNI on a Kubernetes cluster. |
|
svc/installer/cni/cilium
Package ciliuminstaller provides an installer for installing Cilium CNI on a Kubernetes cluster.
|
Package ciliuminstaller provides an installer for installing Cilium CNI on a Kubernetes cluster. |
|
svc/installer/flux
Package fluxinstaller provides an installer for installing Flux on a Kubernetes cluster.
|
Package fluxinstaller provides an installer for installing Flux on a Kubernetes cluster. |
|
svc/installer/localpathstorage
Package localpathstorageinstaller provides installation of Rancher Local Path Provisioner for Kind clusters.
|
Package localpathstorageinstaller provides installation of Rancher Local Path Provisioner for Kind clusters. |
|
svc/installer/metrics-server
Package metricsserverinstaller provides an installer for installing metrics-server on a Kubernetes cluster.
|
Package metricsserverinstaller provides an installer for installing metrics-server on a Kubernetes cluster. |
|
svc/provisioner/cluster
Package clusterprovisioner provides implementations of the ClusterProvisioner interface for provisioning clusters in different providers.
|
Package clusterprovisioner provides implementations of the ClusterProvisioner interface for provisioning clusters in different providers. |
|
svc/provisioner/cluster/k3d
Package k3dprovisioner contains the K3d cluster provisioner and its client provider interfaces.
|
Package k3dprovisioner contains the K3d cluster provisioner and its client provider interfaces. |
|
svc/provisioner/cluster/kind
Package kindprovisioner provides implementations of the ClusterProvisioner interface for provisioning Kind clusters.
|
Package kindprovisioner provides implementations of the ClusterProvisioner interface for provisioning Kind clusters. |
|
svc/provisioner/cluster/talos
Package talosprovisioner provides implementations of the ClusterProvisioner interface for provisioning Talos-in-Docker clusters.
|
Package talosprovisioner provides implementations of the ClusterProvisioner interface for provisioning Talos-in-Docker clusters. |
|
svc/provisioner/registry
Package registry centralizes all registry lifecycle helpers that KSail-Go needs for local development clusters.
|
Package registry centralizes all registry lifecycle helpers that KSail-Go needs for local development clusters. |
Click to show internal directories.
Click to hide internal directories.