ksail

command module
v5.31.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 12, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

README

License Go Reference codecov CI - KSail

🛥️🐳 KSail

ksail

KSail is a tool that bundles common Kubernetes tooling into a single binary. It provides a VSCode Extension, CLI, AI-Enabled Chat TUI or MCP interface to create clusters, deploy workloads, and operate cloud-native stacks across different distributions and providers.

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 Vanilla, K3s, or Talos clusters with one command. Same workflow across distributions.
  • 📥 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.
  • 🤖 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.

Getting Started

Prerequisites

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.

Installation

See the Installation Guide for detailed installation instructions.

VSCode Extension

For VSCode users, install the KSail extension to manage clusters directly from your editor. See the extension documentation for features and usage.

Usage

ksail-mental-model

# 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. Update cluster configuration (modify ksail.yaml, then run)
ksail cluster update            # Apply configuration changes

# 6. Connect to the cluster with K9s
ksail cluster connect

Documentation

Browse the documentation at https://ksail.devantler.tech (GitHub Pages)

Contributing

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.

Presentations

Blog Posts

Star History

Star History Chart

Documentation

Overview

Package main is the entry point for the KSail application.

Source Files

View all Source files

Directories

Path Synopsis
pkg
apis
Package apis provides API type definitions for KSail resources.
 Package apis provides API type definitions for KSail resources.
apis/cluster
Package cluster provides cluster configuration API types.
 Package cluster provides cluster configuration API types.
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/annotations
Package annotations provides constants for annotating Cobra commands to control AI tool generation, permission requirements, and command consolidation.
 Package annotations provides constants for annotating Cobra commands to control AI tool generation, permission requirements, and command consolidation.
cli/cmd
Package cmd provides the command-line interface for KSail.
 Package cmd provides the command-line interface for KSail.
cli/cmd/chat
Package chat implements the AI-assisted chat command.
 Package chat implements the AI-assisted chat command.
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/mcp
Package mcp implements the MCP server command.
 Package mcp implements the MCP server command.
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/dockerutil
Package dockerutil provides Docker client lifecycle management utilities.
 Package dockerutil provides Docker client lifecycle management utilities.
cli/editor
Package editor provides editor configuration resolution with proper precedence.
 Package editor provides editor configuration resolution with proper precedence.
cli/flags
Package flags provides CLI flag handling utilities including benchmark timing.
 Package flags provides CLI flag handling utilities including benchmark timing.
cli/kubeconfig
Package kubeconfig provides helpers for resolving kubeconfig file paths.
 Package kubeconfig provides helpers for resolving kubeconfig file paths.
cli/lifecycle
Package lifecycle provides cluster lifecycle command helpers.
 Package lifecycle provides cluster lifecycle command helpers.
cli/setup
Package setup provides helpers for cluster creation and setup workflows.
 Package setup provides helpers for cluster creation and setup workflows.
cli/setup/localregistry
Package localregistry provides local registry lifecycle operations for cluster commands.
 Package localregistry provides local registry lifecycle operations for cluster commands.
cli/setup/mirrorregistry
Package mirrorregistry provides mirror registry setup and connection stages for cluster creation.
 Package mirrorregistry provides mirror registry setup and connection stages for cluster creation.
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/chat
Package chat provides an interactive Bubbletea TUI for conversing with GitHub Copilot.
 Package chat provides an interactive Bubbletea TUI for conversing with GitHub Copilot.
cli/ui/confirm
Package confirm provides confirmation prompt utilities for destructive operations.
 Package confirm provides confirmation prompt utilities for destructive operations.
cli/ui/errorhandler
Package errorhandler centralizes Cobra command execution with KSail's error formatting rules.
 Package errorhandler centralizes Cobra command execution with KSail's error formatting rules.
client
Package client provides embedded Kubernetes and container tool clients.
 Package client provides embedded Kubernetes and container tool clients.
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/netretry
Package netretry provides shared retry utilities for transient network errors across Kubernetes client packages (Docker, Helm, etc.).
 Package netretry provides shared retry utilities for transient network errors across Kubernetes client packages (Docker, Helm, etc.).
client/oci
Package oci provides OCI artifact management for Kubernetes workloads.
 Package oci provides OCI artifact management for Kubernetes workloads.
client/reconciler
Package reconciler provides a common base for GitOps reconciliation clients.
 Package reconciler provides a common base for GitOps reconciliation clients.
di
Package di exposes shared dependency injection helpers for KSail commands.
 Package di exposes shared dependency injection helpers for KSail commands.
