Lab it, learn it

Before you clone the repo and run vagrant up, it helps to understand what you’re actually building and why each piece exists. This post is the conceptual overview of the Vagrant Simple cluster — what the 6 VMs do, what Kubernetes concepts they map to, and why Vagrant is the right choice when infrastructure-as-code matters most.

When you’re ready to deploy, the step-by-step hands-on guide takes you from zero to a running cluster in about 6 and a half minutes. For help choosing between UTM, Vagrant, and OrbStack, see the full tool comparison.

The Architecture — 6 VMs, 5 Roles

The Simple cluster builds a complete Kubernetes environment across 6 virtual machines defined in a single Vagrantfile. Each VM runs on the QEMU provider with socket_vmnet for host-routable networking, giving you full kernel isolation with declarative infrastructure management. Here’s what each role does and why it exists.

Vault (PKI and Secrets). HashiCorp Vault manages all the TLS certificates your cluster needs. Instead of generating certificates with openssl and scattering them across nodes manually, Vault provides a proper Certificate Authority with a 3-tier hierarchy: Root CA → Intermediate CA → leaf CAs for Kubernetes, etcd, and front-proxy. This separation means a compromised etcd certificate can’t authenticate to the Kubernetes API. The Vault PKI deep dive covers the full hierarchy.

Jump (Bastion and Ansible Controller). Your Mac connects only to the jump server. Every other VM is accessed through it via SSH — the bastion server pattern used in production environments. Jump also runs Ansible (which deploys everything) and hosts the kubectl config, making it your command center for the entire cluster.

etcd (Cluster State Store). Every piece of cluster state lives in etcd — deployments, services, secrets, config maps. In the Simple setup it runs as a single node, which makes it a deliberate single point of failure. Stop etcd and the API server can’t read or write anything. That direct experience motivates the HA upgrade to a 3-node etcd cluster with quorum.

Master (Control Plane). The master runs kube-apiserver, kube-controller-manager, and kube-scheduler as systemd services. One master means one control plane failure away from losing the ability to deploy or modify anything — though existing workloads on workers keep running. The HA version adds a second master behind HAProxy.

Workers (Data Plane). Two workers run your actual workloads with containerd, kubelet, and kube-proxy. Calico CNI handles pod-to-pod networking across both workers.

What You’ll Actually Learn

Building the cluster the hard way forces you to understand how each piece connects. Here’s what becomes concrete instead of abstract.

How certificates flow between components. The API server needs a server cert, a client cert for etcd, and a separate CA for front-proxy aggregation. Each certificate has specific SANs, key usages, and TTLs. You’ll see exactly which cert goes where.

How infrastructure-as-code works in practice. The entire cluster topology lives in one Vagrantfile — VM names, IPs, resource allocations, provisioning scripts. Commit it to Git, share it with a teammate, and vagrant up produces an identical cluster. This is the core Vagrant value proposition, and a Kubernetes cluster is a compelling way to experience it.

How dual-NIC networking affects cluster configuration. Every Vagrant VM has two interfaces: eth0 (NAT for internet) and eth1 (vmnet for inter-VM communication). All cluster components must bind to eth1. Getting this wrong is the most common source of mysterious failures — nodes appear to join the cluster but can’t actually talk to each other. Understanding this dual-NIC reality prepares you for similar multi-interface challenges in cloud environments.

What kubelet actually does on a node. It’s a systemd service with a config file pointing to the API server, a client certificate, and flags controlling everything from pod CIDR to container runtime paths. Reading the unit file teaches more than any doc page.

Why etcd matters most. Stop etcd and everything stops. Not because pods crash — they keep running — but because no new state can be written. That experiment builds the intuition that etcd is the real heart of Kubernetes.

Why Vagrant Specifically

All three tools produce the same functional cluster with the same Ansible roles. The difference is what you learn alongside Kubernetes and how you manage the infrastructure.

Vagrant’s value is declarative lifecycle management. The Vagrantfile defines your entire cluster topology in one file. vagrant up --provider=qemu creates it, vagrant destroy -f tears it down. The file is version-controllable, shareable, and diffable. If you change a VM’s RAM allocation, the diff is a one-line change in Git.

Under the hood, Vagrant uses the same QEMU hypervisor as UTM. The vagrant-qemu plugin provides the provider, and socket_vmnet (from the Lima project) exposes macOS’s vmnet.framework for host-routable networking. Each VM boots its own kernel with genuine isolation — it’s full VMs, not containers or shared-kernel environments.

The tradeoff is networking complexity. Every VM gets two network interfaces (NAT + vmnet), which means every bind address in every config file must explicitly reference the vmnet IP. UTM’s single-NIC setup is cleaner. And Vagrant’s QEMU provider boots VMs slightly slower than UTM’s direct approach, so total deployment time is about 6 minutes 33 seconds versus UTM’s 5 minutes 57 seconds.

If production realism and the cleanest networking matter more, start with the UTM Simple cluster instead. If resource efficiency is the priority, the OrbStack Simple cluster uses a fraction of the RAM and disk.

What the Simple Cluster Deliberately Skips

The Simple setup has intentional single points of failure that the HA version addresses.

No HAProxy load balancer. Workers connect directly to master-1’s API server. If that master goes down, the control plane is offline.

Single etcd node. No quorum, no fault tolerance. One failure means total state loss.

One master. Control plane failure means no deployments, no scaling, no modifications — though existing pods survive on workers.

These gaps let you experience exactly what fails and why — the direct motivation for every HA component.

Who Should Start Here

The Vagrant Simple cluster is the right starting point if you value infrastructure-as-code and want everything in a Vagrantfile, plan to share cluster definitions with teammates via Git, want full VM isolation (same as UTM under the hood), and are comfortable installing a few Homebrew packages and a Vagrant plugin.

If you want the cleanest networking and fastest deployment, start with the UTM Simple cluster. If resource efficiency matters most, the OrbStack Simple cluster is the lightest option.

What’s Next

Ready to build? The Vagrant Simple hands-on guide walks through deployment from clone to kubectl get nodes. Once you’ve explored the cluster and read the Ansible playbooks, the Learning Path maps the full progression from Simple to HA.

The HA upgrade scales to 11 VMs with dual-NIC networking across all of them — the Vagrant HA deep dive covers the Vagrantfile, the socket_vmnet bridge, and the full deployment timing.

Big tech, small lab. One reel at a time.