KSail

Getting Started

Prerequisites

Note

On MacOS, you need to "Allow the default Docker socket to be used (requires password)" in Docker Desktop settings.

Show me how

KSail supports the following operating systems:

• MacOS (x64 and arm64)
• Linux (x64 and arm64)

Installation

With Homebrew:

brew tap devantler-tech/formulas
brew install ksail

Manually:

1. Download the latest release for your OS from the releases page.
2. Make the binary executable: chmod +x ksail.
3. Move the binary to a directory in your $PATH: mv ksail /usr/local/bin/ksail.

Usage

Getting started with KSail is easy. First, you need to configure what cluster you want KSail to manage.

> ksail gen config ksail - To generate a new KSail configuration file.

Now you can make changes to the configuration file to your liking, and when you are ready to initialize a new cluster, you can run:

> ksail init - To initialize a new cluster configuration based on your KSail configuration.

From there, you probably want to ensure that your distribution and ksail is configured to your liking.

• kind-config.yaml - The configuration file for Kind.
• k3d-config.yaml - The configuration file for K3d.

When you are ready to create your cluster, you can run:

> ksail up - To create your new cluster.

From there, you can make some changes to your manifest files, and when you are ready to apply them, you can run:

> ksail update - To update your cluster.

And for more advanced debugging, you can run:

> ksail debug - To debug your cluster with the K9s tool.

Finally, when you are done working with your cluster, you can run:

> ksail stop - To stop your cluster, so you can continue working on it later.

Or if you really want to get rid of it for now, you can run:

> ksail down - To dismantle your cluster and remove its resources.

Documentation

• Overview
• Configuration
• Structure
• CI
• KSail CLI
• Supported Tooling
• FAQ
• Roadmap

Sub-projects

KSail is part of a larger ecosystem of projects that I maintain. These projects are designed to provide important functionality to KSail with high confidence, and without bloating the main repository. Most the projects provide extensible frameworks, so you can build your own tools on top of them, or make contributions to make KSail even more powerful.

• devantler-tech/dotnet-cli-runner - An implementation atop CLI Wrap to support running different binaries from C# code.
• devantler-tech/dotnet-container-engine-provisioner - Provisioners to provision resources in container engines like Docker or Podman.
• devantler-tech/dotnet-secret-manager - A secret manager to manage secrets in Git in a secure way.
• devantler-tech/dotnet-keys - A library with key models, like the Age key model.
• devantler-tech/dotnet-kubernetes-generator - Generators to create Kubernetes resources with ksail init and ksail gen.
• devantler-tech/dotnet-kubernetes-provisioner - Provisioners to provision Kubernetes clusters and resources.
• devantler-tech/dotnet-kubernetes-validator - A library that validates Kubernetes resources client-side or at runtime.
• devantler-tech/dotnet-template-engine - A template engine to support code generation of non-serializable content.

CLI Wrappers

These projects are CLI wrappers that provide a C# API for the respective CLI tools. They are used in KSail to embed and interact with CLI tools in a type-safe manner.

• devantler-tech/dotnet-age-cli - A library that embeds and provides an API for the Age CLI.
• devantler-tech/dotnet-flux-cli - A library that embeds and provides an API for the Flux CLI.
• devantler-tech/dotnet-helm-cli - A library that embeds and provides an API for the Helm CLI.
• devantler-tech/dotnet-k3d-cli - A library that embeds and provides an API for the K3d CLI.
• devantler-tech/dotnet-k9s-cli - A library that embeds and provides an API for the K9s CLI.
• devantler-tech/dotnet-kind-cli - A library that embeds and provides an API for the Kind CLI.
• devantler-tech/dotnet-kubeconform-cli - A library that embeds and provides an API for the Kubeconform CLI.
• devantler-tech/dotnet-kubectl-cli - A library that embeds and provides an API for the Kubectl CLI.
• devantler-tech/dotnet-kustomize-cli - A library that embeds and provides an API for the Kustomize CLI.
• devantler-tech/dotnet-sops-cli - A library that embeds and provides an API for the SOPS CLI.

Related Projects

Note

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 is a powerful tool that can be used in many different ways. Here are some projects that use KSail in their setup:

• devantler/homelab - My personal homelab setup.

Presentations

• KSail - a Kubernetes SDK for local GitOps development and CI - A presentation on KSail at KCD2024.

Star History