Kubernetes Environment Setup (Minikube)

Run a real single-node Kubernetes cluster on your laptop with Minikube, and deploy your first app to it with kubectl.

You don't need a cloud account or a multi-node cluster to learn Kubernetes. Minikube runs a complete, real Kubernetes cluster inside a single VM or container on your own machine — same API, same kubectl, same YAML you'd write for a production cluster.

Prerequisites

Minikube needs a "driver" to run the cluster in — almost always Docker, if you followed the Docker setup guide already. Make sure docker run hello-world works before continuing here.

You'll also need kubectl, the command-line tool for talking to any Kubernetes cluster:

macOS:

brew install kubectl

Linux:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

Windows:

winget install -e --id Kubernetes.kubectl

Verify:

kubectl version --client

Install Minikube

macOS:

brew install minikube

Linux:

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

Windows:

winget install -e --id Kubernetes.minikube

Start your cluster

minikube start --driver=docker

The first run downloads the base image and node components, so it takes a few minutes. Once it's done:

kubectl get nodes

should show a single node in Ready status — that's your cluster.

tip

minikube start auto-detects Docker as the driver on most machines, so you can often just run minikube start. Passing --driver=docker explicitly is worth doing anyway — it avoids Minikube falling back to a slower VM-based driver if it detects one installed too.

Deploy your first app

Create a deployment from any public image:

kubectl create deployment hello-node --image=registry.k8s.io/e2e-test-images/agnhost:2.39 -- /agnhost netexec --http-port=8080

Check that a pod came up:

kubectl get pods

Expose it as a service so it's reachable:

kubectl expose deployment hello-node --type=NodePort --port=8080

Minikube runs inside Docker, so NodePort isn't directly reachable on localhost the way it would be on a cloud cluster — ask Minikube to open a tunnel to it instead:

minikube service hello-node

This opens the service in your browser (or prints the URL) with the tunnel already wired up.

The commands you'll use constantly

kubectl get pods                      # what's running
kubectl get pods -o wide              # ...with node/IP detail
kubectl logs <pod-name>               # a pod's logs
kubectl logs -f <pod-name>            # follow logs live
kubectl describe pod <pod-name>       # why is this pod stuck/crashing?
kubectl exec -it <pod-name> -- sh     # shell into a pod
kubectl apply -f deployment.yaml      # create/update from a YAML manifest
kubectl delete -f deployment.yaml     # tear down what that manifest created

kubectl describe is the one to reach for first whenever a pod won't start — it shows the scheduling and container events (image pull errors, crash loops, failed health checks) that get pods alone won't.

Useful Minikube extras

minikube dashboard    # open the web UI for browsing your cluster
minikube addons list  # see what's available (ingress, metrics-server, ...)
minikube addons enable ingress
minikube stop         # stop the cluster, keep its state
minikube delete       # destroy it completely, start fresh next time

note

Enable the metrics-server addon early — kubectl top pods and kubectl top nodes don't work without it, and it's a one-line minikube addons enable metrics-server to turn on.

Common gotchas

warning

minikube start fails with a driver error. Usually means Docker isn't running, or Minikube picked a different driver than you expected (VirtualBox, HyperKit) from a previous install. Run minikube delete then minikube start --driver=docker to force a clean start with the right one.

warning

Pods stuck in ImagePullBackOff. Check kubectl describe pod <pod-name> — nearly always a typo'd image name/tag, or a private image Minikube's Docker daemon isn't authenticated against. Note that Minikube runs its own Docker daemon separate from your host's; docker images on your host won't show what Minikube has pulled.

warning

Resource limits. Minikube defaults to a fairly small VM allocation. If pods are getting evicted or the dashboard feels sluggish, restart with more headroom: minikube start --cpus=4 --memory=8192.

Once this is running comfortably, you have a real Kubernetes API to practice against — every manifest, kubectl command, and debugging habit you build here carries over directly to a production cluster later.