Minikube Local Development

Minikube Local Development Skill

When to use this Skill

Use this Skill whenever you are:

• Setting up local Kubernetes development environment.
• Running Kubernetes clusters on your laptop for testing.
• Loading and testing local Docker images in Kubernetes.
• Debugging Kubernetes deployments locally.
• Learning Kubernetes without cloud costs.
• Testing Helm charts before deploying to production.

This Skill works for any Minikube project, not just a single repository.

Core Goals

• Set up reliable local Kubernetes environment.
• Efficiently load and test local Docker images.
• Use addons for enhanced development experience.
• Implement proper networking for service access.
• Troubleshoot common issues quickly.
• Enable fast development iteration cycles.

What is Minikube?

Minikube is local Kubernetes that makes it easy to learn and develop for Kubernetes.

Cloud Kubernetes:              Minikube:
┌──────────────────┐          ┌──────────────────┐
│  Cloud Provider  │          │  Your Laptop     │
│  (AWS/GCP/Azure) │          │  (Free!)         │
│  Multiple Nodes  │          │  Single Node     │
│  $100s/month     │          │  $0/month        │
└──────────────────┘          └──────────────────┘

Key Features:

• Single-node Kubernetes cluster
• Supports multiple drivers (Docker, Hyper-V, VirtualBox)
• Built-in addons (dashboard, ingress, registry)
• Local image loading (no registry needed)
• Cross-platform (Windows, macOS, Linux)

Installation

Prerequisites

Windows Installation

Option 1: Using Chocolatey (Recommended)

# Install Chocolatey first if not installed
# Then install minikube
choco install minikube

# Verify installation
minikube version

Option 2: Direct Download

# Download installer
# https://minikube.sigs.k8s.io/docs/start/

# Or use winget
winget install Kubernetes.minikube

Option 3: Using Scoop

scoop install minikube

macOS Installation

# Using Homebrew
brew install minikube

# Verify
minikube version

Linux Installation

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

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

# Verify
minikube version

Install kubectl

kubectl is required to interact with Kubernetes.

# Windows (Chocolatey)
choco install kubernetes-cli

# 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 kubectl /usr/local/bin/kubectl

# Verify
kubectl version --client

Drivers

Minikube supports multiple drivers for running the cluster.

Available Drivers

Setting Default Driver

# Set Docker as default (recommended)
minikube config set driver docker

# View current config
minikube config view

# Or specify at start time
minikube start --driver=docker

Docker Driver (Recommended)

# Requires Docker Desktop running
minikube start --driver=docker

Advantages:

• Fastest startup time
• Works on all platforms
• Easy image loading
• Lower resource usage

Hyper-V Driver (Windows)

# Requires Hyper-V enabled
minikube start --driver=hyperv

# With specific virtual switch
minikube start --driver=hyperv --hyperv-virtual-switch="Minikube Switch"

Starting & Managing Cluster

Start Cluster

# Basic start (uses default driver)
minikube start

# With specific driver
minikube start --driver=docker

# With custom resources
minikube start --cpus=4 --memory=8192 --disk-size=50g

# With specific Kubernetes version
minikube start --kubernetes-version=v1.28.0

# With multiple addons enabled
minikube start --addons=dashboard,ingress,metrics-server

Check Status

# Cluster status
minikube status

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

# Get cluster IP
minikube ip

# Get Kubernetes version
kubectl version

Stop & Delete

# Stop cluster (preserves state)
minikube stop

# Delete cluster (removes everything)
minikube delete

# Delete all clusters and profiles
minikube delete --all

# Pause cluster (save resources)
minikube pause

# Unpause cluster
minikube unpause

Resource Management

# View current config
minikube config view

# Set default CPUs
minikube config set cpus 4

# Set default memory (MB)
minikube config set memory 8192

# Set default disk size
minikube config set disk-size 50g

# Apply changes (requires restart)
minikube stop
minikube start

Loading Docker Images

Minikube has its own Docker registry. Local images must be loaded into Minikube.

