gcp-hockey-results/motm_app/helm-chart/motm-app/DEPLOYMENT.md

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

# 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

# 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

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

# 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

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

database:
  type: "postgresql"
  host: "postgresql-service"
  port: 5432
  name: "motm"
  username: "motm_user"

MySQL

database:
  type: "mysql"
  host: "mysql-service"
  port: 3306
  name: "motm"
  username: "motm_user"

SQLite (Development only)

database:
  type: "sqlite"
  # Other fields ignored for SQLite

S3 Configuration

For asset management (logos, images):

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:

secrets:
  dbPassword: "your-database-password"
  s3AccessKey: "your-s3-access-key"
  s3SecretKey: "your-s3-secret-key"

Or use external secret management:

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

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

logging:
  level: "INFO"  # DEBUG, INFO, WARNING, ERROR
  format: "json" # json, text

Metrics (Optional)

Add Prometheus metrics endpoint:

monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s

Scaling

Horizontal Pod Autoscaling

Enable HPA for production:

autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70
  targetMemoryUtilizationPercentage: 80

Resource Limits

Adjust based on your cluster capacity:

resources:
  limits:
    cpu: 1000m
    memory: 1Gi
  requests:
    cpu: 200m
    memory: 512Mi

Troubleshooting

Common Issues

1. Pod Not Starting

# 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

# 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

# Check S3 configuration
kubectl exec -n motm-app -it deployment/motm-app -- cat /app/s3_config.json

4. Ingress Issues

# 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

# 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

# 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

# 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

# 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