k3smp

k3smp is a local Kubernetes cluster provisioning tool that creates real K3s clusters inside real virtual machines, fully automated using Multipass.

If you ever felt that running Kubernetes nodes inside Docker containers hides too many real-world details — this tool is for you.

In one sentence

k3smp is like k3d, but with real VMs, real node isolation, and a real Kubernetes topology.

Why k3smp exists

There is an excellent tool called k3d that spins up K3s clusters inside Docker containers. It is fast, clean, and perfect for disposable clusters.

However, for some use cases, running Kubernetes inside containers is not ideal:

Networking behaves differently
Node isolation is artificial
HA control plane behavior is abstracted
Kubernetes internals are hidden

So the idea behind k3smp is simple:

Provision virtual machines locally using Multipass, then install K3s directly on those VMs — automatically.

k3smp turns that idea into a fast, repeatable, and safe workflow.

What k3smp does (simple terms)

1. Analyze your host machine

Detects OS (Linux / macOS / WSL)
Checks available CPU, RAM, and disk
Calculates safe limits to avoid overloading your system

Note

k3smp refuses to create clusters that would starve your host machine.

2. Provision real virtual machines

Uses Multipass, not Docker
Each Kubernetes node runs in its own VM
Control planes and workers are fully isolated

3. Install and bootstrap K3s

First control plane initializes the cluster (--cluster-init)
Additional control planes join using the shared server token
Worker nodes join as agents
Optional components handled automatically:
- Traefik
- metrics-server
- Kubernetes dashboard

4. Generate kubeconfig

Fetches kubeconfig from the first control plane
Replaces localhost with the VM IP
Saves it locally for immediate kubectl access

Architecture overview

Example: High availability cluster

Each box represents one Multipass VM
Each VM represents one Kubernetes node

Requirements

Mandatory

Linux or macOS
Virtualization enabled in BIOS
Internet access
sudo privileges

Automatically handled

Multipass installation
kubectl installation
K3s installation

Good news

You don’t need to preinstall anything except a supported OS.

Installation

Clone the repository

Clone k3smp repository

$▊

Make the script executable

Prepare script

$▊

Quick start

Interactive wizard (recommended)

k3smp interactive wizard

$▊

This mode:

Asks configuration questions step by step
Validates host resources
Saves the configuration automatically
Creates the cluster safely

Info

This is the best entry point if you are new to Kubernetes or HA clusters.

Using a configuration file

Create a config file

Create cluster config

$▊

Create the cluster

Create cluster from config

$▊

Use the cluster

Access cluster

$▊

Cluster lifecycle commands

Cluster lifecycle

$▊

Configuration file explained

The configuration file defines what kind of cluster you want.

You can control:

Cluster topology (single / HA / custom)
Number of control planes and workers
CPU, RAM, and disk per node
K3s version
Networking configuration
Optional addons

Validation first

k3smp validates requested resources before creating anything and will warn or stop if limits are exceeded.

k3smp vs k3d

Use case	k3d	k3smp
Fast disposable clusters	✅	❌
Real node isolation	❌	✅
High availability control planes	⚠️	✅
Learning Kubernetes internals	❌	✅
Production-like local testing	❌	✅

Troubleshooting

VM creation issues

Multipass diagnostics

$▊

Danger

Network overlap can prevent pods and services from communicating correctly.

When should you use k3smp?

Use k3smp if you want:

A realistic Kubernetes lab
To learn HA control plane behavior
To test production-like setups locally
To understand Kubernetes beyond containers

If you only need fast disposable clusters, k3d remains the better choice.