Method 1: Use Minikube's Docker Daemon (Recommended)

# Point shell to Minikube's Docker
eval $(minikube docker-env)

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

# Verify image is in Minikube
docker images | grep my-app

# Reset to local Docker (when done)
eval $(minikube docker-env -u)

Note: For PowerShell on Windows:

& minikube docker-env | Invoke-Expression

Method 2: Load Pre-built Images

# Build locally first
docker build -t my-app:v1 .

# Load into Minikube
minikube image load my-app:v1

# Verify
minikube image ls | grep my-app

Method 3: Build Directly in Minikube

# Build inside Minikube
minikube image build -t my-app:v1 .

# Or with specific Dockerfile
minikube image build -t my-app:v1 -f Dockerfile.prod .

Image Commands

# List images in Minikube
minikube image ls

# Load image
minikube image load my-app:v1

# Remove image
minikube image rm my-app:v1

# Pull image from registry
minikube image pull nginx:latest

Important: ImagePullPolicy

When using local images, set imagePullPolicy to prevent Kubernetes from trying to pull from remote registry.

spec:
  containers:
  - name: my-app
    image: my-app:v1
    imagePullPolicy: Never  # or IfNotPresent

Accessing Services

Method 1: minikube service (Easiest)

# Opens service in browser
minikube service my-service

# Get URL only
minikube service my-service --url

# With namespace
minikube service my-service -n my-namespace

Method 2: kubectl port-forward

# Forward pod port
kubectl port-forward pod/my-pod 8080:80

# Forward service port
kubectl port-forward svc/my-service 8080:80

# Forward with specific address
kubectl port-forward svc/my-service 8080:80 --address='0.0.0.0'

Method 3: NodePort Service

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  type: NodePort
  selector:
    app: my-app
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30000  # Fixed port 30000-32767

Access at: http://$(minikube ip):30000

Method 4: minikube tunnel (LoadBalancer)

# Start tunnel (run in separate terminal)
minikube tunnel

# Now LoadBalancer services get external IPs
kubectl get svc
# NAME         TYPE           EXTERNAL-IP    PORT(S)
# my-service   LoadBalancer   127.0.0.1      80:31234/TCP

Addons

Addons extend Minikube functionality.

List & Manage Addons

# List all addons
minikube addons list

# Enable addon
minikube addons enable dashboard

# Disable addon
minikube addons disable dashboard

# Enable at start
minikube start --addons=dashboard,ingress

Essential Addons

Dashboard

# Enable dashboard
minikube addons enable dashboard

# Open dashboard in browser
minikube dashboard

# Get dashboard URL only
minikube dashboard --url

Ingress

# Enable ingress addon
minikube addons enable ingress

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

Example Ingress:

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

Add to hosts file:

# /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows)
192.168.49.2  my-app.local  # Use your minikube ip

Metrics Server

# Enable metrics server
minikube addons enable metrics-server

# Now you can use:
kubectl top nodes
kubectl top pods

Multi-Node Clusters

Minikube can create multi-node clusters for testing.

# Start with 3 nodes
minikube start --nodes 3

# Add node to existing cluster
minikube node add

# List nodes
kubectl get nodes

# Delete specific node
minikube node delete minikube-m02

Profiles

Profiles allow multiple Minikube clusters.

# Create new profile
minikube start -p dev-cluster

# List profiles
minikube profile list

# Switch profile
minikube profile dev-cluster

# Delete profile
minikube delete -p dev-cluster

SSH Access

# SSH into Minikube VM
minikube ssh

# Run command via SSH
minikube ssh -- ls -la /

# SSH to specific node (multi-node)
minikube ssh -n minikube-m02

Logs & Debugging

View Logs

# Minikube logs
minikube logs

# Follow logs
minikube logs -f

# Logs for specific node
minikube logs -n minikube-m02

# Verbose startup
minikube start --alsologtostderr -v=2

Kubernetes Logs

# Pod logs
kubectl logs my-pod

