Lab it, learn it

Before you clone the repo and run the script, it helps to understand what you’re actually building and why each piece exists. This post is the conceptual overview of the OrbStack Simple cluster — what the 6 machines do, what Kubernetes concepts they map to, and why OrbStack is the right choice when you want the lowest resource footprint without sacrificing the learning experience.

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

The Architecture — 6 Machines, 5 Roles

The Simple cluster builds a complete Kubernetes environment across 6 lightweight Linux machines on your Mac. OrbStack machines share the host kernel rather than booting their own — they’re lightweight environments, not full VMs. The result is dramatically lower resource consumption while providing the same Kubernetes learning experience. Here’s what each role does and why it exists.

Vault (PKI and Secrets). HashiCorp Vault manages all the TLS certificates your cluster needs. A proper 3-tier CA hierarchy — Root CA → Intermediate CA → leaf CAs for Kubernetes, etcd, and front-proxy — replaces the typical homelab approach of self-signed certs. 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 machine is accessed through it via SSH — the bastion pattern used in production environments. Jump runs Ansible and hosts the kubectl config, making it your single command center.

etcd (Cluster State Store). All cluster state lives in etcd. In the Simple setup it’s a single node — a deliberate single point of failure. Stop etcd and the API server can’t read or write anything. That experiment is what motivates upgrading to a 3-node etcd cluster with quorum in the HA version.

Master (Control Plane). Runs kube-apiserver, kube-controller-manager, and kube-scheduler as systemd services. One master means one failure away from losing control plane access — though existing workloads on workers keep running.

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 — from individual binaries with no kubeadm — forces you to understand how each piece connects. Here’s what becomes concrete.

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. You’ll see exactly which cert goes where and why the CAs are separated.

What kubelet actually does on a node. A systemd service with a config file, a client certificate, and flags controlling pod CIDR, container runtime paths, and API server communication. Reading the unit file teaches more than documentation.

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 single experiment builds the operational intuition that etcd is the real heart of the cluster.

How lightweight environments differ from full VMs. OrbStack machines share the host kernel (6.17.8-orbstack), use zram swap that can’t be disabled, and have two IPs on a single network interface. These are real-world constraints that teach you to configure explicitly rather than rely on defaults — the kubelet sets failSwapOn: false, every bind address specifies the exact static IP, and kube-proxy uses conntrack.maxPerCore: 0 to avoid shared-kernel permission issues.

Why OrbStack Specifically

All three tools produce the same functional cluster with the same Ansible roles. The difference is resource consumption and what trade-offs you’re making.

OrbStack uses a fraction of the resources. The 6-machine Simple cluster takes roughly 10 GB of disk versus 170 GB for UTM. Memory isn’t pre-allocated per machine — it’s shared dynamically. Machines are created in seconds with orb create, and the entire deploy-explore-destroy-redeploy cycle takes about 12 minutes. Your Mac stays cool even with all 6 machines running.

For learning Kubernetes — deployments, services, RBAC, pod networking, certificate management, etcd operations — the shared-kernel approach is indistinguishable from a full VM. The 5% of cases where it differs (custom kernel modules, kernel-level security policies) aren’t relevant when you’re learning the fundamentals.

The tradeoff is production realism. UTM and Vagrant create full VMs with genuine kernel isolation — separate kernels, independent network stacks, behavior identical to cloud instances. If that matters for your learning goals, the UTM Simple cluster gives you the closest-to-production experience. If infrastructure-as-code is your priority, the Vagrant Simple cluster puts everything in a version-controlled Vagrantfile.

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 it 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.

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

Who Should Start Here

The OrbStack Simple cluster is the right starting point if you want the fastest setup with the lowest resource cost, have a Mac with 16 GB RAM (OrbStack works comfortably where UTM and Vagrant need 32 GB+), want rapid deploy-break-destroy-redeploy cycles for experimentation, and don’t need full kernel isolation for your learning goals.

If production realism matters more, start with the UTM Simple cluster. If infrastructure-as-code is your priority, the Vagrant Simple cluster gives you declarative VM management.

What’s Next

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

The HA upgrade adds 5 more machines while keeping the resource footprint manageable — the OrbStack HA deep dive covers the shared-kernel gotchas, dual-IP networking, and full deployment timing.

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