minikube

Overview

Minikube runs a single-node Kubernetes cluster locally for development and testing. It supports multiple container runtimes (Docker, containerd, CRI-O) and provides easy addon management.

Installation

macOS

# Homebrew
brew install minikube

# Or direct download
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-darwin-arm64
sudo install minikube-darwin-arm64 /usr/local/bin/minikube

Linux

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

Windows (WSL2)

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

Essential Commands

Cluster Management

# Start cluster (uses Docker driver by default)
minikube start

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

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

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

# Check cluster status
minikube status

# Stop cluster (preserves state)
minikube stop

# Delete cluster completely
minikube delete

# Delete all clusters and profiles
minikube delete --all

Multiple Profiles

# Create named cluster
minikube start -p my-cluster

# Switch between clusters
minikube profile my-cluster

# List all profiles
minikube profile list

# Delete specific profile
minikube delete -p my-cluster

Accessing the Cluster

# Open Kubernetes dashboard
minikube dashboard

# Get cluster IP
minikube ip

# SSH into the node
minikube ssh

# Access service via URL
minikube service <service-name> --url

# Open service in browser
minikube service <service-name>

Addons

Minikube addons extend cluster functionality:

List and Enable Addons

# List all available addons
minikube addons list

# Enable addon
minikube addons enable <addon-name>

# Disable addon
minikube addons disable <addon-name>

Essential Addons for TaskFlow

# Ingress controller (REQUIRED for external access)
minikube addons enable ingress

# Ingress DNS (optional, for local DNS)
minikube addons enable ingress-dns

# Metrics server (for kubectl top)
minikube addons enable metrics-server

# Dashboard (web UI)
minikube addons enable dashboard

# Storage provisioner (for PVCs)
minikube addons enable storage-provisioner

# Registry (local container registry)
minikube addons enable registry

Full Setup for TaskFlow

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

# Enable essential addons
minikube addons enable ingress
minikube addons enable metrics-server
minikube addons enable storage-provisioner
minikube addons enable dashboard

Networking

Accessing Services

Three ways to access services in Minikube:

1. NodePort Service

# Get service URL
minikube service my-service --url
# Returns: http://192.168.49.2:30080

2. Minikube Tunnel (LoadBalancer)

# Run in separate terminal (requires sudo)
minikube tunnel

# Now LoadBalancer services get external IPs
kubectl get svc
# EXTERNAL-IP will show actual IP instead of <pending>

3. Port Forwarding

kubectl port-forward svc/my-service 8080:80
# Access at http://localhost:8080

Ingress Setup

# Enable ingress addon
minikube addons enable ingress

# Get minikube IP
minikube ip
# Returns: 192.168.49.2

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

# Now access via: http://taskflow.local

Using Local Docker Images

Load Image into Minikube

# Load from local Docker
minikube image load my-image:tag

# List images in Minikube
minikube image list

Build Directly in Minikube

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

# Now docker build goes directly into Minikube
docker build -t my-app:local .

# Use imagePullPolicy: Never in K8s manifests

Reset Docker Environment

# Return to local Docker daemon
eval $(minikube docker-env -u)

Configuration

Set Default Memory/CPU

minikube config set memory 8192
minikube config set cpus 4
minikube config set driver docker

View Configuration

minikube config view

Debugging

Logs

# Minikube logs
minikube logs

# Follow logs
minikube logs -f

# Specific component logs
minikube logs --file=kubelet

Common Issues

1. Insufficient Resources

# Stop and restart with more resources
minikube stop
minikube start --memory=8192 --cpus=4

2. Driver Issues

# Try different driver
minikube delete
minikube start --driver=docker

3. Ingress Not Working

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

# Check ingress controller logs
kubectl logs -n ingress-nginx -l app.kubernetes.io/component=controller

4. Services Not Accessible

# Check if tunnel is needed
minikube tunnel  # Run in separate terminal

# Or use NodePort
minikube service <service-name>

TaskFlow Deployment Workflow

# 1. Start Minikube
minikube start --memory=8192 --cpus=4

# 2. Enable addons
minikube addons enable ingress
minikube addons enable metrics-server

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

# 4. Build images locally
docker build -t taskflow/api:local ./packages/api
docker build -t taskflow/web:local ./web-dashboard
docker build -t taskflow/sso:local ./sso-platform
docker build -t taskflow/mcp-server:local ./packages/mcp-server

# 5. Deploy with Helm
helm install taskflow ./helm/taskflow \
  --set api.image.tag=local \
  --set api.image.pullPolicy=Never \
  --set web.image.tag=local \
  --set web.image.pullPolicy=Never

# 6. Start tunnel for LoadBalancer
minikube tunnel

# 7. Access application
minikube service taskflow-web

Quick Reference

| Command | Purpose | |---------|---------| | minikube start | Start cluster | | minikube stop | Stop cluster | | minikube delete | Delete cluster | | minikube status | Check status | | minikube dashboard | Open web UI | | minikube addons list | List addons | | minikube service <svc> | Access service | | minikube tunnel | Enable LoadBalancer | | minikube ip | Get cluster IP | | minikube image load <img> | Load Docker image | | eval $(minikube docker-env) | Use Minikube Docker |

Resources

Refer to references/addons-guide.md for detailed addon configurations.