Minikube Tutorial: Complete Guide to Running Kubernetes Locally

Minikube is the easiest way to run Kubernetes locally on your machine. Whether you’re a developer learning Kubernetes, testing deployments, or building cloud-native applications, this comprehensive guide will take you from zero to running your first cluster.

Table of Contents

1. What is Minikube?
2. Prerequisites
3. Installing Minikube
4. Starting Your First Cluster
5. Deploying Your First Application
6. Essential Minikube Commands
7. Working with Services
8. Minikube Addons
9. Multi-Node Clusters
10. Troubleshooting Common Issues
11. Best Practices

---

What is Minikube?

Minikube is an open-source tool that enables you to run a single-node or multi-node Kubernetes cluster on your local machine. It creates a virtual machine (or uses Docker/Podman containers) and deploys a simple cluster containing only one node.

Key Features

• Cross-Platform: Works on Linux, macOS, and Windows
• Multiple Drivers: Supports Docker, Podman, VirtualBox, Hyperkit, KVM, and more
• Addons System: Easy installation of Kubernetes features like Dashboard, Ingress, and Metrics Server
• LoadBalancer Support: Built-in tunnel for LoadBalancer services
• Multi-Cluster: Run multiple clusters simultaneously

Minikube vs Other Local Kubernetes Tools

---

Prerequisites

Before installing Minikube, ensure your system meets the following requirements:

• CPU: 2 cores or more
• Memory: 2GB free RAM (4GB recommended)
• Disk Space: 20GB free disk space
• Container/VM Manager: Docker, Podman, VirtualBox, or Hyperkit

Check System Requirements

# Check CPU cores
nproc

# Check available memory
free -h

# Check disk space
df -h

---

Installing Minikube

Installation on Linux

Using Binary Download (Recommended)

# Download the latest Minikube binary
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64

# Install Minikube
sudo install minikube-linux-amd64 /usr/local/bin/minikube

# Verify installation
minikube version

Using Package Managers

# Debian/Ubuntu
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube_latest_amd64.deb
sudo dpkg -i minikube_latest_amd64.deb

# Fedora/RHEL
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-latest.x86_64.rpm
sudo rpm -Uvh minikube-latest.x86_64.rpm

# Arch Linux
sudo pacman -S minikube

Installation on macOS

# Using Homebrew (Recommended)
brew install minikube

# Using Binary Download
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-amd64
sudo install minikube-darwin-amd64 /usr/local/bin/minikube

# For Apple Silicon (M1/M2/M3)
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-arm64
sudo install minikube-darwin-arm64 /usr/local/bin/minikube

Installation on Windows

# Using Chocolatey
choco install minikube

# Using Winget
winget install Kubernetes.minikube

# Using PowerShell (Manual)
New-Item -Path 'c:\' -Name 'minikube' -ItemType Directory -Force
Invoke-WebRequest -OutFile 'c:\minikube\minikube.exe' -Uri 'https://github.com/kubernetes/minikube/releases/latest/download/minikube-windows-amd64.exe' -UseBasicParsing

Install kubectl

Minikube includes kubectl, but you can also install it separately:

# 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

# macOS
brew install kubectl

# Verify kubectl
kubectl version --client

---

Starting Your First Cluster

Basic Cluster Start

# Start Minikube with default settings
minikube start

# Expected output:
# 😄  minikube v1.32.0 on Ubuntu 22.04
# ✨  Automatically selected the docker driver
# 📌  Using Docker driver with root privileges
# 🧯  Creating minikube cluster in container...
# 🐳  Preparing Kubernetes v1.28.3 on Docker 24.0.7...
# 🔗  Configuring bridge CNI...
# 🔎  Verifying Kubernetes components...
# 🌟  Enabled addons: storage-provisioner, default-storageclass
# 🏄  Done! kubectl is now configured to use "minikube" cluster

Advanced Cluster Configuration

