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

# 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:

# 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

# 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:

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:

# 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

# 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

# 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

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

# Or edit the kustomization.yaml replicas section and reapply

Clean Up

# 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:

# 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

# 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