Skip to content
Nikolai Emil | Devantler
Blog

Local Kubernetes Development with KSail and Talos

KSail with Talos
Nikolai Emil Damm
Nikolai Emil Damm
Developer Experience Engineer

Talos Linux is a minimal, immutable operating system designed specifically for Kubernetes. While it’s often used in production environments, you can also run Talos locally in Docker for development. Combined with KSail, you get a security-focused local development experience. This post shows you how.

Why Talos + KSail?

Section titled “Why Talos + KSail?”

Talos Linux takes a radically different approach to running Kubernetes. There’s no SSH, no shell, no package manager — just the Talos API and Kubernetes. The entire OS is immutable and managed declaratively via configuration files.

This approach provides:

  • Minimal attack surface — No shell means no shell exploits
  • No configuration drift — Immutable OS prevents unauthorized changes
  • Declarative everything — OS configuration is versioned and reproducible
  • Production parity — Your local environment matches production Talos clusters

KSail wraps Talos tooling into a single binary, handling cluster provisioning, GitOps setup, and workload management through one consistent interface.

Prerequisites

Section titled “Prerequisites”

You need Docker installed and running. Verify with:

Terminal window
docker ps

If this command works, you’re ready to go.

Step 1: Install KSail

Section titled “Step 1: Install KSail”

KSail is distributed as a single binary. Install via Homebrew:

Terminal window
brew install --cask devantler-tech/tap/ksail

Or with Go:

Terminal window
go install github.com/devantler-tech/ksail/v5@latest

Verify the installation:

Terminal window
ksail --version

Step 2: Scaffold Your Cluster Project

Section titled “Step 2: Scaffold Your Cluster Project”

KSail’s init command scaffolds a complete project structure. For a Talos cluster with Cilium CNI:

Terminal window
mkdir my-cluster && cd my-cluster
ksail cluster init --distribution Talos --cni Cilium

This creates ksail.yaml (cluster configuration), talos/ (Talos configs), and k8s/ (your Kubernetes manifests).

For all available flags and configuration options, see the KSail documentation:

Step 3: Create the Cluster

Section titled “Step 3: Create the Cluster”

Create and start your cluster:

Terminal window
ksail cluster create

This command:

  1. Creates Docker containers running Talos Linux
  2. Bootstraps the Talos control plane
  3. Initializes etcd and the Kubernetes API server
  4. Installs your selected CNI, CSI, and other components
  5. Configures your local kubeconfig and talosconfig

The process takes 1-2 minutes. Talos clusters take slightly longer than Kind or K3d because of the additional bootstrap steps for the immutable OS.

Step 4: Working with Your Cluster

Section titled “Step 4: Working with Your Cluster”

Once your cluster is running, KSail provides commands for common operations:

Terminal window
ksail cluster info      # Show cluster status
ksail cluster list      # List all KSail-managed clusters
ksail cluster connect   # Open K9s for interactive management
ksail cluster stop      # Stop the cluster
ksail cluster start     # Start a stopped cluster

Your kubeconfig is automatically configured, so standard kubectl commands work too.

For the full command reference, see Cluster Commands.

Step 5: Deploying Workloads

Section titled “Step 5: Deploying Workloads”

KSail wraps kubectl and GitOps operations under the workload command:

Terminal window
ksail workload apply -k ./k8s    # Apply manifests (kubectl workflow)
ksail workload push              # Push to GitOps source
ksail workload reconcile         # Trigger GitOps reconciliation

For the full workload command reference, see Workload Commands.

Cleaning Up

Section titled “Cleaning Up”

When you’re done:

Terminal window
ksail cluster delete

This removes the Docker containers and cleans up kubeconfig and talosconfig entries.

What’s Next

Section titled “What’s Next”

Explore the KSail documentation for advanced topics including:

  • Multi-node Talos clusters for testing HA scenarios
  • Enabling GitOps with Flux or ArgoCD
  • Secret management with SOPS
  • Mirror registries to avoid Docker Hub rate limits

Once you’re comfortable with Talos locally, you can deploy to cloud infrastructure. See Creating Development Clusters on Hetzner with KSail and Talos for a guide on running Talos in the cloud.

For simpler local setups, check out Kind with KSail for vanilla Kubernetes or K3s with KSail for a batteries-included experience.

Feedback Welcome

Section titled “Feedback Welcome”

KSail is under active development. If you encounter bugs or find missing features, please open an issue on GitHub. Your feedback helps improve the tool for everyone.

This blog post was written with the assistance of GitHub Copilot and Claude Opus 4.5.

Tags: