Install Minikube and Start a Local Cluster

Minikube is ideal for local learning and fast experiments. It gives you a real Kubernetes API on your laptop with minimal setup, so you can test manifests, explore add-ons, and validate workflows without a cloud cluster.

This guide expands the original quick start with driver choices, sizing, and a small workload plus ingress example. The goal is to help you build a reliable local environment that mirrors production concepts.

Why Minikube

Lightweight single-node cluster for local development.
Works with common drivers (Docker, Hyper-V, VirtualBox, VMware).
Supports add-ons like Ingress, metrics-server, and dashboard.
Easy to reset when experiments go wrong.

Prerequisites

64-bit OS with virtualization support (or Docker Desktop on macOS/Windows).
2 CPU cores and 4GB memory for a comfortable experience.
kubectl installed and available on your PATH.

Install kubectl

Follow the official guide for your OS. On Linux you can do:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

Verify:

kubectl version --client

Install Minikube

Choose the installer that fits your platform. Example for Linux:

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

Check the version:

minikube version

Choose a driver

The driver determines how the VM or container runtime is managed:

Docker: easiest if you already use Docker Desktop or Docker Engine.
Hyper-V/VirtualBox: good for Windows, but needs virtualization enabled.
VMware/HyperKit: optional for macOS setups.

If Docker is not available, switch drivers and try again. You can list drivers with:

minikube start --help

Driver notes and tradeoffs

Docker driver is the simplest, but it shares resources with your local Docker environment. That is great for quick starts, yet it can collide with corporate proxy settings or registry authentication. VM-based drivers provide stronger isolation, which sometimes makes networking more predictable, but they require hypervisor support and more disk space.

If you are on Windows with Hyper-V, make sure only one hypervisor is active at a time. If VirtualBox and Hyper-V both try to own virtualization, Minikube may fail to start. On macOS, HyperKit is usually smooth, but Docker Desktop is still the most common choice for new users.

Start the cluster

You can tune CPU and memory explicitly, which helps stability for demos:

minikube start --driver=docker --cpus=4 --memory=6g
minikube status
kubectl get nodes

Use profiles when you want multiple clusters:

minikube start -p demo --driver=docker
minikube profile demo

Profiles and daily workflow

Profiles let you keep multiple isolated clusters. A typical pattern is one profile for quick experiments and one for longer-running demos. Remember to switch profiles before running kubectl commands, or set the context explicitly:

kubectl config get-contexts
kubectl config use-context minikube

If you frequently reset your cluster, consider scripting your startup with a few standard flags (driver, CPU, memory). That way you get a predictable baseline every time.

Cluster sizing and expectations

Minikube runs a single-node control plane and worker on the same machine. If you run heavy workloads, it will compete with your OS resources. For day-to-day development, 4 cores and 6-8GB memory is a good baseline. If you enable metrics and dashboard, allocate a bit more memory to avoid OOM kills.

Disk space also matters. The container runtime stores images and layers locally, so keep a few GB free or prune unused images if pulls start failing.

Common operations

minikube addons enable ingress
minikube addons enable metrics-server
minikube dashboard
minikube stop
minikube delete

Deploy a sample workload

Create a small Deployment and Service to validate scheduling and networking:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
      - name: web
        image: nginx:1.27
        ports:
        - containerPort: 80

apiVersion: v1
kind: Service
metadata:
  name: hello
spec:
  selector:
    app: hello
  ports:
  - port: 80
    targetPort: 80

kubectl apply -f deploy.yaml
kubectl apply -f svc.yaml
kubectl get pods -o wide

Access the service

Minikube offers several options:

minikube service hello --url

Or use port-forward:

kubectl port-forward svc/hello 8080:80

If you want to test LoadBalancer services, run:

minikube tunnel

Networking and DNS notes

Because Minikube runs locally, service IPs and cluster DNS only exist inside the node. If a Pod can resolve a name but your laptop cannot, that is expected. Use minikube service, port-forwarding, or ingress with a hosts file entry to bridge the gap.

If you enable the dashboard or expose services, remember that your local firewall may still block traffic even when Kubernetes is configured correctly. When in doubt, test connectivity from inside the Minikube node with minikube ssh and curl.

Ingress example

Enable the ingress add-on, then create an Ingress rule:

minikube addons enable ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello
spec:
  rules:
  - host: hello.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: hello
            port:
              number: 80

Get the Minikube IP and map it in your hosts file:

minikube ip

Then add hello.local -> <minikube-ip> in /etc/hosts (or Windows hosts file) and visit http://hello.local.

Proxy and registry considerations

If you are behind a corporate proxy, Minikube may not pull images properly. Configure proxy variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY) before you start the cluster, and include the cluster CIDR in NO_PROXY so internal traffic is not routed through the proxy.

For private registries, you can either log in inside the Minikube environment or load images directly with minikube image load. The latter is often simpler for local dev.

If image pulls are slow, consider using a local registry mirror configured in Docker or your hypervisor.

Working with local images

If you build images locally, load them into Minikube so it can pull them:

minikube image load my-app:dev
kubectl set image deployment/hello web=my-app:dev

This avoids pushing to a remote registry during development.

Storage basics

Minikube includes a default storage class. To test volumes quickly, create a PVC and mount it into a Pod. This helps verify persistence logic before you move to a real storage backend in production.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: demo-pvc
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

Reset and cleanup

When experiments get messy, reset fast:

minikube stop pauses the VM/container but keeps state.
minikube delete removes the cluster but keeps binaries.
minikube delete --all --purge cleans all profiles and cached images.

If you see repeated start failures, a full purge often fixes stale networking artifacts.

Troubleshooting tips

Node not Ready: check driver health and image pulls; run minikube logs.
Ports not reachable: use minikube service or kubectl port-forward.
Pods Pending: check resources with kubectl describe pod.
Ingress not working: ensure the ingress controller Pods are Running.

Diagnostics commands that save time:

minikube status
minikube logs
kubectl get events -A
kubectl describe node

Practical notes

Start with a quick inventory: kubectl get nodes, kubectl get pods -A, and kubectl get events -A.
Compare desired vs. observed state; kubectl describe usually explains drift or failed controllers.
Keep names, labels, and selectors consistent so Services and controllers can find Pods.

Quick checklist

The resource matches the intent you described in YAML.
Namespaces, RBAC, and images are correct for the target environment.
Health checks and logs are in place before promotion.