Sankofa/docs/proxmox/DNS_CONFIGURATION.md

DNS Configuration for Proxmox Instances

Overview

This document describes DNS configuration for Proxmox instances using the sankofa.nexus domain.

DNS Records Required

Instance 1 (ML110-01)

Type	Name	Value	TTL	Purpose
A	ml110-01.sankofa.nexus	192.168.11.10	300	Primary FQDN
CNAME	ml110-01-api.sankofa.nexus	ml110-01.sankofa.nexus	300	API endpoint
CNAME	ml110-01-metrics.sankofa.nexus	ml110-01.sankofa.nexus	300	Metrics endpoint

Instance 2 (R630-01)

Type	Name	Value	TTL	Purpose
A	r630-01.sankofa.nexus	192.168.11.11	300	Primary FQDN
CNAME	r630-01-api.sankofa.nexus	r630-01.sankofa.nexus	300	API endpoint
CNAME	r630-01-metrics.sankofa.nexus	r630-01.sankofa.nexus	300	Metrics endpoint

Configuration Methods

Method 1: Cloudflare API (Automated)

Use the provided script to create DNS records via Cloudflare API:

# Set environment variables
export CLOUDFLARE_ZONE_ID="your-zone-id"
export CLOUDFLARE_API_TOKEN="your-api-token"
export DOMAIN="sankofa.nexus"

# Run the script
./scripts/setup-dns-records.sh

Prerequisites:

• Cloudflare account with sankofa.nexus zone
• API token with DNS edit permissions
• curl and jq installed

Method 2: Cloudflare Terraform

Use Terraform to manage DNS records as infrastructure:

cd cloudflare/terraform

# Initialize Terraform
terraform init

# Review plan
terraform plan

# Apply DNS records
terraform apply

Files:

• cloudflare/terraform/dns.tf - DNS record definitions

Method 3: Cloudflare Dashboard (Manual)

1. Log into Cloudflare dashboard
2. Select sankofa.nexus zone
3. Go to DNS → Records
4. Add records manually:

For Instance 1:

• Type: A, Name: ml110-01, Content: 192.168.11.10, TTL: Auto, Proxy: Off
• Type: CNAME, Name: ml110-01-api, Target: ml110-01.sankofa.nexus, TTL: Auto, Proxy: Off
• Type: CNAME, Name: ml110-01-metrics, Target: ml110-01.sankofa.nexus, TTL: Auto, Proxy: Off

For Instance 2:

• Type: A, Name: r630-01, Content: 192.168.11.11, TTL: Auto, Proxy: Off
• Type: CNAME, Name: r630-01-api, Target: r630-01.sankofa.nexus, TTL: Auto, Proxy: Off
• Type: CNAME, Name: r630-01-metrics, Target: r630-01.sankofa.nexus, TTL: Auto, Proxy: Off

Method 4: Local /etc/hosts (Testing)

For local testing before DNS is configured:

# Add entries to /etc/hosts
sudo cat scripts/hosts-entries.txt >> /etc/hosts

# Or manually edit /etc/hosts
sudo nano /etc/hosts

Note: This only works on the local machine. For production, use proper DNS.

Verification

Test DNS Resolution

# Test A records
dig ml110-01.sankofa.nexus +short
# Expected: 192.168.11.10

dig r630-01.sankofa.nexus +short
# Expected: 192.168.11.11

# Test CNAME records
dig ml110-01-api.sankofa.nexus +short
# Expected: ml110-01.sankofa.nexus

dig r630-01-metrics.sankofa.nexus +short
# Expected: r630-01.sankofa.nexus

# Test with nslookup
nslookup ml110-01.sankofa.nexus
nslookup r630-01.sankofa.nexus

Test HTTPS Connectivity

# Test Instance 1
curl -k https://ml110-01.sankofa.nexus:8006/api2/json/version

# Test Instance 2
curl -k https://r630-01.sankofa.nexus:8006/api2/json/version

Test from Kubernetes Pod

# Test DNS resolution from within cluster
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup ml110-01.sankofa.nexus
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup r630-01.sankofa.nexus

DNS Record Details

A Records

A records provide direct IP address mapping:

• Purpose: Primary hostname resolution
• TTL: 300 seconds (5 minutes) - allows quick updates
• Proxy: Disabled (direct connection, not proxied through Cloudflare)

CNAME Records

CNAME records create aliases:

• Purpose: Provide alternative endpoints (API, metrics)
• TTL: 300 seconds (5 minutes)
• Proxy: Disabled (direct connection)

Cloudflare Tunnel Integration

When using Cloudflare Tunnels, DNS records should point to tunnel endpoints:

# For tunnel-based access (if using Cloudflare proxy)
# A records would point to tunnel CNAME:
# ml110-01.sankofa.nexus → <tunnel-id>.cfargotunnel.com

Current Configuration: Direct IP access (no proxy) for internal network access.

Troubleshooting

DNS Not Resolving

1. Check DNS propagation:

   dig @8.8.8.8 ml110-01.sankofa.nexus
   dig @1.1.1.1 ml110-01.sankofa.nexus
   

2. Check local DNS cache:

   # Linux
   sudo systemd-resolve --flush-caches
   
   # macOS
   sudo dscacheutil -flushcache
   
   # Windows
   ipconfig /flushdns
   

3. Verify records exist:

   # Using Cloudflare API
   curl -X GET \
     -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
     "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/dns_records?name=ml110-01.sankofa.nexus"
   

Wrong IP Address

1. Update A record:

   # Use setup-dns-records.sh script
   # Or update via Cloudflare dashboard
   # Or use Terraform to update
   

2. Wait for TTL expiration (300 seconds)

CNAME Resolution Issues

1. Verify target exists:

   dig ml110-01.sankofa.nexus  # Should resolve first
   dig ml110-01-api.sankofa.nexus  # Then test CNAME
   

2. Check for CNAME chains (should be avoided)

Security Considerations

1. Internal Network Only: These IPs (192.168.11.x) are private, so DNS should only be accessible from internal networks or via VPN.

2. No Public Exposure: Do not expose these records publicly if they point to private IPs.

3. Access Control: Use Cloudflare Access policies if exposing via tunnels.

Related Documentation

• Cloudflare Tunnel Configuration
• Site Mapping
• TLS Configuration

Scripts

• scripts/setup-dns-records.sh - Automated DNS record creation
• scripts/hosts-entries.txt - Local /etc/hosts entries
• cloudflare/terraform/dns.tf - Terraform DNS configuration