Sankofa/docs/configs/cloudflare/README.md

# Cloudflare Tunnel Configuration Guide

## Overview
This guide covers configuring the Cloudflare Tunnel VM for SMOM-DBIS-138 deployment to provide secure public access.

## Prerequisites
- Cloudflare Tunnel VM deployed and running
- SSH access to the VM
- Cloudflare account with Zero Trust enabled
- Domain configured in Cloudflare

## Quick Start

### 1. Get VM IP Address
```bash
kubectl get proxmoxvm cloudflare-tunnel-vm -n default -o jsonpath='{.status.ipAddress}'
```

### 2. Create Tunnel in Cloudflare

#### Option A: Via Cloudflare Dashboard
1. Go to Zero Trust → Networks → Tunnels
2. Click "Create a tunnel"
3. Select "Cloudflared"
4. Name it: `smom-dbis-138-tunnel`
5. Copy the tunnel token

#### Option B: Via API
```bash
./scripts/configure-cloudflare.sh
```

### 3. SSH into the VM
```bash
ssh admin@<vm-ip-address>
```

### 4. Configure Tunnel Credentials
```bash
# Create credentials file
sudo mkdir -p /etc/cloudflared
sudo nano /etc/cloudflared/tunnel-credentials.json
```

Paste the tunnel credentials JSON:
```json
{
  "AccountTag": "your-account-tag",
  "TunnelSecret": "your-tunnel-secret",
  "TunnelID": "your-tunnel-id",
  "TunnelName": "smom-dbis-138-tunnel"
}
```

### 5. Configure Tunnel
```bash
# Copy configuration template
sudo cp /path/to/tunnel-config.yaml /etc/cloudflared/config.yaml

# Edit configuration
sudo nano /etc/cloudflared/config.yaml
```

### 6. Start Tunnel Service
```bash
# Start service
sudo systemctl start cloudflared

# Enable auto-start
sudo systemctl enable cloudflared

# Check status
sudo systemctl status cloudflared
```

## Configuration Details

### Tunnel Credentials
Location: `/etc/cloudflared/tunnel-credentials.json`

Contains:
- AccountTag: Your Cloudflare account ID
- TunnelSecret: Secret key for the tunnel
- TunnelID: Unique tunnel identifier
- TunnelName: Human-readable tunnel name

### Tunnel Configuration
Location: `/etc/cloudflared/config.yaml`

Key sections:
- `tunnel`: Tunnel name (must match credentials)
- `credentials-file`: Path to credentials JSON
- `ingress`: Routing rules for services
- `metrics`: Prometheus metrics endpoint
- `health-probe`: Health check configuration

## Ingress Rules

### Pattern
```yaml
ingress:
  - hostname: service.example.com
    service: http://backend-service:port
    originRequest:
      connectTimeout: 30s
      tcpKeepAlive: 30s
```

### Important Notes
- Rules are evaluated in order (first match wins)
- Catch-all rule (`http_status:404`) must be last
- Use internal hostnames or IPs for backend services

## DNS Configuration

For each hostname in ingress rules, create a CNAME record:
```
Type: CNAME
Name: smom-api
Content: <tunnel-id>.cfargotunnel.com
Proxy: Enabled (orange cloud)
```

Or use Cloudflare API:
```bash
curl -X POST "https://api.cloudflare.com/client/v4/zones/{zone_id}/dns_records" \
  -H "Authorization: Bearer {api_token}" \
  -H "Content-Type: application/json" \
  --data '{
    "type": "CNAME",
    "name": "smom-api",
    "content": "<tunnel-id>.cfargotunnel.com",
    "proxied": true
  }'
```

## Monitoring

### Check Tunnel Status
```bash
sudo systemctl status cloudflared
```

### View Logs
```bash
sudo tail -f /var/log/cloudflared/tunnel.log
```

### Metrics Endpoint
```bash
curl http://localhost:9090/metrics
```

## Troubleshooting

### Tunnel Not Connecting
1. Verify credentials file is correct
2. Check tunnel is created in Cloudflare dashboard
3. Verify DNS records point to tunnel
4. Check firewall allows outbound HTTPS (443)

### Service Not Accessible
1. Verify ingress rule matches hostname
2. Check backend service is running
3. Verify internal network connectivity
4. Check tunnel logs for errors

### Test Connection
```bash
# Test from Cloudflare Tunnel VM
curl http://backend-service:port

# Test from external
curl https://your-domain.com
```

## Security Best Practices

1. **Rotate Tunnel Secrets**: Regularly rotate tunnel credentials
2. **Use Access Policies**: Configure Cloudflare Access for authentication
3. **Monitor Logs**: Review tunnel logs for suspicious activity
4. **Limit Ingress Rules**: Only expose necessary services
5. **Use Private Networks**: Keep backend services on private networks

## Next Steps
1. Configure Cloudflare Access policies
2. Set up monitoring and alerting
3. Configure rate limiting
4. Set up backup tunnel for redundancy