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:

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:

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:

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:

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

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:

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:

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

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

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

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

# 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

# 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

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

# 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