CoreDNS Integration Guide

Version: 1.0.0 Date: 2025-10-06 Author: CoreDNS Integration Agent

Table of Contents

1. Overview
2. Installation
3. Configuration
4. CLI Commands
5. Zone Management
6. Record Management
7. Docker Deployment
8. Integration
9. Troubleshooting
10. Advanced Topics

Overview

The CoreDNS integration provides comprehensive DNS management capabilities for the provisioning system. It supports:

• Local DNS service - Run CoreDNS as binary or Docker container
• Dynamic DNS updates - Automatic registration of infrastructure changes
• Multi-zone support - Manage multiple DNS zones
• Provider integration - Seamless integration with orchestrator
• REST API - Programmatic DNS management
• Docker deployment - Containerized CoreDNS with docker-compose

Key Features

✅ Automatic Server Registration - Servers automatically registered in DNS on creation ✅ Zone File Management - Create, update, and manage zone files programmatically ✅ Multiple Deployment Modes - Binary, Docker, remote, or hybrid ✅ Health Monitoring - Built-in health checks and metrics ✅ CLI Interface - Comprehensive command-line tools ✅ API Integration - REST API for external integration

Installation

Prerequisites

• Nushell 0.107+ - For CLI and scripts
• Docker (optional) - For containerized deployment
• dig (optional) - For DNS queries

Install CoreDNS Binary

# Install latest version
provisioning dns install

# Install specific version
provisioning dns install 1.11.1

# Check mode
provisioning dns install --check

The binary will be installed to ~/.provisioning/bin/coredns.

Verify Installation

# Check CoreDNS version
~/.provisioning/bin/coredns -version

# Verify installation
ls -lh ~/.provisioning/bin/coredns

Configuration

KCL Configuration Schema

Add CoreDNS configuration to your infrastructure config:

# In workspace/infra/{name}/config.k
import provisioning.coredns as dns

coredns_config: dns.CoreDNSConfig = {
    mode = "local"

    local = {
        enabled = True
        deployment_type = "binary"  # or "docker"
        binary_path = "~/.provisioning/bin/coredns"
        config_path = "~/.provisioning/coredns/Corefile"
        zones_path = "~/.provisioning/coredns/zones"
        port = 5353
        auto_start = True
        zones = ["provisioning.local", "workspace.local"]
    }

    dynamic_updates = {
        enabled = True
        api_endpoint = "http://localhost:9090/dns"
        auto_register_servers = True
        auto_unregister_servers = True
        ttl = 300
    }

    upstream = ["8.8.8.8", "1.1.1.1"]
    default_ttl = 3600
    enable_logging = True
    enable_metrics = True
    metrics_port = 9153
}

Configuration Modes

Local Mode (Binary)

Run CoreDNS as a local binary process:

coredns_config: CoreDNSConfig = {
    mode = "local"
    local = {
        deployment_type = "binary"
        auto_start = True
    }
}

Local Mode (Docker)

Run CoreDNS in Docker container:

coredns_config: CoreDNSConfig = {
    mode = "local"
    local = {
        deployment_type = "docker"
        docker = {
            image = "coredns/coredns:1.11.1"
            container_name = "provisioning-coredns"
            restart_policy = "unless-stopped"
        }
    }
}

Remote Mode

Connect to external CoreDNS service:

coredns_config: CoreDNSConfig = {
    mode = "remote"
    remote = {
        enabled = True
        endpoints = ["https://dns1.example.com", "https://dns2.example.com"]
        zones = ["production.local"]
        verify_tls = True
    }
}

Disabled Mode

Disable CoreDNS integration:

coredns_config: CoreDNSConfig = {
    mode = "disabled"
}

CLI Commands

Service Management

# Check status
provisioning dns status

# Start service
provisioning dns start

# Start in foreground (for debugging)
provisioning dns start --foreground

# Stop service
provisioning dns stop

# Restart service
provisioning dns restart

# Reload configuration (graceful)
provisioning dns reload

# View logs
provisioning dns logs

# Follow logs
provisioning dns logs --follow

# Show last 100 lines
provisioning dns logs --lines 100

Health & Monitoring

# Check health
provisioning dns health

# View configuration
provisioning dns config show

# Validate configuration
provisioning dns config validate

# Generate new Corefile
provisioning dns config generate

Zone Management

List Zones

# List all zones
provisioning dns zone list

Output:

DNS Zones
=========
  • provisioning.local ✓
  • workspace.local ✓

Create Zone

# Create new zone
provisioning dns zone create myapp.local

# Check mode
provisioning dns zone create myapp.local --check

Show Zone Details

# Show all records in zone
provisioning dns zone show provisioning.local

# JSON format
provisioning dns zone show provisioning.local --format json

# YAML format
provisioning dns zone show provisioning.local --format yaml

Delete Zone

# Delete zone (with confirmation)
provisioning dns zone delete myapp.local

# Force deletion (skip confirmation)
provisioning dns zone delete myapp.local --force

# Check mode
provisioning dns zone delete myapp.local --check

Record Management

Add Records

A Record (IPv4)

provisioning dns record add server-01 A 10.0.1.10

