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:

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

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

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

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

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

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

```yaml
# 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**:
   ```bash
   dig @8.8.8.8 ml110-01.sankofa.nexus
   dig @1.1.1.1 ml110-01.sankofa.nexus
   ```

2. **Check local DNS cache**:
   ```bash
   # Linux
   sudo systemd-resolve --flush-caches
   
   # macOS
   sudo dscacheutil -flushcache
   
   # Windows
   ipconfig /flushdns
   ```

3. **Verify records exist**:
   ```bash
   # 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**:
   ```bash
   # 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**:
   ```bash
   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](../cloudflare/tunnel-configs/)
- [Site Mapping](./SITE_MAPPING.md)
- [TLS Configuration](./TLS_CONFIGURATION.md)

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