pos-system/microservices/deployments/local/kubernetes/README.md

Local Kubernetes Deployment Guide (Docker Desktop)

Prerequisites

• Docker Desktop for macOS M4 Max
• kubectl CLI installed
• Minimum 8GB RAM allocated to Docker Desktop

Step 1: Enable Kubernetes in Docker Desktop

1. Open Docker Desktop
2. Go to Settings (gear icon)
3. Click Kubernetes tab
4. Check Enable Kubernetes
5. Click Apply & Restart
6. Wait for Kubernetes to start (green indicator)

Verify installation:

kubectl version --client
kubectl cluster-info
kubectl get nodes

Expected output:

NAME             STATUS   ROLES           AGE   VERSION
docker-desktop   Ready    control-plane   1d    v1.28.2

Step 2: Create Local Namespace

kubectl create namespace iam-local
kubectl config set-context --current --namespace=iam-local

Step 3: Create Secrets

# Generate strong secrets (DO NOT use these in production!)
JWT_SECRET=$(openssl rand -base64 32)
JWT_REFRESH_SECRET=$(openssl rand -base64 32)
JWT_ID_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)

# Create Kubernetes secret
kubectl create secret generic iam-service-secrets \
  --from-literal=jwt-secret="$JWT_SECRET" \
  --from-literal=jwt-refresh-secret="$JWT_REFRESH_SECRET" \
  --from-literal=jwt-id-secret="$JWT_ID_SECRET" \
  --from-literal=encryption-key="$ENCRYPTION_KEY" \
  --from-literal=database-url="postgresql://username:password@host.neon.tech/database?sslmode=require" \
  -n iam-local

IMPORTANT: Update database-url with your actual Neon PostgreSQL connection string.

Step 4: Create ConfigMap

kubectl apply -f deployments/local/kubernetes/iam-service-configmap.yaml -n iam-local

Step 5: Build and Load Docker Image

# Build image
cd /Users/velikho/Desktop/WORKING/Base
docker build -t iam-service:local -f services/iam-service/Dockerfile .

# Verify image
docker images | grep iam-service

Note: Docker Desktop Kubernetes can access images built locally, no need to push to registry.

Step 6: Deploy Service

kubectl apply -f deployments/local/kubernetes/iam-service-deployment.yaml -n iam-local

Step 7: Verify Deployment

# Check pods
kubectl get pods -n iam-local

# Check deployment
kubectl get deployment -n iam-local

# Check logs
kubectl logs -f deployment/iam-service -n iam-local

# Describe pod (if issues)
kubectl describe pod <pod-name> -n iam-local

Step 8: Expose Service (LoadBalancer)

kubectl apply -f deployments/local/kubernetes/iam-service-service.yaml -n iam-local

For Docker Desktop, LoadBalancer will be available at localhost.

Step 9: Test Endpoints

# Get service URL
kubectl get svc iam-service -n iam-local

# Test health
curl http://localhost:<PORT>/health/live
curl http://localhost:<PORT>/health/ready

# Test registration
curl -X POST http://localhost:<PORT>/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"k8s-test@example.com","password":"Test@123456","username":"k8suser"}'

Step 10: Run Database Migrations

# Port-forward to access service
kubectl port-forward deployment/iam-service 5001:5001 -n iam-local

# In another terminal, run migrations
cd services/iam-service
DATABASE_URL="<your-neon-db-url>" pnpm prisma:deploy

Troubleshooting

Pod Not Starting

# Check events
kubectl get events -n iam-local --sort-by='.lastTimestamp'

# Check pod logs
kubectl logs <pod-name> -n iam-local

# Check pod description
kubectl describe pod <pod-name> -n iam-local

Common issues:

• ImagePullBackOff: Image not found locally, rebuild image
• CrashLoopBackOff: Check logs for errors, verify secrets/configmap
• Pending: Resource constraints, check Docker Desktop RAM allocation

Service Not Accessible

# Check service
kubectl get svc -n iam-local

# Check endpoints
kubectl get endpoints -n iam-local

# Port forward for testing
kubectl port-forward svc/iam-service 5001:80 -n iam-local

Database Connection Issues

• Verify DATABASE_URL in secret
• Check if Neon database allows connections from your IP
• Test connection manually: psql <database-url>

Cleanup

# Delete all resources
kubectl delete namespace iam-local

# Or delete individual resources
kubectl delete deployment iam-service -n iam-local
kubectl delete service iam-service -n iam-local
kubectl delete configmap iam-service-config -n iam-local
kubectl delete secret iam-service-secrets -n iam-local

Next Steps

After successful local K8s deployment:

1. Test all API endpoints
2. Verify health checks
3. Test autoscaling (HPA)
4. Test rolling updates
5. Simulate pod failures

Differences from Production

Aspect	Local K8s	Production K8s
Cluster	Docker Desktop	Cloud (GKE/EKS/AKS)
LoadBalancer	localhost	Cloud LB with public IP
Ingress	Optional	Required (with TLS)
Secrets	kubectl create	External secrets manager
Database	Neon (shared)	Dedicated production DB
Monitoring	Optional	Required (Prometheus/Grafana)
Replicas	1-2	3+ with HPA
Resources	Minimal	Production-grade limits

Resources

• Docker Desktop Kubernetes
• kubectl Cheat Sheet
• Kubernetes Documentation