# With custom TTL
provisioning dns record add server-01 A 10.0.1.10 --ttl 600

# With comment
provisioning dns record add server-01 A 10.0.1.10 --comment "Web server"

# Different zone
provisioning dns record add server-01 A 10.0.1.10 --zone myapp.local

AAAA Record (IPv6)

provisioning dns record add server-01 AAAA 2001:db8::1

CNAME Record

provisioning dns record add web CNAME server-01.provisioning.local

MX Record

provisioning dns record add @ MX mail.example.com --priority 10

TXT Record

provisioning dns record add @ TXT "v=spf1 mx -all"

Remove Records

# Remove record
provisioning dns record remove server-01

# Different zone
provisioning dns record remove server-01 --zone myapp.local

# Check mode
provisioning dns record remove server-01 --check

Update Records

# Update record value
provisioning dns record update server-01 A 10.0.1.20

# With new TTL
provisioning dns record update server-01 A 10.0.1.20 --ttl 1800

List Records

# List all records in zone
provisioning dns record list

# Different zone
provisioning dns record list --zone myapp.local

# JSON format
provisioning dns record list --format json

# YAML format
provisioning dns record list --format yaml

Example Output:

DNS Records - Zone: provisioning.local

╭───┬──────────────┬──────┬─────────────┬─────╮
│ # │     name     │ type │    value    │ ttl │
├───┼──────────────┼──────┼─────────────┼─────┤
│ 0 │ server-01    │ A    │ 10.0.1.10   │ 300 │
│ 1 │ server-02    │ A    │ 10.0.1.11   │ 300 │
│ 2 │ db-01        │ A    │ 10.0.2.10   │ 300 │
│ 3 │ web          │ CNAME│ server-01   │ 300 │
╰───┴──────────────┴──────┴─────────────┴─────╯

Docker Deployment

Prerequisites

Ensure Docker and docker-compose are installed:

docker --version
docker-compose --version

Start CoreDNS in Docker

# Start CoreDNS container
provisioning dns docker start

# Check mode
provisioning dns docker start --check

Manage Docker Container

# Check status
provisioning dns docker status

# View logs
provisioning dns docker logs

# Follow logs
provisioning dns docker logs --follow

# Restart container
provisioning dns docker restart

# Stop container
provisioning dns docker stop

# Check health
provisioning dns docker health

Update Docker Image

# Pull latest image
provisioning dns docker pull

# Pull specific version
provisioning dns docker pull --version 1.11.1

# Update and restart
provisioning dns docker update

Remove Container

# Remove container (with confirmation)
provisioning dns docker remove

# Remove with volumes
provisioning dns docker remove --volumes

# Force remove (skip confirmation)
provisioning dns docker remove --force

# Check mode
provisioning dns docker remove --check

View Configuration

# Show docker-compose config
provisioning dns docker config

Integration

Automatic Server Registration

When dynamic DNS is enabled, servers are automatically registered:

# Create server (automatically registers in DNS)
provisioning server create web-01 --infra myapp

# Server gets DNS record: web-01.provisioning.local -> <server-ip>

Manual Registration

use lib_provisioning/coredns/integration.nu *

# Register server
register-server-in-dns "web-01" "10.0.1.10"

# Unregister server
unregister-server-from-dns "web-01"

# Bulk register
bulk-register-servers [
    {hostname: "web-01", ip: "10.0.1.10"}
    {hostname: "web-02", ip: "10.0.1.11"}
    {hostname: "db-01", ip: "10.0.2.10"}
]

Sync Infrastructure with DNS

# Sync all servers in infrastructure with DNS
provisioning dns sync myapp

# Check mode
provisioning dns sync myapp --check

Service Registration

use lib_provisioning/coredns/integration.nu *

# Register service
register-service-in-dns "api" "10.0.1.10"

# Unregister service
unregister-service-from-dns "api"

Query DNS

Using CLI

# Query A record
provisioning dns query server-01

# Query specific type
provisioning dns query server-01 --type AAAA

# Query different server
provisioning dns query server-01 --server 8.8.8.8 --port 53

# Query from local CoreDNS
provisioning dns query server-01 --server 127.0.0.1 --port 5353

Using dig

# Query from local CoreDNS
dig @127.0.0.1 -p 5353 server-01.provisioning.local

# Query CNAME
dig @127.0.0.1 -p 5353 web.provisioning.local CNAME

# Query MX
dig @127.0.0.1 -p 5353 example.com MX

Troubleshooting

CoreDNS Not Starting

Symptoms: dns start fails or service doesn’t respond

Solutions:

1. Check if port is in use:

   lsof -i :5353
   netstat -an | grep 5353
   

2. Validate Corefile:

   provisioning dns config validate
   

3. Check logs:

   provisioning dns logs
   tail -f ~/.provisioning/coredns/coredns.log
   

4. Verify binary exists:

   ls -lh ~/.provisioning/bin/coredns
   provisioning dns install
   

DNS Queries Not Working

Symptoms: dig returns SERVFAIL or timeout

Solutions:

1. Check CoreDNS is running:

   provisioning dns status
   provisioning dns health
   

