Add base kubernetes support
This commit is contained in:
Urtzi Alfaro
262
infrastructure/kubernetes/README.md
Normal file
262
infrastructure/kubernetes/README.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user