370 lines
7.3 KiB
Markdown
370 lines
7.3 KiB
Markdown
# MOTM App Kubernetes Deployment Guide
|
|
|
|
This guide provides step-by-step instructions for deploying the MOTM (Man of the Match) Hockey Voting Application to a Kubernetes cluster using Helm.
|
|
|
|
## Prerequisites
|
|
|
|
### Required Tools
|
|
- **Kubernetes Cluster** (version 1.19+)
|
|
- **Helm** (version 3.0+)
|
|
- **kubectl** (configured for your cluster)
|
|
- **Docker** (for building images)
|
|
|
|
### Required Services
|
|
- **PostgreSQL Database** (or MySQL/SQLite)
|
|
- **S3-compatible Storage** (optional, for asset management)
|
|
|
|
## Quick Start
|
|
|
|
### 1. Build and Push Docker Image
|
|
|
|
```bash
|
|
# Navigate to the application directory
|
|
cd /home/jonny/Projects/gcp-hockey-results/motm_app
|
|
|
|
# Build the Docker image
|
|
docker build -t your-registry/motm-app:latest .
|
|
|
|
# Push to your container registry
|
|
docker push your-registry/motm-app:latest
|
|
```
|
|
|
|
### 2. Deploy to Development
|
|
|
|
```bash
|
|
# Navigate to the helm chart directory
|
|
cd helm-chart/motm-app
|
|
|
|
# Update the image repository in values-development.yaml
|
|
sed -i 's/your-registry\/motm-app/your-actual-registry\/motm-app/g' values-development.yaml
|
|
|
|
# Deploy using the deployment script
|
|
./scripts/deploy.sh development install
|
|
```
|
|
|
|
### 3. Deploy to Production
|
|
|
|
```bash
|
|
# Update production values
|
|
cp values-production.yaml my-production-values.yaml
|
|
# Edit my-production-values.yaml with your production settings
|
|
|
|
# Deploy to production
|
|
./scripts/deploy.sh production install
|
|
```
|
|
|
|
## Manual Deployment
|
|
|
|
### 1. Customize Values
|
|
|
|
Edit the appropriate values file:
|
|
|
|
```bash
|
|
# For development
|
|
vim values-development.yaml
|
|
|
|
# For production
|
|
vim values-production.yaml
|
|
```
|
|
|
|
Key values to update:
|
|
- `image.repository`: Your container registry
|
|
- `database.host`: Database service name
|
|
- `ingress.hosts[0].host`: Your domain name
|
|
- `secrets.*`: Database and S3 credentials
|
|
|
|
### 2. Install with Helm
|
|
|
|
```bash
|
|
# Development
|
|
helm install motm-app ./motm-app \
|
|
--namespace motm-app \
|
|
--values values-development.yaml \
|
|
--create-namespace
|
|
|
|
# Production
|
|
helm install motm-app ./motm-app \
|
|
--namespace motm-app \
|
|
--values values-production.yaml \
|
|
--create-namespace
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Database Setup
|
|
|
|
The application supports multiple database types:
|
|
|
|
#### PostgreSQL (Recommended)
|
|
```yaml
|
|
database:
|
|
type: "postgresql"
|
|
host: "postgresql-service"
|
|
port: 5432
|
|
name: "motm"
|
|
username: "motm_user"
|
|
```
|
|
|
|
#### MySQL
|
|
```yaml
|
|
database:
|
|
type: "mysql"
|
|
host: "mysql-service"
|
|
port: 3306
|
|
name: "motm"
|
|
username: "motm_user"
|
|
```
|
|
|
|
#### SQLite (Development only)
|
|
```yaml
|
|
database:
|
|
type: "sqlite"
|
|
# Other fields ignored for SQLite
|
|
```
|
|
|
|
### S3 Configuration
|
|
|
|
For asset management (logos, images):
|
|
|
|
```yaml
|
|
s3:
|
|
enabled: true
|
|
endpoint: "https://s3.amazonaws.com"
|
|
region: "us-east-1"
|
|
bucket: "motm-assets"
|
|
# Credentials set via secrets
|
|
```
|
|
|
|
### Security Configuration
|
|
|
|
#### Secrets Management
|
|
|
|
Set secrets via Helm values or external secret management:
|
|
|
|
```yaml
|
|
secrets:
|
|
dbPassword: "your-database-password"
|
|
s3AccessKey: "your-s3-access-key"
|
|
s3SecretKey: "your-s3-secret-key"
|
|
```
|
|
|
|
Or use external secret management:
|
|
```bash
|
|
# Create secrets manually
|
|
kubectl create secret generic motm-app-secrets \
|
|
--from-literal=db-password=your-password \
|
|
--from-literal=s3-access-key=your-key \
|
|
--from-literal=s3-secret-key=your-secret \
|
|
--namespace motm-app
|
|
```
|
|
|
|
#### Network Policies
|
|
|
|
For enhanced security, create network policies:
|
|
|
|
```yaml
|
|
# network-policy.yaml
|
|
apiVersion: networking.k8s.io/v1
|
|
kind: NetworkPolicy
|
|
metadata:
|
|
name: motm-app-netpol
|
|
spec:
|
|
podSelector:
|
|
matchLabels:
|
|
app.kubernetes.io/name: motm-app
|
|
policyTypes:
|
|
- Ingress
|
|
- Egress
|
|
ingress:
|
|
- from:
|
|
- namespaceSelector:
|
|
matchLabels:
|
|
name: ingress-nginx
|
|
egress:
|
|
- to:
|
|
- namespaceSelector:
|
|
matchLabels:
|
|
name: postgresql
|
|
```
|
|
|
|
## Monitoring and Observability
|
|
|
|
### Health Checks
|
|
|
|
The application includes built-in health checks:
|
|
- **Liveness Probe**: Checks if the application is running
|
|
- **Readiness Probe**: Checks if the application is ready to serve traffic
|
|
|
|
### Logging
|
|
|
|
Configure log levels in values:
|
|
|
|
```yaml
|
|
logging:
|
|
level: "INFO" # DEBUG, INFO, WARNING, ERROR
|
|
format: "json" # json, text
|
|
```
|
|
|
|
### Metrics (Optional)
|
|
|
|
Add Prometheus metrics endpoint:
|
|
|
|
```yaml
|
|
monitoring:
|
|
enabled: true
|
|
serviceMonitor:
|
|
enabled: true
|
|
interval: 30s
|
|
```
|
|
|
|
## Scaling
|
|
|
|
### Horizontal Pod Autoscaling
|
|
|
|
Enable HPA for production:
|
|
|
|
```yaml
|
|
autoscaling:
|
|
enabled: true
|
|
minReplicas: 2
|
|
maxReplicas: 10
|
|
targetCPUUtilizationPercentage: 70
|
|
targetMemoryUtilizationPercentage: 80
|
|
```
|
|
|
|
### Resource Limits
|
|
|
|
Adjust based on your cluster capacity:
|
|
|
|
```yaml
|
|
resources:
|
|
limits:
|
|
cpu: 1000m
|
|
memory: 1Gi
|
|
requests:
|
|
cpu: 200m
|
|
memory: 512Mi
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### 1. Pod Not Starting
|
|
```bash
|
|
# Check pod status
|
|
kubectl get pods -n motm-app -l app.kubernetes.io/name=motm-app
|
|
|
|
# Check pod logs
|
|
kubectl logs -n motm-app -l app.kubernetes.io/name=motm-app
|
|
```
|
|
|
|
#### 2. Database Connection Issues
|
|
```bash
|
|
# Test database connectivity
|
|
kubectl exec -n motm-app -it deployment/motm-app -- python -c "
|
|
from database import sql_read_static
|
|
from sqlalchemy import text
|
|
try:
|
|
result = sql_read_static(text('SELECT 1'))
|
|
print('Database connection successful')
|
|
except Exception as e:
|
|
print(f'Database connection failed: {e}')
|
|
"
|
|
```
|
|
|
|
#### 3. S3 Connection Issues
|
|
```bash
|
|
# Check S3 configuration
|
|
kubectl exec -n motm-app -it deployment/motm-app -- cat /app/s3_config.json
|
|
```
|
|
|
|
#### 4. Ingress Issues
|
|
```bash
|
|
# Check ingress status
|
|
kubectl get ingress -n motm-app
|
|
|
|
# Check ingress controller logs
|
|
kubectl logs -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
|
|
```
|
|
|
|
### Debugging Commands
|
|
|
|
```bash
|
|
# Get all resources
|
|
kubectl get all -n motm-app
|
|
|
|
# Describe deployment
|
|
kubectl describe deployment -n motm-app motm-app
|
|
|
|
# Check events
|
|
kubectl get events -n motm-app --sort-by='.lastTimestamp'
|
|
|
|
# Port forward for local testing
|
|
kubectl port-forward -n motm-app svc/motm-app 8080:80
|
|
```
|
|
|
|
## Maintenance
|
|
|
|
### Updates
|
|
|
|
```bash
|
|
# Update application
|
|
helm upgrade motm-app ./motm-app \
|
|
--namespace motm-app \
|
|
--values values-production.yaml
|
|
|
|
# Rollback if needed
|
|
helm rollback motm-app 1 --namespace motm-app
|
|
```
|
|
|
|
### Backup
|
|
|
|
```bash
|
|
# Backup database (PostgreSQL)
|
|
kubectl exec -n postgresql postgresql-0 -- pg_dump -U motm_user motm > backup.sql
|
|
|
|
# Backup application data
|
|
kubectl exec -n motm-app deployment/motm-app -- tar -czf /tmp/data-backup.tar.gz /app/data
|
|
kubectl cp motm-app/deployment/motm-app:/tmp/data-backup.tar.gz ./data-backup.tar.gz
|
|
```
|
|
|
|
### Cleanup
|
|
|
|
```bash
|
|
# Uninstall application
|
|
helm uninstall motm-app --namespace motm-app
|
|
|
|
# Delete namespace (if no other resources)
|
|
kubectl delete namespace motm-app
|
|
```
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Use Non-Root Containers**: The application runs as non-root user (UID 1000)
|
|
2. **Read-Only Root Filesystem**: Enable in production values
|
|
3. **Network Policies**: Implement to restrict pod-to-pod communication
|
|
4. **RBAC**: Use dedicated service accounts with minimal permissions
|
|
5. **Secret Management**: Use external secret management solutions
|
|
6. **Image Security**: Scan images for vulnerabilities
|
|
7. **TLS**: Enable TLS for all ingress traffic
|
|
8. **Resource Limits**: Set appropriate CPU and memory limits
|
|
|
|
## Support
|
|
|
|
For issues and questions:
|
|
1. Check the application logs
|
|
2. Review Kubernetes events
|
|
3. Consult the Helm chart documentation
|
|
4. Create an issue in the repository
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|