turash/k8s/README.md

# 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

```bash
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

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

```bash
# 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**
```bash
# 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

```bash
# 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

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

#### Create Project (Optional)

```bash
kubectl apply -f k8s/argocd/project.yaml
```

#### Create Application

```bash
kubectl apply -f k8s/argocd/application.yaml
```

Or via ArgoCD CLI:

```bash
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

```bash
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

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

### Check Service

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

### Check Ingress

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

### Port Forward for Testing

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

### Check ArgoCD Application

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

## Database Migrations

Run migrations using the CLI tool:

```bash
# 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

```yaml
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'`