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:

```rust
// 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:

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

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

## Configuration

DNS settings in `config.defaults.toml`:

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

```http
GET /api/v1/dns/records
```

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

## Usage Examples

### Register Server DNS

```rust
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

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

### Update DNS Record

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

### List All Records

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

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