prvng_platform/orchestrator/docs/DNS_INTEGRATION.md

DNS Integration Guide

Overview

The DNS integration module provides automatic DNS registration and management for provisioned servers through CoreDNS integration.

Architecture

┌─────────────────┐
│  Orchestrator   │
│   (Rust)        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  DNS Manager    │
│                 │
│  - Auto-register│
│  - TTL config   │
│  - Verification │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ CoreDNS Client  │
│  (HTTP API)     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    CoreDNS      │
│   Service       │
└─────────────────┘

Features

1. Automatic DNS Registration

When a server is created, the orchestrator automatically registers its DNS record:

// In server creation workflow
let ip = server.get_ip_address();
state.dns_manager.register_server_dns(&hostname, ip).await?;

2. DNS Record Types

Supports multiple DNS record types:

• A - IPv4 address
• AAAA - IPv6 address
• CNAME - Canonical name
• TXT - Text record

3. DNS Verification

Verify DNS resolution after registration:

let verified = state.dns_manager.verify_dns_resolution("server.example.com").await?;
if verified {
    info!("DNS resolution verified");
}

4. Automatic Cleanup

When a server is deleted, DNS records are automatically removed:

state.dns_manager.unregister_server_dns(&hostname).await?;

Configuration

DNS settings in config.defaults.toml:

[orchestrator.dns]
coredns_url = "http://localhost:53"
auto_register = true
ttl = 300

Configuration Options

• coredns_url: CoreDNS HTTP API endpoint
• auto_register: Enable automatic DNS registration (default: true)
• ttl: Default TTL for DNS records in seconds (default: 300)

API Endpoints

List DNS Records

GET /api/v1/dns/records

Response:

{
  "success": true,
  "data": [
    {
      "name": "web-01.example.com",
      "record_type": "A",
      "value": "192.168.1.10",
      "ttl": 300
    }
  ]
}

Usage Examples

Register Server DNS

use std::net::IpAddr;

let ip: IpAddr = "192.168.1.10".parse()?;
dns_manager.register_server_dns("web-01.example.com", ip).await?;

Unregister Server DNS

dns_manager.unregister_server_dns("web-01.example.com").await?;

Update DNS Record

let new_ip: IpAddr = "192.168.1.20".parse()?;
dns_manager.update_dns_record("web-01.example.com", new_ip).await?;

List All Records

let records = dns_manager.list_records().await?;
for record in records {
    println!("{} -> {} ({})", record.name, record.value, record.record_type);
}

Integration with Workflows

Server Creation Workflow

1. Create server via provider API
2. Wait for server to be ready
3. Register DNS record (automatic)
4. Verify DNS resolution
5. Continue with next steps

Server Deletion Workflow

1. Stop services on server
2. Unregister DNS record (automatic)
3. Delete server via provider API
4. Update inventory

Error Handling

The DNS integration handles errors gracefully:

• Network errors: Retries with exponential backoff
• DNS conflicts: Reports error but continues workflow
• Invalid records: Validates before sending to CoreDNS

Testing

Run DNS integration tests:

cd provisioning/platform/orchestrator
cargo test test_dns_integration

Troubleshooting

DNS registration fails

1. Check CoreDNS is running and accessible
2. Verify coredns_url configuration
3. Check network connectivity
4. Review orchestrator logs

DNS records not resolving

1. Verify record was registered (check logs)
2. Query CoreDNS directly
3. Check TTL settings
4. Verify DNS resolver configuration

Best Practices

1. Use FQDN: Always use fully-qualified domain names
2. Set appropriate TTL: Lower TTL for dev, higher for prod
3. Enable auto-register: Reduces manual operations
4. Monitor DNS health: Check DNS resolution periodically

Security Considerations

1. Access Control: Restrict access to CoreDNS API
2. Validation: Validate hostnames and IP addresses
3. Audit: Log all DNS operations
4. Rate Limiting: Prevent DNS flooding

Future Enhancements

• Support for SRV records
• DNS zone management
• DNSSEC integration
• Multi-zone support
• DNS caching layer