bakery-ia/infrastructure/kubernetes/README.md

# Bakery IA Kubernetes Configuration

This directory contains Kubernetes manifests for deploying the Bakery IA forecasting platform in a local development environment.

## Prerequisites

1. **Kubernetes Cluster**: Ensure you have a local Kubernetes cluster running (minikube, kind, Docker Desktop, etc.)
2. **kubectl**: Install and configure kubectl to communicate with your cluster
3. **Kustomize**: Built into kubectl v1.14+, or install separately
4. **NGINX Ingress Controller**: Required for ingress functionality

### Install NGINX Ingress Controller

```bash
# For minikube
minikube addons enable ingress

# For kind
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml

# For Docker Desktop
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml
```

## Directory Structure

```
infrastructure/kubernetes/
├── base/                           # Base Kubernetes resources
│   ├── namespace.yaml             # Namespace definition
│   ├── configmap.yaml             # Shared configuration
│   ├── secrets.yaml               # Secrets (base64 encoded)
│   ├── ingress.yaml               # Ingress rules
│   └── kustomization.yaml         # Base kustomization
├── components/                     # Individual component manifests
│   ├── auth/                      # Auth service
│   ├── tenant/                    # Tenant service
│   ├── training/                  # Training service
│   ├── forecasting/               # Forecasting service
│   ├── sales/                     # Sales service
│   ├── external/                  # External service
│   ├── notification/              # Notification service
│   ├── inventory/                 # Inventory service
│   ├── recipes/                   # Recipes service
│   ├── suppliers/                 # Suppliers service
│   ├── pos/                       # POS service
│   ├── orders/                    # Orders service
│   ├── production/                # Production service
│   ├── alert-processor/           # Alert processor
│   ├── frontend/                  # Frontend application
│   ├── databases/                 # Database deployments
│   └── infrastructure/            # Infrastructure components (gateway, etc.)
└── overlays/
    └── dev/                       # Development environment overlay
        ├── kustomization.yaml     # Dev-specific kustomization
        └── dev-patches.yaml       # Development patches
```

## Quick Start

### 1. Build and Deploy Images (if needed)

First, ensure your Docker images are built and available to your Kubernetes cluster:

```bash
# Build all services
docker-compose build

# For minikube, use minikube's Docker daemon
eval $(minikube docker-env)
docker-compose build

# For kind, load images into the cluster
kind load docker-image bakery/auth-service:latest
kind load docker-image bakery/tenant-service:latest
# ... repeat for all services
```

### 2. Deploy to Kubernetes

```bash
# Deploy the development environment
kubectl apply -k infrastructure/kubernetes/overlays/dev/

# Check deployment status
kubectl get pods -n bakery-ia
kubectl get services -n bakery-ia
kubectl get ingress -n bakery-ia
```

### 3. Access the Application

Add the following to your `/etc/hosts` file (or Windows equivalent):

```
127.0.0.1 bakery-ia.local
127.0.0.1 api.bakery-ia.local
127.0.0.1 monitoring.bakery-ia.local
```

For minikube, get the ingress IP:
```bash
minikube ip
# Use this IP instead of 127.0.0.1 in your hosts file
```

Access the application:
- Frontend: http://bakery-ia.local or http://localhost:3000
- API Gateway: http://api.bakery-ia.local or http://localhost:8000/api
- Individual services: Check service NodePorts or use port-forwarding

## Port Forwarding for Direct Access

If you prefer to access services directly without ingress:

```bash
# Frontend
kubectl port-forward -n bakery-ia svc/frontend-service 3000:3000

# Gateway
kubectl port-forward -n bakery-ia svc/gateway-service 8000:8000

# Auth Service
kubectl port-forward -n bakery-ia svc/auth-service 8001:8000

# Redis
kubectl port-forward -n bakery-ia svc/redis-service 6379:6379

# Database example (auth-db)
kubectl port-forward -n bakery-ia svc/auth-db-service 5432:5432
```

## Managing the Deployment

### Check Status

```bash
# Check all resources
kubectl get all -n bakery-ia

# Check specific resource types
kubectl get pods -n bakery-ia
kubectl get services -n bakery-ia
kubectl get deployments -n bakery-ia
kubectl get pvc -n bakery-ia

# Check logs
kubectl logs -n bakery-ia deployment/auth-service
kubectl logs -n bakery-ia deployment/frontend -f  # Follow logs
```

### Update Deployments

```bash
# After making changes to manifests
kubectl apply -k infrastructure/kubernetes/overlays/dev/

# Force restart a deployment
kubectl rollout restart -n bakery-ia deployment/auth-service

# Check rollout status
kubectl rollout status -n bakery-ia deployment/auth-service
```

### Scaling Services

```bash
# Scale a service
kubectl scale -n bakery-ia deployment/auth-service --replicas=3

# Or edit the kustomization.yaml replicas section and reapply
```

### Clean Up

```bash
# Delete everything
kubectl delete -k infrastructure/kubernetes/overlays/dev/

# Or delete just the namespace (removes everything in it)
kubectl delete namespace bakery-ia
```

## Configuration

### Secrets

The `secrets.yaml` file contains base64-encoded secrets. For production, these should be:
1. Generated securely
2. Managed through external secret management systems
3. Not committed to version control

To encode/decode secrets:
```bash
# Encode
echo -n "your-secret-value" | base64

# Decode
echo "eW91ci1zZWNyZXQtdmFsdWU=" | base64 -d
```

### Environment-Specific Configuration

Modify the `overlays/dev/` files to customize the development environment:
- `kustomization.yaml`: Image tags, replicas, resource references
- `dev-patches.yaml`: Environment-specific configuration overrides

### Adding New Services

1. Create a new directory under `components/`
2. Add the service YAML manifest
3. Update `base/kustomization.yaml` to include the new resource
4. Update configuration maps and secrets as needed

## Troubleshooting

### Common Issues

1. **Images not found**: Ensure images are built and available to the cluster
2. **Pending pods**: Check resource requests and cluster capacity
3. **CrashLoopBackOff**: Check logs and environment variables
4. **Service not accessible**: Verify ingress controller is running and hosts file is configured

### Debugging Commands

```bash
# Describe resources for detailed information
kubectl describe pod -n bakery-ia <pod-name>
kubectl describe deployment -n bakery-ia <deployment-name>

# Get events
kubectl get events -n bakery-ia --sort-by='.firstTimestamp'

# Execute commands in pods
kubectl exec -n bakery-ia -it <pod-name> -- bash
kubectl exec -n bakery-ia -it <pod-name> -- env

# Check resource usage
kubectl top pods -n bakery-ia
kubectl top nodes
```

## Production Considerations

For production deployment, consider:

1. **Resource Limits**: Set appropriate CPU and memory limits
2. **Persistent Volumes**: Use proper storage classes for databases
3. **Secrets Management**: Use external secret management (HashiCorp Vault, AWS Secrets Manager, etc.)
4. **Monitoring**: Deploy Prometheus and Grafana
5. **Backup**: Implement database backup strategies
6. **High Availability**: Use multiple replicas and anti-affinity rules
7. **Security**: Network policies, RBAC, pod security policies
8. **CI/CD**: Integrate with your deployment pipeline

## Next Steps

1. Add monitoring with Prometheus and Grafana
2. Implement proper logging with ELK stack or similar
3. Add health checks and metrics endpoints
4. Implement automated testing
5. Set up CI/CD pipelines for automated deployments