# Start with specific resources
minikube start --cpus=4 --memory=8192 --disk-size=50g

# Start with specific Kubernetes version
minikube start --kubernetes-version=v1.29.0

# Start with specific driver
minikube start --driver=docker
minikube start --driver=virtualbox
minikube start --driver=podman

# Start with custom container runtime
minikube start --container-runtime=containerd
minikube start --container-runtime=cri-o

# Start with multiple nodes
minikube start --nodes=3

# Start with specific CNI plugin
minikube start --cni=calico
minikube start --cni=flannel

Verify Cluster Status

# Check Minikube status
minikube status

# Expected output:
# minikube
# type: Control Plane
# host: Running
# kubelet: Running
# apiserver: Running
# kubeconfig: Configured

# Check cluster info
kubectl cluster-info

# View nodes
kubectl get nodes

# Check all system pods
kubectl get pods -A

---

Deploying Your First Application

Deploy a Simple Nginx Application

# Create a deployment
kubectl create deployment nginx --image=nginx:latest

# Verify the deployment
kubectl get deployments

# Check pods
kubectl get pods

# Expected output:
# NAME                     READY   STATUS    RESTARTS   AGE
# nginx-77b4fdf86c-xk2qp   1/1     Running   0          30s

Expose the Application

# Expose deployment as a service
kubectl expose deployment nginx --type=NodePort --port=80

# Get service details
kubectl get services

# Access the service URL
minikube service nginx --url

# Open in browser automatically
minikube service nginx

Deploy Using YAML Manifests

Create a file named nginx-deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  type: NodePort
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30080

Apply the manifest:

# Apply the configuration
kubectl apply -f nginx-deployment.yaml

# Verify deployment
kubectl get deployments
kubectl get pods
kubectl get services

# Access the application
minikube service nginx-service

Deploy a Full-Stack Application

Create fullstack-app.yaml:

# Frontend Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: 2
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
      - name: frontend
        image: nginx:alpine
        ports:
        - containerPort: 80
---
# Backend Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
      - name: backend
        image: hashicorp/http-echo
        args:
        - "-text=Hello from Backend!"
        ports:
        - containerPort: 5678
---
# Frontend Service
apiVersion: v1
kind: Service
metadata:
  name: frontend-service
spec:
  selector:
    app: frontend
  type: NodePort
  ports:
  - port: 80
    targetPort: 80
---
# Backend Service
apiVersion: v1
kind: Service
metadata:
  name: backend-service
spec:
  selector:
    app: backend
  type: ClusterIP
  ports:
  - port: 5678
    targetPort: 5678

---

Essential Minikube Commands

Cluster Management

# Start cluster
minikube start

# Stop cluster (preserves state)
minikube stop

# Delete cluster completely
minikube delete

# Delete all clusters
minikube delete --all

# Pause cluster (save resources)
minikube pause

# Resume paused cluster
minikube unpause

# SSH into the Minikube node
minikube ssh

# View cluster IP
minikube ip

Profile Management (Multiple Clusters)

# Create a new profile/cluster
minikube start -p dev-cluster
minikube start -p staging-cluster

# List all profiles
minikube profile list

# Switch between profiles
minikube profile dev-cluster

# Delete specific profile
minikube delete -p staging-cluster

Docker Environment

# Configure shell to use Minikube's Docker daemon
eval $(minikube docker-env)

# Build images directly in Minikube
docker build -t my-app:v1 .

# Revert to host Docker daemon
eval $(minikube docker-env -u)

Logs and Debugging

# View Minikube logs
minikube logs

# Follow logs in real-time
minikube logs -f

# View logs for specific node
minikube logs --node=minikube-m02

# Get kubectl configuration
minikube kubectl -- get pods

---

Working with Services

Service Types in Minikube

# ClusterIP (internal only)
kubectl expose deployment myapp --type=ClusterIP --port=80

# NodePort (external via node port)
kubectl expose deployment myapp --type=NodePort --port=80