# Follow logs
kubectl logs -f my-pod

# Previous container logs
kubectl logs my-pod --previous

# Logs from all pods with label
kubectl logs -l app=my-app

Describe Resources

# Describe pod (shows events)
kubectl describe pod my-pod

# Describe service
kubectl describe service my-service

# Describe node
kubectl describe node minikube

Troubleshooting

Common Issues & Solutions

1. Minikube Won't Start

# Delete and recreate
minikube delete
minikube start

# Try different driver
minikube start --driver=docker

# Check Docker is running
docker info

2. ImagePullBackOff Error

Cause: Image not found in Minikube

Solution:

# Load image into Minikube
minikube image load my-app:v1

# Set imagePullPolicy to Never
# In deployment.yaml:
imagePullPolicy: Never

3. Insufficient Resources

# Allocate more resources
minikube stop
minikube start --cpus=4 --memory=8192

# Or permanently set
minikube config set cpus 4
minikube config set memory 8192

4. kubectl Connection Refused

# Check cluster status
minikube status

# Update kubeconfig
minikube update-context

# Or set context manually
kubectl config use-context minikube

5. Service Not Accessible

# Use minikube service
minikube service my-service

# Or start tunnel
minikube tunnel

6. DNS Issues

# Check CoreDNS pods
kubectl get pods -n kube-system | grep coredns

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

7. Clean Start

# Complete reset
minikube delete --all --purge
rm -rf ~/.minikube
minikube start

Diagnostic Commands

# Full status check
minikube status

# System info
minikube ssh -- cat /etc/os-release

# Disk usage
minikube ssh -- df -h

# Memory usage
minikube ssh -- free -m

# Kubernetes component status
kubectl get componentstatuses

# All pods in all namespaces
kubectl get pods -A

Development Workflow

Recommended Workflow

# 1. Start Minikube
minikube start --driver=docker

# 2. Point to Minikube Docker
eval $(minikube docker-env)

# 3. Build images
docker build -t my-backend:v1 ./backend
docker build -t my-frontend:v1 ./frontend

# 4. Deploy
kubectl apply -f k8s/

# 5. Access service
minikube service frontend-service

# 6. View logs if needed
kubectl logs -l app=backend

# 7. Make changes, rebuild, redeploy
docker build -t my-backend:v1 ./backend
kubectl rollout restart deployment/backend

# 8. When done
minikube stop

Fast Iteration Cycle

# Build and deploy in one command
docker build -t my-app:dev . && kubectl rollout restart deployment/my-app

# Or create a script: dev.sh
#!/bin/bash
eval $(minikube docker-env)
docker build -t $1:dev ./$1
kubectl rollout restart deployment/$1
echo "Deployed $1"

Complete Example: Deploy Full-Stack App

Step 1: Start Minikube

minikube start --driver=docker --cpus=4 --memory=4096

Step 2: Build Images

eval $(minikube docker-env)

cd phase2/backend
docker build -t todo-backend:v1 .

cd ../frontend
docker build -t todo-frontend:v1 .

Step 3: Create Namespace

kubectl create namespace todo-app

Step 4: Deploy

kubectl apply -f k8s/ -n todo-app

Step 5: Verify

kubectl get all -n todo-app

Step 6: Access

minikube service frontend-service -n todo-app

Best Practices

Do

• Use Docker driver for fastest startup.
• Set imagePullPolicy: Never for local images.
• Use eval $(minikube docker-env) for direct builds.
• Enable metrics-server for resource monitoring.
• Use namespaces to organize deployments.
• Stop Minikube when not in use (save resources).

Don't

• Don't use :latest tag with local images.
• Don't forget to load images into Minikube.
• Don't ignore resource limits in deployments.
• Don't leave tunnel running when not needed.
• Don't use excessive resources for simple tests.

References

• Minikube Official Documentation
• Minikube Start Guide
• Pushing Images to Minikube
• Minikube Addons
• Troubleshooting Guide
• Hello Minikube Tutorial