minikube-local-deployment-pattern

name

minikube-local-deployment-pattern

description

Deploy and test applications on local Minikube Kubernetes cluster. Use for: loading local Docker images to Minikube, exposing services locally via port-forward or minikube service, debugging pods (logs, describe, exec), troubleshooting CrashLoopBackOff/ImagePullBackOff errors. Triggers: "deploy to minikube", "minikube image load", "port-forward", "minikube service", "debug pod", "why is pod crashing", "minikube dashboard", "local kubernetes testing". NOT for: minikube installation, minikube start/stop, cloud Kubernetes, Helm charts, or writing YAML manifests (use kubernetes-yaml-best-practices for YAML).

Minikube Local Deployment Pattern

Deploy and debug applications on local Minikube cluster.

Assumptions

• Minikube is already running (do NOT run minikube start unless explicitly asked)
• User has kubectl configured for minikube context

Core Workflow

1. Load Local Image

Always use minikube image load for local Docker images:

# Build and load (preferred for local development)
docker build -t myapp:dev .
minikube image load myapp:dev

# Verify image is loaded
minikube image ls | grep myapp

Important: Set imagePullPolicy: Never in Deployment YAML when using local images.

2. Apply Manifests

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

# Or apply all in directory
kubectl apply -f ./k8s/

3. Expose Service Locally

Option A: minikube service (recommended)

# Opens browser automatically
minikube service <service-name>

# Get URL only
minikube service <service-name> --url

Option B: kubectl port-forward

# Forward service
kubectl port-forward svc/<service-name> 8080:80

# Forward specific pod
kubectl port-forward pod/<pod-name> 8080:3000

4. Verify Deployment

kubectl get pods -w              # Watch pod status
kubectl get svc                  # List services
kubectl get all                  # Overview of resources

Debugging Commands

Command	Purpose
kubectl logs <pod>	View container logs
kubectl logs <pod> -f	Stream logs
kubectl logs <pod> --previous	Logs from crashed container
kubectl describe pod <pod>	Detailed pod info + events
kubectl exec -it <pod> -- /bin/sh	Shell into container
kubectl get events --sort-by=.lastTimestamp	Recent cluster events
minikube dashboard	Open K8s dashboard UI
minikube ip	Get cluster IP

Quick Troubleshooting

Status	Likely Cause	Fix
ImagePullBackOff	Image not in minikube	minikube image load <image> + set imagePullPolicy: Never
CrashLoopBackOff	App crashing on start	kubectl logs <pod> --previous to see crash reason
Pending	Resource constraints	kubectl describe pod → check Events section
0/1 Ready	Readiness probe failing	Check probe path/port matches app

For detailed troubleshooting scenarios: See references/troubleshooting.md

Local Image Deployment Template

# Minimal deployment for local image
spec:
  containers:
    - name: myapp
      image: myapp:dev
      imagePullPolicy: Never  # REQUIRED for minikube image load

Common Patterns

Full redeploy after code change:

docker build -t myapp:dev . && \
minikube image load myapp:dev && \
kubectl rollout restart deployment/<deployment-name>

Quick cleanup:

kubectl delete -f ./k8s/