# LoadBalancer (requires tunnel)
kubectl expose deployment myapp --type=LoadBalancer --port=80

Using Minikube Tunnel for LoadBalancer

# Start tunnel in a separate terminal
minikube tunnel

# Now LoadBalancer services get external IPs
kubectl get services

# Example output:
# NAME         TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
# myapp        LoadBalancer   10.96.100.100   10.96.100.100 80:31234/TCP   5m

Port Forwarding

# Forward a pod port to localhost
kubectl port-forward pod/nginx-pod 8080:80

# Forward a service port
kubectl port-forward service/nginx-service 8080:80

# Access at http://localhost:8080

---

Minikube Addons

Addons extend Minikube’s functionality with pre-configured Kubernetes components.

List Available Addons

minikube addons list

# Output shows status of each addon:
# |-----------------------------|----------|--------------|--------------------------------|
# |         ADDON NAME          | PROFILE  |    STATUS    |           MAINTAINER           |
# |-----------------------------|----------|--------------|--------------------------------|
# | dashboard                   | minikube | disabled     | Kubernetes                     |
# | default-storageclass        | minikube | enabled ✅   | Kubernetes                     |
# | ingress                     | minikube | disabled     | Kubernetes                     |
# | ingress-dns                 | minikube | disabled     | minikube                       |
# | metrics-server              | minikube | disabled     | Kubernetes                     |
# | registry                    | minikube | disabled     | minikube                       |
# |-----------------------------|----------|--------------|--------------------------------|

Essential Addons

Kubernetes Dashboard

# Enable dashboard
minikube addons enable dashboard

# Enable metrics for dashboard
minikube addons enable metrics-server

# Open dashboard in browser
minikube dashboard

# Get dashboard URL without opening
minikube dashboard --url

Ingress Controller

# Enable Ingress addon
minikube addons enable ingress

# Verify ingress controller is running
kubectl get pods -n ingress-nginx

# Create an Ingress resource
cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: hello-world.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 80
EOF

# Add to /etc/hosts
echo "$(minikube ip) hello-world.local" | sudo tee -a /etc/hosts

# Access via hostname
curl http://hello-world.local

Metrics Server

# Enable metrics server
minikube addons enable metrics-server

# View node metrics
kubectl top nodes

# View pod metrics
kubectl top pods

# View pod metrics in all namespaces
kubectl top pods -A

Container Registry

# Enable local registry
minikube addons enable registry

# Push images to local registry
docker tag my-app:latest localhost:5000/my-app:latest
docker push localhost:5000/my-app:latest

Configure Addon Settings

bash

# Configure addon with specific settings
minikube addons configure ingress

# Enable addon with configuration
minikube addons enable ingress --config=ingress-config.yaml

---

Multi-Node Clusters

Minikube supports multi-node clusters to simulate production environments.

Create Multi-Node Cluster

# Start a 3-node cluster
minikube start --nodes=3

# Verify nodes
kubectl get nodes

# Output:
# NAME           STATUS   ROLES           AGE   VERSION
# minikube       Ready    control-plane   10m   v1.28.3
# minikube-m02   Ready    <none>          9m    v1.28.3
# minikube-m03   Ready    <none>          8m    v1.28.3

Add Nodes to Existing Cluster

# Add a worker node
minikube node add

# Add a worker node with specific name
minikube node add --worker

# List nodes
minikube node list

Remove Nodes

# Delete a specific node
minikube node delete minikube-m03

# View remaining nodes
kubectl get nodes

Deploy with Node Affinity

apiVersion: apps/v1
kind: Deployment
metadata:
  name: worker-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: worker
  template:
    metadata:
      labels:
        app: worker
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: kubernetes.io/hostname
                operator: NotIn
                values:
                - minikube  # Don't schedule on control plane
      containers:
      - name: worker
        image: nginx:alpine

---

Troubleshooting Common Issues

Issue 1: Minikube Won’t Start

