Alright, let’s get our hands dirty. You need a Kubernetes cluster, but you don’t need the existential dread of managing a multi-node production beast just to figure out how a Deployment works. Enter minikube. It’s your local, disposable, single-node Kubernetes cluster that runs on a virtual machine (VM) right on your laptop. Think of it as a petri dish for all your cloud-native experiments. It’s perfect for development, learning, and testing. It’s not built for performance or high availability, and that’s the point. It’s built for you to break things without getting a frantic call at 3 AM.

The core concept is brilliantly simple: minikube boots a VM (or a container, more on that later) and then uses the VM’s internal container runtime to host the entire Kubernetes control plane and the worker node. That’s right, the API server, scheduler, etcd—all of it—runs in containers on this single node. It’s Kubernetes-ception. This is why it feels a bit like a Russian nesting doll, but it works surprisingly well.

Installation: Getting the Binary

First, you need the minikube binary and a hypervisor. I’m assuming you’re not running on a toaster and have something vaguely modern. On macOS, brew is your friend. On Linux, you’re probably already comfortable wrangling binaries. For Windows, well, my condolences, but Chocolatey or Winget will see you through.

# On macOS with Homebrew
brew install minikube

# On Linux (using the static binary)
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Check it's installed
minikube version

You’ll also need a hypervisor. On macOS, I default to virtualbox because it’s reliable and universal, but docker (using the Docker Desktop VM) or hyperkit are often faster. On Linux, virtualbox or docker are solid choices. Pick your fighter.

Starting Your Cluster: The First Hit

The basic command is straightforward. Fire it up. This is where the magic—and the waiting—happens. minikube will download a VM image (the “bootstrapper”) and then the container images for all the Kubernetes components. Go grab a coffee. Your first time will take a minute.

# Start a cluster with VirtualBox
minikube start --driver=virtualbox

😄  minikube v1.32.0 on Darwin 14.5 (arm64)
✨  Using the virtualbox driver based on user configuration
👍  Starting control plane node minikube in cluster minikube
🔥  Creating virtualbox VM (CPUs=2, Memory=2200MB, Disk=20000MB) ...
🐳  Preparing Kubernetes v1.28.3 on Docker 24.0.7 ...
🔗  Configuring bridge CNI (Container Network Interface) ...
🔎  Verifying Kubernetes components...
🌟  Enabled addons: storage-provisioner, default-storageclass
💡  kubectl not set up. You'll need to install it and point it at this cluster.

See that last line? It assumes you have kubectl, the CLI for controlling Kubernetes clusters, already installed and configured. It’s not wrong. You should absolutely have that. If you don’t, go install it now. I’ll wait.

…

Back? Good. Now, a crucial piece of minikube’s witchery: it automatically configures your kubectl context to point to itself. Run kubectl cluster-info and you’ll see it’s talking to your shiny new local cluster.

The Container Runtime Shuffle

Here’s a classic “questionable choice” moment, but it’s not minikube’s fault—it’s the industry’s. Kubernetes doesn’t run containers; it talks to something called a container runtime that does. The default runtime inside the minikube VM is Docker. Yes, you read that right. It’s using Docker to run Kubernetes, which in turn runs Pods, which often contain containers. It’s meta.

But wait, there’s more! The modern Kubernetes world is moving to containerd, a simpler, more focused runtime that was originally part of Docker. minikube lets you choose. If you want to simulate a more production-like environment, you can start with the containerd runtime.

# Start a cluster with the containerd runtime instead
minikube start --driver=virtualbox --container-runtime=containerd

Why does this matter? Because some commands change. When you use Docker as the runtime, you can run minikube ssh and then docker ps to see all the containers Kubernetes is managing. With containerd, you’d use crictl ps instead. This bit me more than once, so I’m doing you a solid by calling it out.

Interacting With Your Cluster: The Usual Suspects

Once it’s running, you treat it like any other Kubernetes cluster. Use kubectl.

# Get the nodes. Spoiler: there's only one.
kubectl get nodes

NAME       STATUS   ROLES           AGE   VERSION
minikube   Ready    control-plane   45s   v1.28.3

See? It’s even a little bit cocky, labeling itself as the control-plane. It’s not wrong, it’s just… ambitious.

The Dashboard: A Web UI Because You Have Eyes

Kubernetes has a dashboard. It’s a helpful, sometimes sluggish, web-based UI. minikube can deploy it for you as an addon. Addons are minikube’s way of packaging common cluster services.

# Enable the dashboard addon
minikube addons enable dashboard

# Now, to access it, you can run this command which sets up a proxy tunnel
minikube dashboard

This last command will open the dashboard in your default browser. It feels like a party trick, and it is, but a useful one for visualizing what’s happening in your cluster.

The Classic Pitfall: The minikube Docker Daemon

Pay attention, because this is the single most common “why doesn’t this work?!” moment for new minikube users.

You have Docker installed on your laptop. You have Docker running inside the minikube VM. They are not the same thing. Your local host Docker daemon knows nothing about the minikube VM.

If you try to build a Docker image on your laptop and then reference it in a Kubernetes Pod manifest like my-app:latest, Kubernetes will look for that image inside its own environment—inside the minikube VM. It won’t find it. You’ll get an ImagePullBackOff error and you’ll curse my name.

You have two solutions:

  1. Use the minikube’s Docker daemon. This tells your local docker command to talk to the Docker daemon inside the VM.

    eval $(minikube docker-env)  # This modifies your current shell's environment
docker build -t my-app:latest .  # Now this image is built inside the minikube VM

    Remember to run eval $(minikube docker-env) in every shell where you want to build images. To undo this, run eval $(minikube docker-env --unset).

  2. Push to a remote registry. The proper, production-grade way. Build your image, push it to Docker Hub or another registry, and then reference it in your manifest with the full path (docker.io/username/my-app:latest). minikube will pull it from the internet just like a real cluster would.

Stopping, Deleting, and Embracing the Chaos

You will break this cluster. Often. The beauty is in the reset.

# Pause your cluster without destroying it (saves CPU)
minikube stop

# Delete the cluster and its VM entirely. This is your "get out of jail free" card.
minikube delete

# Then just start it again. A blank slate in a few minutes.
minikube start

This impermanence is minikube’s greatest strength. It encourages experimentation. So go on, try to break it. That’s how you learn what not to do on the real thing.