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:
```bash
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

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

## Step 3: Create Secrets

```bash
# 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

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

## Step 5: Build and Load Docker Image

```bash
# 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

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

## Step 7: Verify Deployment

```bash
# 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)

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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](https://docs.docker.com/desktop/kubernetes/)
- [kubectl Cheat Sheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
- [Kubernetes Documentation](https://kubernetes.io/docs/home/)