Minikube Setup, Drivers, and Resource Configuration#

Minikube runs a single-node Kubernetes cluster on your local machine. The difference between a minikube setup that feels like a toy and one that behaves like production comes down to three choices: the driver, the resource allocation, and the Kubernetes version. Get these wrong and you spend more time fighting the tool than using it.

Installation#

On macOS with Homebrew:

brew install minikube

On Linux via direct download:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

On ARM64 Linux:

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-arm64
sudo install minikube-linux-arm64 /usr/local/bin/minikube

On Windows, use the installer from the minikube releases page, or install via Chocolatey:

choco install minikube

Verify the installation:

minikube version

Driver Selection#

The driver determines how minikube creates the node that runs your cluster. This is the single most important decision for your setup.

Docker Driver (Recommended for Most Users)#

The Docker driver runs minikube as a container inside Docker. It is the fastest to start, uses the least overhead, and on Apple Silicon Macs, it runs containers natively on ARM64 without any emulation layer.

minikube start --driver=docker

To make Docker the permanent default:

minikube config set driver docker

Hyperkit (macOS Intel Only)#

Hyperkit uses the macOS Hypervisor.framework to create a lightweight VM. It was the recommended driver before Docker Desktop supported Kubernetes well. Not available on Apple Silicon.

minikube start --driver=hyperkit

QEMU (Avoid for Go Binaries on ARM64)#

QEMU provides a virtual machine driver that works across platforms. However, on ARM64 systems, QEMU cannot reliably run Go binaries. They crash with an lfstack.push error in the Go runtime. This is a known, persistent issue that affects any Go-based workload – which includes most Kubernetes ecosystem tools, operators, and many application servers.

If you are on an Apple Silicon Mac and need to run Go-based containers, do not use the QEMU driver. Use Docker instead.

# This will cause Go binary crashes on ARM64:
minikube start --driver=qemu
# Use Docker instead on ARM64 systems

Hyper-V (Windows)#

The native Windows hypervisor driver. Requires Hyper-V enabled in Windows features.

minikube start --driver=hyperv

VirtualBox#

Cross-platform but heavy. Requires a full VM. Slower to start than Docker. Use only if Docker is not available.

minikube start --driver=virtualbox

ARM64 and Apple Silicon Considerations#

Apple Silicon Macs (M1/M2/M3/M4) run ARM64 natively. The Docker driver creates ARM64 containers directly – no emulation, no performance penalty. This is the correct choice for these machines.

The critical constraint: not all container images publish ARM64 variants. When an image lacks an ARM64 build, Docker on Apple Silicon will attempt to run the AMD64 version through Rosetta emulation inside the Docker VM. This works for simple binaries but frequently fails for Go programs and anything with architecture-specific assembly.

When you encounter an image without ARM64 support, you have two options:

Build the image locally from source targeting ARM64.
Find an alternative image that publishes multi-arch manifests.

Check if an image supports ARM64:

docker manifest inspect <image>:<tag> | grep architecture

Resource Allocation#

Minikube defaults to modest resources that are insufficient for anything beyond trivial workloads. For running a production-like stack with a database, application server, and monitoring, allocate at minimum:

minikube start \
  --cpus=4 \
  --memory=8192 \
  --disk-size=40g

These values mean:

4 CPUs: Enough to run 10-15 pods without CPU throttling. Kubernetes system components (API server, etcd, CoreDNS, kube-proxy) consume about 0.5 CPU at idle.
8 GB RAM: Leaves room for your workloads after the ~1 GB consumed by Kubernetes system components.
40 GB disk: Container images accumulate fast. A typical stack with PostgreSQL, Redis, Nginx, and a few application images easily exceeds 10 GB.

You can check current resource allocation at any time:

minikube config view
kubectl top nodes   # requires metrics-server addon

Profiles: Multiple Isolated Clusters#

Profiles let you run multiple independent minikube clusters simultaneously. Each profile gets its own VM/container, its own Kubernetes version, and its own set of workloads.

# Create a staging cluster
minikube start -p staging --cpus=2 --memory=4096

# Create a production-like cluster with a specific k8s version
minikube start -p production --cpus=4 --memory=8192 --kubernetes-version=v1.28.0

# List all profiles
minikube profile list

# Switch kubectl context between profiles
minikube profile staging
# Or use kubectl directly:
kubectl config use-context staging

Delete a profile when done:

minikube delete -p staging

Kubernetes Version Pinning#

Pin your minikube Kubernetes version to match your production cluster. Version skew between local development and production is a common source of “works on my machine” failures, especially around API deprecations and admission controller behavior changes.

minikube start --kubernetes-version=v1.28.0

Check available versions:

minikube config defaults kubernetes-version

Container Runtime Selection#

Minikube supports three container runtimes. The choice rarely matters for development but can be relevant for testing runtime-specific behavior.

# containerd (default in recent minikube versions)
minikube start --container-runtime=containerd

# Docker (the original, still widely used)
minikube start --container-runtime=docker

# CRI-O (used by OpenShift)
minikube start --container-runtime=cri-o

If you need to use docker build inside minikube (via eval $(minikube docker-env)), you must use the Docker runtime. With containerd or CRI-O, use minikube image build instead.

Useful Addons#

Minikube ships with a library of addons that install common Kubernetes components:

# List all available addons
minikube addons list

# Essential addons for production-like development
minikube addons enable metrics-server    # kubectl top pods/nodes
minikube addons enable ingress           # nginx ingress controller
minikube addons enable ingress-dns       # DNS for ingress hostnames
minikube addons enable dashboard         # Kubernetes dashboard
minikube addons enable metallb           # LoadBalancer service support
minikube addons enable storage-provisioner  # dynamic PVC provisioning (enabled by default)

Production-Like Start Command#

Combining all the above into a single command that creates a production-like local cluster:

minikube start \
  --driver=docker \
  --cpus=4 \
  --memory=8192 \
  --disk-size=40g \
  --kubernetes-version=v1.28.0 \
  --container-runtime=containerd \
  -p my-project \
  --addons=metrics-server,ingress,dashboard

After startup, verify the cluster:

kubectl cluster-info
kubectl get nodes -o wide
kubectl get pods -A

Common Gotchas#

Minikube will not start after a Docker restart. Run minikube delete and minikube start again if the Docker engine was restarted while minikube was running.
Disk full errors. Minikube caches downloaded images. Clean old images with minikube ssh -- docker system prune -a (Docker runtime) or minikube image prune.
DNS not resolving inside pods. Wait 30-60 seconds after startup for CoreDNS to initialize. If it persists, check kubectl get pods -n kube-system.
Addon enable fails. Some addons have dependencies. Enable metrics-server before addons that rely on resource metrics.