proxmox/docs/04-configuration/PHOENIX_DNS_ZONE_TEMPLATE.md

# Phoenix DNS Zone Template

**Domain:** phoenix.sankofa.nexus  
**Zone:** sankofa.nexus (Cloudflare)  
**Version:** 1.0.0  
**Last Updated:** 2026-01-09
**Status:** Active Documentation

---

## Overview

This document defines the DNS zone configuration for Phoenix Core services. DNS records enable external access to Phoenix services via domain names.

**DNS Strategy:** DNS-only mode (gray cloud) for direct NAT routing. No Cloudflare proxy initially to enable direct IP routing.

---

## DNS Records

### Required Records

| Record Name | Type | Content | Proxy | TTL | Purpose |
|-------------|------|---------|-------|-----|---------|
| `api.phoenix.sankofa.nexus` | A | 10.160.0.10 | DNS Only | 300 | Phoenix API endpoint |
| `auth.phoenix.sankofa.nexus` | A | 10.160.0.12 | DNS Only | 300 | Keycloak authentication |
| `portal.phoenix.sankofa.nexus` | A | 10.160.0.11 | DNS Only | 300 | Phoenix Portal web interface |

### Optional Records

| Record Name | Type | Content | Proxy | TTL | Purpose |
|-------------|------|---------|-------|-----|---------|
| `phoenix.sankofa.nexus` | A or CNAME | 10.160.0.11 (or `portal.phoenix.sankofa.nexus`) | DNS Only | 300 | Primary Phoenix domain (redirects to portal) |
| `www.phoenix.sankofa.nexus` | CNAME | `phoenix.sankofa.nexus` | DNS Only | 300 | WWW alias for primary domain |

**Note:** The existing `phoenix.sankofa.nexus` and `www.phoenix.sankofa.nexus` records may already exist in Cloudflare. Update them to point to the new Phoenix deployment.

---

## Cloudflare Configuration

### Zone Information

- **Zone ID:** (Retrieve from Cloudflare dashboard or use `scripts/update-all-dns-to-public-ip.sh` pattern)
- **Zone Name:** sankofa.nexus
- **DNS Provider:** Cloudflare

### DNS Mode: DNS Only (Gray Cloud)