bash

# Check system requirements
minikube start --alsologtostderr

# Reset Minikube completely
minikube delete --all --purge
minikube start

# Try different driver
minikube start --driver=virtualbox

Issue 2: kubectl Can’t Connect

bash

# Update kubeconfig
minikube update-context

# Check cluster status
minikube status

# Restart cluster
minikube stop && minikube start

Issue 3: Insufficient Resources

bash

# Check resource usage
minikube ssh -- df -h
minikube ssh -- free -m

# Start with more resources
minikube delete
minikube start --cpus=4 --memory=8192

Issue 4: Image Pull Errors

bash

# Use Minikube's Docker daemon
eval $(minikube docker-env)

# Build image locally
docker build -t myapp:v1 .

# Update deployment to never pull
kubectl set image deployment/myapp myapp=myapp:v1
kubectl patch deployment myapp -p '{"spec":{"template":{"spec":{"containers":[{"name":"myapp","imagePullPolicy":"Never"}]}}}}'

Issue 5: DNS Resolution Problems

bash

# Check CoreDNS pods
kubectl get pods -n kube-system -l k8s-app=kube-dns

# Restart CoreDNS
kubectl rollout restart deployment coredns -n kube-system

# Test DNS resolution
kubectl run test-dns --image=busybox:1.28 --rm -it --restart=Never -- nslookup kubernetes

View Detailed Logs

bash

# Minikube logs
minikube logs --file=minikube-debug.log

# Specific component logs
kubectl logs -n kube-system -l component=kube-apiserver
kubectl logs -n kube-system -l component=etcd

# Events
kubectl get events --sort-by='.lastTimestamp'

---

Best Practices

1. Resource Management

bash

# Set appropriate resource limits
minikube start --cpus=4 --memory=8g --disk-size=40g

# Use pause/unpause instead of stop/start for quick breaks
minikube pause
minikube unpause

# Clean up unused resources regularly
minikube delete --all --purge
docker system prune -a

2. Use Profiles for Different Environments

bash

# Development cluster
minikube start -p dev --cpus=2 --memory=4096

# Testing cluster with more resources
minikube start -p test --cpus=4 --memory=8192 --nodes=3

# Switch between profiles
minikube profile dev

3. Optimize Image Building

bash

# Use Minikube's Docker daemon for faster builds
eval $(minikube docker-env)

# Cache base images
minikube cache add nginx:alpine
minikube cache add node:18-alpine

# List cached images
minikube cache list

4. Persistent Storage

yaml

# Use hostPath for development
apiVersion: v1
kind: PersistentVolume
metadata:
  name: dev-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /data/dev-pv

5. Network Configuration

bash

# Enable ingress for HTTP routing
minikube addons enable ingress

# Use tunnel for LoadBalancer services
minikube tunnel

# Configure custom DNS
minikube addons enable ingress-dns

---

Quick Reference Cheat Sheet

CommandDescriptionminikube startStart clusterminikube stopStop clusterminikube deleteDelete clusterminikube statusCheck statusminikube dashboardOpen dashboardminikube service <name>Access serviceminikube tunnelEnable LoadBalancerminikube addons listList addonsminikube sshSSH into nodeminikube ipGet cluster IPminikube logsView logseval $(minikube docker-env)Use Minikube Docker

---

Conclusion

Minikube is an indispensable tool for Kubernetes development and learning. With this guide, you can now set up local Kubernetes clusters, deploy applications, manage services, use addons, and troubleshoot common issues.

Next Steps

1. Learn Helm: Package your applications with Helm charts
2. Explore Service Mesh: Try Istio or Linkerd with Minikube
3. CI/CD Integration: Integrate Minikube with GitHub Actions or Jenkins
4. Advanced Networking: Experiment with different CNI plugins

Additional Resources

• Official Minikube Documentation
• Kubernetes Documentation
• Minikube GitHub Repository
• CNCF Landscape