2. Verify zone file exists:

   ls -lh ~/.provisioning/coredns/zones/
   cat ~/.provisioning/coredns/zones/provisioning.local.zone
   

3. Test with dig:

   dig @127.0.0.1 -p 5353 provisioning.local SOA
   

4. Check firewall:

   # macOS
   sudo pfctl -sr | grep 5353
   
   # Linux
   sudo iptables -L -n | grep 5353
   

Zone File Validation Errors

Symptoms: dns config validate shows errors

Solutions:

1. Backup zone file:

   cp ~/.provisioning/coredns/zones/provisioning.local.zone \
      ~/.provisioning/coredns/zones/provisioning.local.zone.backup
   

2. Regenerate zone:

   provisioning dns zone create provisioning.local --force
   

3. Check syntax manually:

   cat ~/.provisioning/coredns/zones/provisioning.local.zone
   

4. Increment serial:

   • Edit zone file manually
   • Increase serial number in SOA record

Docker Container Issues

Symptoms: Docker container won’t start or crashes

Solutions:

1. Check Docker logs:

   provisioning dns docker logs
   docker logs provisioning-coredns
   

2. Verify volumes exist:

   ls -lh ~/.provisioning/coredns/
   

3. Check container status:

   provisioning dns docker status
   docker ps -a | grep coredns
   

4. Recreate container:

   provisioning dns docker stop
   provisioning dns docker remove --volumes
   provisioning dns docker start
   

Dynamic Updates Not Working

Symptoms: Servers not auto-registered in DNS

Solutions:

1. Check if enabled:

   provisioning dns config show | grep -A 5 dynamic_updates
   

2. Verify orchestrator running:

   curl http://localhost:9090/health
   

3. Check logs for errors:

   provisioning dns logs | grep -i error
   

4. Test manual registration:

   use lib_provisioning/coredns/integration.nu *
   register-server-in-dns "test-server" "10.0.0.1"
   

Advanced Topics

Custom Corefile Plugins

Add custom plugins to Corefile:

use lib_provisioning/coredns/corefile.nu *

# Add plugin to zone
add-corefile-plugin \
    "~/.provisioning/coredns/Corefile" \
    "provisioning.local" \
    "cache 30"

Backup and Restore

# Backup configuration
tar czf coredns-backup.tar.gz ~/.provisioning/coredns/

# Restore configuration
tar xzf coredns-backup.tar.gz -C ~/

Zone File Backup

use lib_provisioning/coredns/zones.nu *

# Backup zone
backup-zone-file "provisioning.local"

# Creates: ~/.provisioning/coredns/zones/provisioning.local.zone.YYYYMMDD-HHMMSS.bak

Metrics and Monitoring

CoreDNS exposes Prometheus metrics on port 9153:

# View metrics
curl http://localhost:9153/metrics

# Common metrics:
# - coredns_dns_request_duration_seconds
# - coredns_dns_requests_total
# - coredns_dns_responses_total

Multi-Zone Setup

coredns_config: CoreDNSConfig = {
    local = {
        zones = [
            "provisioning.local",
            "workspace.local",
            "dev.local",
            "staging.local",
            "prod.local"
        ]
    }
}

Split-Horizon DNS

Configure different zones for internal/external:

coredns_config: CoreDNSConfig = {
    local = {
        zones = ["internal.local"]
        port = 5353
    }
    remote = {
        zones = ["external.com"]
        endpoints = ["https://dns.external.com"]
    }
}

Configuration Reference

CoreDNSConfig Fields

LocalCoreDNS Fields

DynamicDNS Fields

Examples

Complete Setup Example

# 1. Install CoreDNS
provisioning dns install

# 2. Generate configuration
provisioning dns config generate

# 3. Start service
provisioning dns start

# 4. Create custom zone
provisioning dns zone create myapp.local

# 5. Add DNS records
provisioning dns record add web-01 A 10.0.1.10
provisioning dns record add web-02 A 10.0.1.11
provisioning dns record add api CNAME web-01.myapp.local --zone myapp.local

# 6. Query records
provisioning dns query web-01 --server 127.0.0.1 --port 5353

# 7. Check status
provisioning dns status
provisioning dns health

Docker Deployment Example

# 1. Start CoreDNS in Docker
provisioning dns docker start

# 2. Check status
provisioning dns docker status

# 3. View logs
provisioning dns docker logs --follow

# 4. Add records (container must be running)
provisioning dns record add server-01 A 10.0.1.10

# 5. Query
dig @127.0.0.1 -p 5353 server-01.provisioning.local

# 6. Stop
provisioning dns docker stop

Best Practices

1. Use TTL wisely - Lower TTL (300s) for frequently changing records, higher (3600s) for stable
2. Enable logging - Essential for troubleshooting
3. Regular backups - Backup zone files before major changes
4. Validate before reload - Always run dns config validate before reloading
5. Monitor metrics - Track DNS query rates and error rates
6. Use comments - Add comments to records for documentation
7. Separate zones - Use different zones for different environments (dev, staging, prod)

See Also

• Architecture Documentation
• API Reference
• Orchestrator Integration
• KCL Schema Reference

Last Updated: 2025-10-06 Version: 1.0.0