envvar
Package envvar provides utilities for working with environment variables.
 Package envvar provides utilities for working with environment variables.
fsutil
Package fsutil provides utilities for filesystem operations.
 Package fsutil provides utilities for filesystem operations.
fsutil/configmanager
Package configmanager provides centralized configuration management for KSail.
 Package configmanager provides centralized configuration management for KSail.
fsutil/configmanager/k3d
Package k3d provides configuration management for K3d clusters.
 Package k3d provides configuration management for K3d clusters.
fsutil/configmanager/kind
Package kind provides configuration management for Kind clusters.
 Package kind provides configuration management for Kind clusters.
fsutil/configmanager/ksail
Package configmanager provides configuration management for KSail v1alpha1.Cluster configurations.
 Package configmanager provides configuration management for KSail v1alpha1.Cluster configurations.
fsutil/configmanager/loader
Package loader provides common functionality for config managers to eliminate duplication.
 Package loader provides common functionality for config managers to eliminate duplication.
fsutil/configmanager/talos
Package talos provides configuration management for Talos cluster patches.
 Package talos provides configuration management for Talos cluster patches.
fsutil/generator
Package generator provides an interface for generating files from code.
 Package generator provides an interface for generating files from code.
fsutil/generator/argocd
Package argocd provides generators for ArgoCD GitOps resources.
 Package argocd provides generators for ArgoCD GitOps resources.
fsutil/generator/flux
Package flux provides generators for Flux GitOps resources.
 Package flux provides generators for Flux GitOps resources.
fsutil/generator/k3d
Package k3dgenerator provides utilities for generating K3d cluster configurations.
 Package k3dgenerator provides utilities for generating K3d cluster configurations.
fsutil/generator/kind
Package kindgenerator provides utilities for generating Kind cluster configurations.
 Package kindgenerator provides utilities for generating Kind cluster configurations.
fsutil/generator/kustomization
Package kustomizationgenerator provides utilities for generating kustomization.yaml files.
 Package kustomizationgenerator provides utilities for generating kustomization.yaml files.
fsutil/generator/talos
Package talosgenerator provides a generator for Talos project scaffolding.
 Package talosgenerator provides a generator for Talos project scaffolding.
fsutil/generator/yaml
Package yamlgenerator provides YAML generation functionality for arbitrary models.
 Package yamlgenerator provides YAML generation functionality for arbitrary models.
fsutil/marshaller
Package marshaller provides functionality for marshaling and unmarshaling resources.
 Package marshaller provides functionality for marshaling and unmarshaling resources.
fsutil/scaffolder
Package scaffolder provides utilities for scaffolding KSail project files and configuration.
 Package scaffolder provides utilities for scaffolding KSail project files and configuration.
fsutil/validator
Package validator provides interfaces for configuration file validation.
 Package validator provides interfaces for configuration file validation.
fsutil/validator/k3d
Package k3d provides K3d configuration validation functionality.
 Package k3d provides K3d configuration validation functionality.
fsutil/validator/kind
Package kind provides Kind configuration validation functionality.
 Package kind provides Kind configuration validation functionality.
fsutil/validator/ksail
Package ksail provides validation for KSail cluster configurations.
 Package ksail provides validation for KSail cluster configurations.
k8s
Package k8s provides Kubernetes client configuration and general-purpose utilities.
 Package k8s provides Kubernetes client configuration and general-purpose utilities.
k8s/readiness
Package readiness provides Kubernetes resource readiness polling utilities.
 Package readiness provides Kubernetes resource readiness polling utilities.
notify
Package notify provides utilities for sending formatted notifications to CLI users.
 Package notify provides utilities for sending formatted notifications to CLI users.
runner
Package runner provides helpers for executing Cobra commands while capturing output.
 Package runner provides helpers for executing Cobra commands while capturing output.
svc
Package svc provides service layer components for KSail.
 Package svc provides service layer components for KSail.
svc/chat
Package chat provides services for the AI chat assistant feature.
 Package chat provides services for the AI chat assistant feature.
svc/detector
Package detector detects installed Kubernetes components by querying the cluster via Helm release history and Kubernetes API.
 Package detector detects installed Kubernetes components by querying the cluster via Helm release history and Kubernetes API.
svc/detector/cluster
Package cluster detects Kubernetes cluster distribution, provider, and other attributes by analyzing kubeconfig contexts and server endpoints.
 Package cluster detects Kubernetes cluster distribution, provider, and other attributes by analyzing kubeconfig contexts and server endpoints.
