turash/k8s

Turash Backend - Kubernetes Deployment

This directory contains Kubernetes manifests and ArgoCD configuration for deploying the Turash backend application.

Architecture

The deployment includes:

• Backend API: Go application serving on port 8080
• PostgreSQL + PostGIS: Spatial database (managed separately or via StatefulSet)
• Neo4j: Graph database (managed separately or via StatefulSet)
• Redis: Caching layer (managed separately or via StatefulSet)
• NATS: Message queue (managed separately or via StatefulSet)

Prerequisites

1. Kubernetes Cluster (k3s/k8s) with:

   • ArgoCD installed and configured
   • Ingress controller (nginx-ingress recommended)
   • Metrics server (for HPA)
   • Storage class for persistent volumes

2. Container Registry:

   • Image should be built and pushed to ghcr.io/samyrai/turash-backend:latest
   • Or update the image reference in deployment.yaml

3. Secrets Management:

   • Create secrets using the template provided
   • Use sealed-secrets, external-secrets, or your preferred solution

Quick Start

1. Build and Push Docker Image

cd bugulma/backend
docker build -t ghcr.io/samyrai/turash-backend:latest -f Dockerfile .
docker push ghcr.io/samyrai/turash-backend:latest

2. Create Secrets

# Copy the template
cp k8s/secret.yaml.template k8s/secret.yaml

# Edit secret.yaml with your actual values
# IMPORTANT: Add secret.yaml to .gitignore!

# Create the secret
kubectl create secret generic turash-backend-secret \
  --from-env-file=k8s/secret.yaml \
  --namespace=turash \
  --dry-run=client -o yaml | kubectl apply -f -

Or using sealed-secrets:

# Install kubeseal if not already installed
kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.24.0/controller.yaml

# Create sealed secret
kubectl create secret generic turash-backend-secret \
  --from-env-file=k8s/secret.yaml \
  --namespace=turash \
  --dry-run=client -o yaml | kubeseal -o yaml > k8s/sealed-secret.yaml

3. Deploy Infrastructure Services

The backend depends on PostgreSQL, Neo4j, Redis, and NATS. You can either:

Option A: Use existing managed services

• Update service names in configmap.yaml to point to your managed services

Option B: Deploy via Helm charts

# PostgreSQL with PostGIS
helm repo add bitnami https://charts.bitnami.com/bitnami
helm install turash-postgres bitnami/postgresql \
  --namespace turash \
  --set postgresqlDatabase=turash \
  --set postgresqlUsername=turash \
  --set postgresqlPassword=YOUR_PASSWORD \
  --set image.tag=16-postgis

# Neo4j
helm repo add neo4j https://helm.neo4j.com/neo4j
helm install turash-neo4j neo4j/neo4j \
  --namespace turash \
  --set neo4j.password=YOUR_PASSWORD

# Redis
helm install turash-redis bitnami/redis \
  --namespace turash \
  --set auth.password=YOUR_PASSWORD

# NATS
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
helm install turash-nats nats/nats \
  --namespace turash

4. Deploy Application Manually

# Create namespace
kubectl apply -f k8s/namespace.yaml

# Apply ConfigMap
kubectl apply -f k8s/configmap.yaml

# Apply Secret (or sealed-secret)
kubectl apply -f k8s/secret.yaml

# Apply Deployment
kubectl apply -f k8s/deployment.yaml

# Apply Service
kubectl apply -f k8s/service.yaml

# Apply Ingress (optional)
kubectl apply -f k8s/ingress.yaml

# Apply HPA
kubectl apply -f k8s/hpa.yaml

# Apply PDB
kubectl apply -f k8s/pdb.yaml

5. Deploy via ArgoCD

Add Repository to ArgoCD

argocd repo add https://github.com/SamyRai/turash.git \
  --name turash \
  --type git

Create Project (Optional)

kubectl apply -f k8s/argocd/project.yaml

Create Application

kubectl apply -f k8s/argocd/application.yaml

Or via ArgoCD CLI:

argocd app create turash-backend \
  --repo https://github.com/SamyRai/turash.git \
  --path k8s \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace turash \
  --project default \
  --sync-policy automated \
  --self-heal \
  --auto-prune

