ksail

KSail (ksail) is a single binary that bundles the tooling needed to create, deploy, and manage Kubernetes clusters across multiple distributions (Vanilla/Kind, K3s, Talos, VCluster) and providers. It provides a unified workflow for cluster provisioning, GitOps operations, workload deployment, and cluster lifecycle management, reducing tool sprawl by embedding provisioning utilities, GitOps engines, and deployment tooling into one interface. KSail exposes a CLI and an MCP interface to scaffold projects, scaffold clusters, manage manifests, and operate clusters, with optional AI-assisted configuration help and an integrated VSCode extension for editor-based management.

To use KSail, interact with its CLI to initialize a project, scaffold a cluster, and manage workloads. The CLI commands cover cluster initialization, creation, updates, and connections, while the built-in GitOps support (Flux or ArgoCD) handles bootstrap, push, and reconcile workflows. You can also leverage KSail’s native configuration files (kind.yaml, k3d.yaml, talos/, vcluster.yaml) to operate clusters directly with the underlying tools when desired.

Prerequisites:

• A supported operating system (Linux, macOS, or Windows with WSL2) and a supported CPU architecture (amd64 or arm64).
• Docker installed and running for local clusters.
• Go installed if you plan to build or run KSail from source.

Option A: Install a released KSail binary (recommended for most users)

1. Visit the KSail release page or install via your preferred package manager (if available).
2. Follow the platform-specific instructions to install the ksail binary.
3. Verify installation:
   • ksail version

Option B: Build KSail from source

1. Ensure Go is installed (Go 1.20+ recommended).
2. Clone the repository:
   • git clone https://github.com/devantler-tech/ksail.git
   • cd ksail
3. Build and install the binary:
   • go build ./...
   • go install ./...
4. Verify installation:
   • ksail version

Additional setup:

• Ensure Docker is running and you can execute docker ps.
• Optionally install the KSail VSCode extension for editor-based cluster management (marketplace link provided in the README).

Usage basics after installation: follow the KSail Installation Guide and the Usage section in the README to initialize a project, create clusters, add manifests, and apply workloads.

Tips and common considerations:

• KSail is designed to be distribution- and provider-agnostic, leveraging native configurations (kind.yaml, k3d.yaml, talos patches, vcluster.yaml). This means you can migrate away from KSail and use the underlying tools directly if needed.
• For GitOps workflows, you can choose between Flux and ArgoCD; KSail provides bootstrap, push, and reconcile commands to integrate with your chosen workflow.
• The AI assistant feature can help with configuration and troubleshooting within the MCP interface.
• If you encounter environment-specific issues, ensure your Docker daemon is accessible to KSail and that your PATH includes the KSail binary.
• When working with multiple cluster distributions, KSail maintains a consistent workflow across Kind, K3d, Talos, and VCluster to simplify cluster management.
• If you need to customize the stack, KSail lets you select CNI, CSI, policy engines, and mirror registries to suit your environment.
• Review the native configuration files generated by KSail (kind.yaml, k3d.yaml, talos/, vcluster.yaml) to operate clusters with the underlying tools directly when needed.