svc/detector/gitops
Package gitops provides utilities for detecting existing Kubernetes resources in the source directory, such as GitOps Custom Resources managed by KSail.
 Package gitops provides utilities for detecting existing Kubernetes resources in the source directory, such as GitOps Custom Resources managed by KSail.
svc/diff
Package diff provides a DiffEngine that computes configuration differences between old and new ClusterSpec values and classifies their update impact into in-place, reboot-required, and recreate-required categories.
 Package diff provides a DiffEngine that computes configuration differences between old and new ClusterSpec values and classifies their update impact into in-place, reboot-required, and recreate-required categories.
svc/image
Package image provides services for exporting and importing container images to and from Kubernetes cluster containerd runtimes.
 Package image provides services for exporting and importing container images to and from Kubernetes cluster containerd runtimes.
svc/image/parser
Package parser provides utilities for parsing container image references from Dockerfiles.
 Package parser provides utilities for parsing container image references from Dockerfiles.
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/certmanager
Package certmanagerinstaller installs cert-manager via Helm.
 Package certmanagerinstaller installs cert-manager via Helm.
svc/installer/cloudproviderkind
Package cloudproviderkindinstaller provides a Helm-based installer for Cloud Provider KIND.
 Package cloudproviderkindinstaller provides a Helm-based installer for Cloud Provider KIND.
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/gatekeeper
Package gatekeeperinstaller installs Gatekeeper via Helm.
 Package gatekeeperinstaller installs Gatekeeper via Helm.
svc/installer/hetznercsi
Package hetznercsiinstaller installs the Hetzner Cloud CSI driver via Helm.
 Package hetznercsiinstaller installs the Hetzner Cloud CSI driver via Helm.
svc/installer/internal/helmutil
Package helmutil provides shared helpers for Helm-based installer packages.
 Package helmutil provides shared helpers for Helm-based installer packages.
svc/installer/kubeletcsrapprover
Package kubeletcsrapproverinstaller provides an installer for kubelet-csr-approver on a Kubernetes cluster.
 Package kubeletcsrapproverinstaller provides an installer for kubelet-csr-approver on a Kubernetes cluster.
svc/installer/kyverno
Package kyvernoinstaller installs Kyverno via Helm.
 Package kyvernoinstaller installs Kyverno via Helm.
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/metallb
Package metallbinstaller installs MetalLB via Helm.
 Package metallbinstaller installs MetalLB via Helm.
svc/installer/metricsserver
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/mcp
Package mcp provides an MCP server for exposing KSail commands as tools.
 Package mcp provides an MCP server for exposing KSail commands as tools.
svc/provider
Package provider defines infrastructure providers for running Kubernetes cluster nodes.
 Package provider defines infrastructure providers for running Kubernetes cluster nodes.
svc/provider/docker
Package docker provides a Docker-based infrastructure provider.
 Package docker provides a Docker-based infrastructure provider.
svc/provider/hetzner
Package hetzner implements provider.Provider for Hetzner Cloud servers.
 Package hetzner implements provider.Provider for Hetzner Cloud servers.
svc/provisioner
Package provisioner provides cluster and registry provisioning services.
 Package provisioner provides cluster and registry provisioning services.
svc/provisioner/cluster
Package clusterprovisioner provides cluster provisioning for KSail distributions.
 Package clusterprovisioner provides cluster provisioning for KSail distributions.
svc/provisioner/cluster/clustererr
Package clustererr provides common error types for cluster provisioners.
 Package clustererr provides common error types for cluster provisioners.
svc/provisioner/cluster/clusterupdate
Package clusterupdate provides shared types for cluster update operations.
 Package clusterupdate provides shared types for cluster update operations.
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.
svc/registryresolver
Package registryresolver provides OCI registry detection, resolution, and artifact push utilities.
 Package registryresolver provides OCI registry detection, resolution, and artifact push utilities.
svc/state
Package state provides cluster state persistence for distributions that cannot introspect their running configuration (Kind, K3d).
 Package state provides cluster state persistence for distributions that cannot introspect their running configuration (Kind, K3d).
timer
Package timer provides timing functionality for tracking command execution duration.
 Package timer provides timing functionality for tracking command execution duration.
toolgen
Package toolgen provides automatic tool generation from Cobra commands for AI interfaces.
 Package toolgen provides automatic tool generation from Cobra commands for AI interfaces.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.