Sync Application

argocd app sync turash-backend

Configuration

Environment Variables

The application uses the following environment variables (configured via ConfigMap and Secret):

ConfigMap (non-sensitive):

• SERVER_PORT: Server port (default: 8080)
• GIN_MODE: Gin framework mode (release/debug)
• LOG_LEVEL: Logging level (info/debug)
• POSTGRES_HOST: PostgreSQL hostname
• POSTGRES_PORT: PostgreSQL port
• POSTGRES_DB: Database name
• NEO4J_URI: Neo4j connection URI
• REDIS_URL: Redis connection URL
• NATS_URL: NATS connection URL

Secret (sensitive):

• JWT_SECRET: JWT signing secret
• POSTGRES_USER: PostgreSQL username
• POSTGRES_PASSWORD: PostgreSQL password
• NEO4J_PASSWORD: Neo4j password
• REDIS_PASSWORD: Redis password

Resource Limits

Default resource requests/limits:

• Requests: 256Mi memory, 100m CPU
• Limits: 512Mi memory, 500m CPU

Adjust in deployment.yaml based on your workload.

Scaling

The HPA is configured to:

• Scale between 2-10 replicas
• Target 70% CPU utilization
• Target 80% memory utilization

Adjust in hpa.yaml as needed.

Monitoring

Health Checks

The application exposes a /health endpoint used for:

• Liveness probe: Checks every 10s after 30s initial delay
• Readiness probe: Checks every 5s after 10s initial delay

Metrics

If Prometheus is installed, metrics are exposed at /metrics endpoint.

Troubleshooting

Check Pod Status

kubectl get pods -n turash
kubectl describe pod <pod-name> -n turash
kubectl logs <pod-name> -n turash

Check Service

kubectl get svc -n turash
kubectl describe svc turash-backend -n turash

Check Ingress

kubectl get ingress -n turash
kubectl describe ingress turash-backend-ingress -n turash

Port Forward for Testing

kubectl port-forward -n turash svc/turash-backend 8080:80
curl http://localhost:8080/health

Check ArgoCD Application

argocd app get turash-backend
argocd app logs turash-backend
argocd app history turash-backend

Database Migrations

Run migrations using the CLI tool:

# Port forward to backend pod
kubectl port-forward -n turash deployment/turash-backend 8080:8080

# Or exec into pod
kubectl exec -it -n turash deployment/turash-backend -- ./bugulma-cli migrate up

CI/CD Integration

GitHub Actions Example

name: Build and Deploy
on:
  push:
    branches: [master]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker image
        run: |
          docker build -t ghcr.io/samyrai/turash-backend:${{ github.sha }} -f bugulma/backend/Dockerfile bugulma/backend
          docker push ghcr.io/samyrai/turash-backend:${{ github.sha }}          
      
      - name: Update deployment image
        run: |
          sed -i "s|image:.*|image: ghcr.io/samyrai/turash-backend:${{ github.sha }}|" k8s/deployment.yaml
          git commit -am "Update image to ${{ github.sha }}"
          git push          

ArgoCD will automatically sync the updated deployment.

Security Considerations

1. Secrets: Never commit secrets to git. Use sealed-secrets or external-secrets.
2. Image Security: Scan images for vulnerabilities before deployment.
3. Network Policies: Consider adding NetworkPolicies to restrict pod-to-pod communication.
4. RBAC: Configure appropriate RBAC rules for service accounts.
5. TLS: Enable TLS for ingress and use cert-manager for automatic certificate management.

Production Checklist

• Update all default passwords in secrets
• Configure TLS certificates for ingress
• Set up monitoring and alerting
• Configure backup strategy for databases
• Review and adjust resource limits
• Set up log aggregation
• Configure network policies
• Enable pod security policies
• Set up CI/CD pipeline
• Document runbooks for common issues

Support

For issues or questions:

• Check application logs: kubectl logs -n turash deployment/turash-backend
• Check ArgoCD sync status: argocd app get turash-backend
• Review Kubernetes events: kubectl get events -n turash --sort-by='.lastTimestamp'