**Why DNS Only?**
- Enables direct NAT routing through ER605
- Allows role-based egress NAT (Block #5 when assigned)
- Supports future NAT-based access patterns

**Proxy Mode:** Disabled (gray cloud) for all Phoenix records.

---

## DNS Record Details

### Record 1: API Endpoint

**Name:** `api.phoenix.sankofa.nexus`  
**Type:** A  
**Content:** `10.160.0.10`  
**Proxy:** DNS Only (gray cloud)  
**TTL:** 300 (5 minutes)

**Purpose:**  
- GraphQL API endpoint
- Health check endpoint
- Service-to-service communication endpoint

**Endpoints:**
- `http://api.phoenix.sankofa.nexus:4000/graphql` - GraphQL API
- `http://api.phoenix.sankofa.nexus:4000/health` - Health check

**Cloudflare API Command:**
```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" \
  -d '{
    "type": "A",
    "name": "api.phoenix",
    "content": "10.160.0.10",
    "ttl": 300,
    "proxied": false,
    "comment": "Phoenix API endpoint"
  }'
```

### Record 2: Authentication Endpoint

**Name:** `auth.phoenix.sankofa.nexus`  
**Type:** A  
**Content:** `10.160.0.12`  
**Proxy:** DNS Only (gray cloud)  
**TTL:** 300 (5 minutes)

**Purpose:**  
- Keycloak authentication server
- OAuth/OIDC token issuance
- User authentication and authorization

**Endpoints:**
- `http://auth.phoenix.sankofa.nexus:8080` - Keycloak base URL
- `http://auth.phoenix.sankofa.nexus:8080/admin` - Admin console
- `http://auth.phoenix.sankofa.nexus:8080/health/ready` - Health check

**Cloudflare API Command:**
```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" \
  -d '{
    "type": "A",
    "name": "auth.phoenix",
    "content": "10.160.0.12",
    "ttl": 300,
    "proxied": false,
    "comment": "Phoenix Keycloak authentication"
  }'
```

### Record 3: Portal Endpoint

**Name:** `portal.phoenix.sankofa.nexus`  
**Type:** A  
**Content:** `10.160.0.11`  
**Proxy:** DNS Only (gray cloud)  
**TTL:** 300 (5 minutes)

**Purpose:**  
- Phoenix Portal web interface
- User-facing application
- Primary entry point for end users

**Endpoints:**
- `http://portal.phoenix.sankofa.nexus:3000` - Portal web interface

**Cloudflare API Command:**
```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" \
  -d '{
    "type": "A",
    "name": "portal.phoenix",
    "content": "10.160.0.11",
    "ttl": 300,
    "proxied": false,
    "comment": "Phoenix Portal web interface"
  }'
```

### Record 4: Primary Domain (Optional)

**Name:** `phoenix.sankofa.nexus`  
**Type:** A (or CNAME to `portal.phoenix.sankofa.nexus`)  
**Content:** `10.160.0.11` (or `portal.phoenix.sankofa.nexus`)  
**Proxy:** DNS Only (gray cloud)  
**TTL:** 300 (5 minutes)

**Purpose:**  
- Primary Phoenix domain
- Redirects to portal (or serves portal directly)

**Option A - A Record:**
```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" \
  -d '{
    "type": "A",
    "name": "phoenix",
    "content": "10.160.0.11",
    "ttl": 300,
    "proxied": false,
    "comment": "Phoenix primary domain"
  }'
```

**Option B - CNAME (Recommended if portal domain exists):**
```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" \
  -d '{
    "type": "CNAME",
    "name": "phoenix",
    "content": "portal.phoenix.sankofa.nexus",
    "ttl": 300,
    "proxied": false,
    "comment": "Phoenix primary domain (CNAME to portal)"
  }'
```

**Note:** If `phoenix.sankofa.nexus` already exists, update it instead of creating a new record.

### Record 5: WWW Alias (Optional)

**Name:** `www.phoenix.sankofa.nexus`  
**Type:** CNAME  
**Content:** `phoenix.sankofa.nexus`  
**Proxy:** DNS Only (gray cloud)  
**TTL:** 300 (5 minutes)

**Purpose:**  
- WWW alias for primary domain
- Common convention for web domains

**Cloudflare API Command:**
```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" \
  -d '{
    "type": "CNAME",
    "name": "www.phoenix",
    "content": "phoenix.sankofa.nexus",
    "ttl": 300,
    "proxied": false,
    "comment": "Phoenix WWW alias"
  }'
```

**Note:** If `www.phoenix.sankofa.nexus` already exists, update it instead of creating a new record.

---

## DNS Cutover Procedure

### Pre-Cutover Checklist

- [ ] All Phoenix services deployed and validated
- [ ] All validation gates passed (see deployment runbook)
- [ ] Firewall rules configured (see firewall rules document)
- [ ] NAT routing configured (if using direct NAT)
- [ ] SSL/TLS certificates ready (if using HTTPS)
- [ ] DNS records prepared (this document)

### Step 1: Verify Current DNS Records

**Check existing records:**
```bash
# Check if phoenix.sankofa.nexus exists
dig phoenix.sankofa.nexus +short

# Check all phoenix.* records
dig +short TXT phoenix.sankofa.nexus
```

### Step 2: Create/Update DNS Records

**Option A: Using Cloudflare API (Automated)**

```bash
# Set environment variables
export CLOUDFLARE_API_TOKEN="your-token-here"
export ZONE_ID_SANKOFA_NEXUS="your-zone-id-here"

# Create/update records (see Cloudflare API commands above)
# Or use existing script: scripts/update-all-dns-to-public-ip.sh
```

**Option B: Using Cloudflare Dashboard (Manual)**

1. Log in to Cloudflare dashboard
2. Navigate to: **DNS** → **Records**
3. For each record:
   - If record exists: Click **Edit**, update content, ensure proxy is disabled (gray cloud)
   - If record doesn't exist: Click **Add record**, create new record

### Step 3: Verify DNS Propagation

**Test DNS resolution:**
```bash
# Test each record
dig api.phoenix.sankofa.nexus +short
dig auth.phoenix.sankofa.nexus +short
dig portal.phoenix.sankofa.nexus +short
dig phoenix.sankofa.nexus +short
dig www.phoenix.sankofa.nexus +short

# Expected: All should return 10.160.0.10, 10.160.0.12, or 10.160.0.11
```

**Wait for propagation:**
- Cloudflare: Usually instant
- Global DNS: 1-5 minutes
- Some resolvers: Up to 24 hours (rare)

### Step 4: Test Service Access

**After DNS propagation, test each endpoint:**
```bash
# Test API (may fail without NAT routing, but DNS should resolve)
curl -v http://api.phoenix.sankofa.nexus:4000/health

# Test Keycloak
curl -v http://auth.phoenix.sankofa.nexus:8080/health/ready

# Test Portal
curl -v http://portal.phoenix.sankofa.nexus:3000
```

**Note:** These tests may fail if NAT routing is not yet configured. DNS resolution is the key verification at this stage.

### Step 5: Rollback Procedure (If Needed)

**If issues are discovered after DNS cutover:**

1. **Revert DNS records** to previous values (or delete new records)
2. **Legacy services (7800-series) become active again** automatically
3. **Phoenix services remain running** but unreachable via DNS

**Cloudflare API - Delete Record:**
```bash
# Get record ID first
RECORD_ID=$(curl -s -X GET "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records?name=api.phoenix.sankofa.nexus" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" | jq -r '.result[0].id')

# Delete record
curl -X DELETE "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records/${RECORD_ID}" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json"
```

---

## DNS Record Priority

**When to use each record:**

1. **Development/Testing:** Use subdomain records (`api.*`, `auth.*`, `portal.*`)
2. **Production:** Use subdomain records + primary domain (`phoenix.sankofa.nexus`)
3. **User-Friendly:** Use primary domain (`phoenix.sankofa.nexus`) as main entry point

---

## Future Enhancements

### SSL/TLS Certificates

**When HTTPS is implemented:**

- Use Let's Encrypt certificates
- Configure Nginx reverse proxy on ER605 or separate container
- Update DNS to point to HTTPS endpoints
- Update service URLs in documentation

### Cloudflare Proxy Mode

**If Cloudflare proxy is needed later:**

1. Enable proxy (orange cloud) for DDoS protection
2. Configure Cloudflare Access for additional security
3. Update firewall rules to allow Cloudflare IP ranges
4. Note: Proxy mode requires public IP routing, not direct NAT

---

## Verification Commands

### Check DNS Resolution

```bash
# Test DNS resolution
dig api.phoenix.sankofa.nexus +short
dig auth.phoenix.sankofa.nexus +short
dig portal.phoenix.sankofa.nexus +short

# Test with different DNS servers
dig @1.1.1.1 api.phoenix.sankofa.nexus +short
dig @8.8.8.8 api.phoenix.sankofa.nexus +short
```

### Check Cloudflare Records

```bash
# Using Cloudflare API
curl -s -X GET "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records?name=api.phoenix.sankofa.nexus" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" | jq '.result[]'
```

### Test Service Connectivity (After NAT Configuration)

```bash
# Test API
curl -v http://api.phoenix.sankofa.nexus:4000/health

# Test Keycloak
curl -v http://auth.phoenix.sankofa.nexus:8080/health/ready

# Test Portal
curl -v http://portal.phoenix.sankofa.nexus:3000
```

---

## Integration with Existing DNS Automation

**Existing Script:** `scripts/update-all-dns-to-public-ip.sh`

This script already includes `phoenix.sankofa.nexus` and `www.phoenix.sankofa.nexus` records. 

**To add Phoenix-specific records:**

1. **Option A:** Extend the existing script to include `api.phoenix.*`, `auth.phoenix.*`, `portal.phoenix.*`
2. **Option B:** Create a separate script for Phoenix-specific DNS management
3. **Option C:** Use Cloudflare dashboard for one-time setup, then manage via API

**Note:** The existing script uses a single public IP (76.53.10.35). Phoenix uses private IPs (10.160.0.x) which require NAT routing. DNS records may need to point to a NAT gateway IP instead of direct private IPs, depending on the NAT configuration.

---

## DNS Record Maintenance

### Regular Tasks

1. **Monitor DNS propagation:** Check resolution from multiple locations
2. **Verify record correctness:** Ensure IPs match actual service IPs
3. **Update TTL as needed:** Lower TTL (300s) for faster updates, higher TTL (3600s) for stability
4. **Document changes:** Keep a log of DNS record changes

### Change Management

**Before making changes:**
- Document current DNS state
- Create backup of DNS records (export from Cloudflare)
- Plan rollback procedure
- Notify stakeholders

**After making changes:**
- Verify DNS propagation
- Test service access
- Monitor for issues
- Update documentation

---

## Related Documentation

- **Phoenix Deployment Runbook:** `docs/03-deployment/PHOENIX_DEPLOYMENT_RUNBOOK.md`
- **Phoenix Firewall Rules:** `docs/04-configuration/PHOENIX_VLAN160_FIREWALL_RULES.md`
- **Network Architecture:** `docs/02-architecture/NETWORK_ARCHITECTURE.md`
- **DNS Update Script:** `scripts/update-all-dns-to-public-ip.sh`

---

**Last Updated:** 2026-01-09  
**Status:** Ready for Implementation  
**Next Review:** After DNS cutover