Skip to content

ADR-001: Use Minikube as Local Kubernetes Runtime

Status

Accepted

Date

2026-03-07

Context

A local Kubernetes runtime is needed to run the HomeKube sandbox on macOS without access to a cloud provider. The runtime must be CNCF-compatible (unmodified upstream K8s API), support realistic learning scenarios, and be capable of running the Phase 1 stack (ingress-nginx, cert-manager, Prometheus, Grafana) on a MacBook with 16–32 GB RAM.

Requirements

  • Standard CNCF Kubernetes API (no stripped or modified components)
  • macOS support with Apple Silicon (arm64)
  • LoadBalancer service type support
  • Addon ecosystem for accelerated learning
  • Active CNCF community

Decision

Use Minikube with the Docker driver as the local Kubernetes runtime.

Start command: 

minikube start \
  --driver=docker \
  --cpus=4 \
  --memory=8g \
  --kubernetes-version=stable \
  --addons=metrics-server

Alternatives Considered

Tool Reason Not Chosen
kind (Kubernetes in Docker) Excellent for CI; lacks built-in addons, no native LoadBalancer, limited minikube tunnel equivalent
k3d / k3s K3s deliberately strips or replaces components (e.g. uses Traefik instead of ingress-nginx, embeds SQLite instead of etcd). Reduces CNCF learning fidelity.
Docker Desktop K8s Opinionated, limited configurability, harder to replicate CNCF tooling patterns
Lima + nerdctl Low-level; valuable for understanding container runtimes but not for K8s cluster learning

Consequences

Positive

  • Runs standard upstream Kubernetes — everything learned applies 1:1 to production clusters
  • Addon system (minikube addons enable ...) provides quick access to dashboard, registry, metrics-server
  • minikube tunnel emulates cloud LoadBalancer behaviour (useful for Phase 2+ learning)
  • minikube image load allows testing local container images without a registry
  • arm64 support via Docker driver on Apple Silicon

Negative

  • Heavier than kind/k3d (~2 GB RAM overhead for Docker VM vs host process)
  • Single-node only — multi-node requires multiple minikube profiles
  • Not suitable for production; must re-learn some operational patterns for real clusters

Trade-offs

Learning fidelity and convenience are prioritised over minimal resource usage. The extra RAM cost of Minikube is justified by its standard Kubernetes API and addon ecosystem.