minikube-local-development

@mub7865/minikube-local-development

0 forks

Updated 4/6/2026

Complete guide for local Kubernetes development with Minikube: installation, configuration, image management, addons, networking, and troubleshooting for efficient local development workflows.

Installation

$npx agent-skills-cli install @mub7865/minikube-local-development

Claude Code

Cursor

Copilot

Codex

Antigravity

Details

Repositorymub7865/Hackathone-2

Path.claude/skills/minikube-local-development/SKILL.md

Branchmain

Scoped Name@mub7865/minikube-local-development

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

npx agent-skills-cli list

Skill Instructions

name: minikube-local-development description: > Complete guide for local Kubernetes development with Minikube: installation, configuration, image management, addons, networking, and troubleshooting for efficient local development workflows.

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

Platform	Requirements
Windows	Docker Desktop or Hyper-V enabled
macOS	Docker Desktop or HyperKit
Linux	Docker or KVM

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

Driver	Platform	Description
docker	All	Uses Docker containers (recommended)
hyperv	Windows	Uses Hyper-V VMs
virtualbox	All	Uses VirtualBox VMs
kvm2	Linux	Uses KVM VMs
hyperkit	macOS	Uses HyperKit VMs
podman	All	Uses Podman containers

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

Policy	Description	Use Case
`Never`	Never pull from registry	Local images only
`IfNotPresent`	Pull only if not local	Local first, then registry
`Always`	Always pull (default for :latest)	Always use registry

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

Addon	Description	Command
dashboard	Web UI for Kubernetes	`minikube addons enable dashboard`
ingress	NGINX Ingress controller	`minikube addons enable ingress`
metrics-server	Resource metrics	`minikube addons enable metrics-server`
registry	Local Docker registry	`minikube addons enable registry`
storage-provisioner	Dynamic storage	Enabled by default

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

More by mub7865

View all

kubernetes-deployment-patterns

Complete patterns for deploying applications on Kubernetes: Deployments, Services, ConfigMaps, Secrets, health probes, resource management, and production-ready configurations for any application.

helm-chart-creation

Complete patterns for creating and managing Helm charts: chart structure, templates, values, dependencies, and deployment workflows for packaging Kubernetes applications.

openai-chatkit-frontend

Patterns for building AI chatbot frontends using OpenAI ChatKit with Next.js App Router, including custom backend integration via ChatKit Python SDK.

docker-containerization

Complete patterns for containerizing applications with Docker: Dockerfiles, multi-stage builds, layer optimization, security best practices, and production-ready configurations for Python/FastAPI and Node.js/Next.js apps.