This project documents how to build a multi-node Kubernetes cluster locally on macOS using Lima and kubeadm.
The goal is to run something closer to a real cluster than tools like kind or minikube — a setup that behaves more like production Kubernetes while still running on a laptop.
All implementation details, commands, and troubleshooting notes live in the docs directory.
A reproducible local Kubernetes environment that:
- Runs on macOS using Lima virtual machines
- Uses kubeadm to bootstrap the cluster
- Uses containerd as the runtime
- Uses Cilium for networking
- Supports multiple nodes
- Behaves like a real Kubernetes cluster
This repo is intentionally focused on learning, experimentation, and hands-on cluster operations.
Most local Kubernetes tools abstract away the interesting parts.
This setup is for people who want to:
- Understand how Kubernetes actually boots
- Work with real nodes and networking
- Practice cluster operations safely
- Break and fix things locally
- Learn Kubernetes the hard way (the useful way)
It was really nice to get back into the network and virtualization side of things. We take so much for granted with the cloud. I got my start on VMware and taking apart my laptop, putting it back together, and using Virtualbox as my gateway into the world of Linux. Going back in time and refreshing my memory on layer 2 and 3 networking was really fun. I learned the history of toml. I was also kind of bored with minkube and kind - so I originally set out to do this project on Multipass.
I had nothing but problems with Multipass instability, instances stuck in an unknown state, network caches borked with partial data, required linux kernel upgrades, and let's not forget the five times I tried to set up the Calico CNI and watched the operator get completely deleted from the cluster, namespace and all, and still have pending requests and sockets open... I got it working, eventually. A course I took provided a script that I had to read line-by-line so I could test each step because it failed somewhere in the process, but I couldn't tell where because there was no output or logs. That course was greatd (most of the time - despite the repeatitive nature of the same videos reused across multiple courses). But I might have to leave the a note about that refresher course I took.
And then, I found Lima. Lima has been nothing but a perfect gentlemen this entire time. Lima uses manners, holds my door, and doesn't forget my birthday. I had never even heard of Lima, let alone know that it was a CNCF project! This was a wonderful experience for me and I look forward to the next adventure.
I intentionally chose not to add a Makefile at this stage.
The goal of this project is to understand the mechanics of cluster creation, node joins, networking, and recovery - not to hide those steps behind automation too early.
Once the workflow is well understood, automation becomes straightforward.
If you're looking for a fully automated approach, the Lima project provides excellent templates that manage the entire cluster lifecycle:
https://lima-vm.io/docs/examples/containers/kubernetes/
MIT