# CoreDNS Integration Guide\n\n**Version**: 1.0.0\n**Date**: 2025-10-06\n**Author**: CoreDNS Integration Agent\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Installation](#installation)\n3. [Configuration](#configuration)\n4. [CLI Commands](#cli-commands)\n5. [Zone Management](#zone-management)\n6. [Record Management](#record-management)\n7. [Docker Deployment](#docker-deployment)\n8. [Integration](#integration)\n9. [Troubleshooting](#troubleshooting)\n10. [Advanced Topics](#advanced-topics)\n\n---\n\n## Overview\n\nThe CoreDNS integration provides comprehensive DNS management capabilities for the provisioning system. It supports:\n\n- **Local DNS service** - Run CoreDNS as binary or Docker container\n- **Dynamic DNS updates** - Automatic registration of infrastructure changes\n- **Multi-zone support** - Manage multiple DNS zones\n- **Provider integration** - Seamless integration with orchestrator\n- **REST API** - Programmatic DNS management\n- **Docker deployment** - Containerized CoreDNS with docker-compose\n\n### Key Features\n\n✅ **Automatic Server Registration** - Servers automatically registered in DNS on creation\n✅ **Zone File Management** - Create, update, and manage zone files programmatically\n✅ **Multiple Deployment Modes** - Binary, Docker, remote, or hybrid\n✅ **Health Monitoring** - Built-in health checks and metrics\n✅ **CLI Interface** - Comprehensive command-line tools\n✅ **API Integration** - REST API for external integration\n\n---\n\n## Installation\n\n### Prerequisites\n\n- **Nushell 0.107+** - For CLI and scripts\n- **Docker** (optional) - For containerized deployment\n- **dig** (optional) - For DNS queries\n\n### Install CoreDNS Binary\n\n```\n# Install latest version\nprovisioning dns install\n\n# Install specific version\nprovisioning dns install 1.11.1\n\n# Check mode\nprovisioning dns install --check\n```\n\nThe binary will be installed to `~/.provisioning/bin/coredns`.\n\n### Verify Installation\n\n```\n# Check CoreDNS version\n~/.provisioning/bin/coredns -version\n\n# Verify installation\nls -lh ~/.provisioning/bin/coredns\n```\n\n---\n\n## Configuration\n\n### Nickel Configuration Schema\n\nAdd CoreDNS configuration to your infrastructure config:\n\n```\n# In workspace/infra/{name}/config.ncl\nlet coredns_config = {\n  mode = "local",\n\n  local = {\n    enabled = true,\n    deployment_type = "binary",  # or "docker"\n    binary_path = "~/.provisioning/bin/coredns",\n    config_path = "~/.provisioning/coredns/Corefile",\n    zones_path = "~/.provisioning/coredns/zones",\n    port = 5353,\n    auto_start = true,\n    zones = ["provisioning.local", "workspace.local"],\n  },\n\n  dynamic_updates = {\n    enabled = true,\n    api_endpoint = "http://localhost:9090/dns",\n    auto_register_servers = true,\n    auto_unregister_servers = true,\n    ttl = 300,\n  },\n\n  upstream = ["8.8.8.8", "1.1.1.1"],\n  default_ttl = 3600,\n  enable_logging = true,\n  enable_metrics = true,\n  metrics_port = 9153,\n} in\ncoredns_config\n```\n\n### Configuration Modes\n\n#### Local Mode (Binary)\n\nRun CoreDNS as a local binary process:\n\n```\nlet coredns_config = {\n  mode = "local",\n  local = {\n    deployment_type = "binary",\n    auto_start = true,\n  },\n} in\ncoredns_config\n```\n\n#### Local Mode (Docker)\n\nRun CoreDNS in Docker container:\n\n```\nlet coredns_config = {\n  mode = "local",\n  local = {\n    deployment_type = "docker",\n    docker = {\n      image = "coredns/coredns:1.11.1",\n      container_name = "provisioning-coredns",\n      restart_policy = "unless-stopped",\n    },\n  },\n} in\ncoredns_config\n```\n\n#### Remote Mode\n\nConnect to external CoreDNS service:\n\n```\nlet coredns_config = {\n  mode = "remote",\n  remote = {\n    enabled = true,\n    endpoints = ["https://dns1.example.com", "https://dns2.example.com"],\n    zones = ["production.local"],\n    verify_tls = true,\n  },\n} in\ncoredns_config\n```\n\n#### Disabled Mode\n\nDisable CoreDNS integration:\n\n```\nlet coredns_config = {\n  mode = "disabled",\n} in\ncoredns_config\n```\n\n---\n\n## CLI Commands\n\n### Service Management\n\n```\n# Check status\nprovisioning dns status\n\n# Start service\nprovisioning dns start\n\n# Start in foreground (for debugging)\nprovisioning dns start --foreground\n\n# Stop service\nprovisioning dns stop\n\n# Restart service\nprovisioning dns restart\n\n# Reload configuration (graceful)\nprovisioning dns reload\n\n# View logs\nprovisioning dns logs\n\n# Follow logs\nprovisioning dns logs --follow\n\n# Show last 100 lines\nprovisioning dns logs --lines 100\n```\n\n### Health & Monitoring\n\n```\n# Check health\nprovisioning dns health\n\n# View configuration\nprovisioning dns config show\n\n# Validate configuration\nprovisioning dns config validate\n\n# Generate new Corefile\nprovisioning dns config generate\n```\n\n---\n\n## Zone Management\n\n### List Zones\n\n```\n# List all zones\nprovisioning dns zone list\n```\n\n**Output:**\n\n```\nDNS Zones\n=========\n  • provisioning.local ✓\n  • workspace.local ✓\n```\n\n### Create Zone\n\n```\n# Create new zone\nprovisioning dns zone create myapp.local\n\n# Check mode\nprovisioning dns zone create myapp.local --check\n```\n\n### Show Zone Details\n\n```\n# Show all records in zone\nprovisioning dns zone show provisioning.local\n\n# JSON format\nprovisioning dns zone show provisioning.local --format json\n\n# YAML format\nprovisioning dns zone show provisioning.local --format yaml\n```\n\n### Delete Zone\n\n```\n# Delete zone (with confirmation)\nprovisioning dns zone delete myapp.local\n\n# Force deletion (skip confirmation)\nprovisioning dns zone delete myapp.local --force\n\n# Check mode\nprovisioning dns zone delete myapp.local --check\n```\n\n---\n\n## Record Management\n\n### Add Records\n\n#### A Record (IPv4)\n\n```\nprovisioning dns record add server-01 A 10.0.1.10\n\n# With custom TTL\nprovisioning dns record add server-01 A 10.0.1.10 --ttl 600\n\n# With comment\nprovisioning dns record add server-01 A 10.0.1.10 --comment "Web server"\n\n# Different zone\nprovisioning dns record add server-01 A 10.0.1.10 --zone myapp.local\n```\n\n#### AAAA Record (IPv6)\n\n```\nprovisioning dns record add server-01 AAAA 2001:db8::1\n```\n\n#### CNAME Record\n\n```\nprovisioning dns record add web CNAME server-01.provisioning.local\n```\n\n#### MX Record\n\n```\nprovisioning dns record add @ MX mail.example.com --priority 10\n```\n\n#### TXT Record\n\n```\nprovisioning dns record add @ TXT "v=spf1 mx -all"\n```\n\n### Remove Records\n\n```\n# Remove record\nprovisioning dns record remove server-01\n\n# Different zone\nprovisioning dns record remove server-01 --zone myapp.local\n\n# Check mode\nprovisioning dns record remove server-01 --check\n```\n\n### Update Records\n\n```\n# Update record value\nprovisioning dns record update server-01 A 10.0.1.20\n\n# With new TTL\nprovisioning dns record update server-01 A 10.0.1.20 --ttl 1800\n```\n\n### List Records\n\n```\n# List all records in zone\nprovisioning dns record list\n\n# Different zone\nprovisioning dns record list --zone myapp.local\n\n# JSON format\nprovisioning dns record list --format json\n\n# YAML format\nprovisioning dns record list --format yaml\n```\n\n**Example Output:**\n\n```\nDNS Records - Zone: provisioning.local\n\n╭───┬──────────────┬──────┬─────────────┬─────╮\n│ # │     name     │ type │    value    │ ttl │\n├───┼──────────────┼──────┼─────────────┼─────┤\n│ 0 │ server-01    │ A    │ 10.0.1.10   │ 300 │\n│ 1 │ server-02    │ A    │ 10.0.1.11   │ 300 │\n│ 2 │ db-01        │ A    │ 10.0.2.10   │ 300 │\n│ 3 │ web          │ CNAME│ server-01   │ 300 │\n╰───┴──────────────┴──────┴─────────────┴─────╯\n```\n\n---\n\n## Docker Deployment\n\n### Prerequisites\n\nEnsure Docker and docker-compose are installed:\n\n```\ndocker --version\ndocker-compose --version\n```\n\n### Start CoreDNS in Docker\n\n```\n# Start CoreDNS container\nprovisioning dns docker start\n\n# Check mode\nprovisioning dns docker start --check\n```\n\n### Manage Docker Container\n\n```\n# Check status\nprovisioning dns docker status\n\n# View logs\nprovisioning dns docker logs\n\n# Follow logs\nprovisioning dns docker logs --follow\n\n# Restart container\nprovisioning dns docker restart\n\n# Stop container\nprovisioning dns docker stop\n\n# Check health\nprovisioning dns docker health\n```\n\n### Update Docker Image\n\n```\n# Pull latest image\nprovisioning dns docker pull\n\n# Pull specific version\nprovisioning dns docker pull --version 1.11.1\n\n# Update and restart\nprovisioning dns docker update\n```\n\n### Remove Container\n\n```\n# Remove container (with confirmation)\nprovisioning dns docker remove\n\n# Remove with volumes\nprovisioning dns docker remove --volumes\n\n# Force remove (skip confirmation)\nprovisioning dns docker remove --force\n\n# Check mode\nprovisioning dns docker remove --check\n```\n\n### View Configuration\n\n```\n# Show docker-compose config\nprovisioning dns docker config\n```\n\n---\n\n## Integration\n\n### Automatic Server Registration\n\nWhen dynamic DNS is enabled, servers are automatically registered:\n\n```\n# Create server (automatically registers in DNS)\nprovisioning server create web-01 --infra myapp\n\n# Server gets DNS record: web-01.provisioning.local -> <server-ip>\n```\n\n### Manual Registration\n\n```\nuse lib_provisioning/coredns/integration.nu *\n\n# Register server\nregister-server-in-dns "web-01" "10.0.1.10"\n\n# Unregister server\nunregister-server-from-dns "web-01"\n\n# Bulk register\nbulk-register-servers [\n    {hostname: "web-01", ip: "10.0.1.10"}\n    {hostname: "web-02", ip: "10.0.1.11"}\n    {hostname: "db-01", ip: "10.0.2.10"}\n]\n```\n\n### Sync Infrastructure with DNS\n\n```\n# Sync all servers in infrastructure with DNS\nprovisioning dns sync myapp\n\n# Check mode\nprovisioning dns sync myapp --check\n```\n\n### Service Registration\n\n```\nuse lib_provisioning/coredns/integration.nu *\n\n# Register service\nregister-service-in-dns "api" "10.0.1.10"\n\n# Unregister service\nunregister-service-from-dns "api"\n```\n\n---\n\n## Query DNS\n\n### Using CLI\n\n```\n# Query A record\nprovisioning dns query server-01\n\n# Query specific type\nprovisioning dns query server-01 --type AAAA\n\n# Query different server\nprovisioning dns query server-01 --server 8.8.8.8 --port 53\n\n# Query from local CoreDNS\nprovisioning dns query server-01 --server 127.0.0.1 --port 5353\n```\n\n### Using dig\n\n```\n# Query from local CoreDNS\ndig @127.0.0.1 -p 5353 server-01.provisioning.local\n\n# Query CNAME\ndig @127.0.0.1 -p 5353 web.provisioning.local CNAME\n\n# Query MX\ndig @127.0.0.1 -p 5353 example.com MX\n```\n\n---\n\n## Troubleshooting\n\n### CoreDNS Not Starting\n\n**Symptoms:** `dns start` fails or service doesn't respond\n\n**Solutions:**\n\n1. **Check if port is in use:**\n\n   ```bash\n   lsof -i :5353\n   netstat -an | grep 5353\n   ```\n\n1. **Validate Corefile:**\n\n   ```bash\n   provisioning dns config validate\n   ```\n\n2. **Check logs:**\n\n   ```bash\n   provisioning dns logs\n   tail -f ~/.provisioning/coredns/coredns.log\n   ```\n\n3. **Verify binary exists:**\n\n   ```bash\n   ls -lh ~/.provisioning/bin/coredns\n   provisioning dns install\n   ```\n\n### DNS Queries Not Working\n\n**Symptoms:** `dig` returns SERVFAIL or timeout\n\n**Solutions:**\n\n1. **Check CoreDNS is running:**\n\n   ```bash\n   provisioning dns status\n   provisioning dns health\n   ```\n\n2. **Verify zone file exists:**\n\n   ```bash\n   ls -lh ~/.provisioning/coredns/zones/\n   cat ~/.provisioning/coredns/zones/provisioning.local.zone\n   ```\n\n3. **Test with dig:**\n\n   ```bash\n   dig @127.0.0.1 -p 5353 provisioning.local SOA\n   ```\n\n4. **Check firewall:**\n\n   ```bash\n   # macOS\n   sudo pfctl -sr | grep 5353\n\n   # Linux\n   sudo iptables -L -n | grep 5353\n   ```\n\n### Zone File Validation Errors\n\n**Symptoms:** `dns config validate` shows errors\n\n**Solutions:**\n\n1. **Backup zone file:**\n\n   ```bash\n   cp ~/.provisioning/coredns/zones/provisioning.local.zone \\n      ~/.provisioning/coredns/zones/provisioning.local.zone.backup\n   ```\n\n2. **Regenerate zone:**\n\n   ```bash\n   provisioning dns zone create provisioning.local --force\n   ```\n\n3. **Check syntax manually:**\n\n   ```bash\n   cat ~/.provisioning/coredns/zones/provisioning.local.zone\n   ```\n\n4. **Increment serial:**\n   - Edit zone file manually\n   - Increase serial number in SOA record\n\n### Docker Container Issues\n\n**Symptoms:** Docker container won't start or crashes\n\n**Solutions:**\n\n1. **Check Docker logs:**\n\n   ```bash\n   provisioning dns docker logs\n   docker logs provisioning-coredns\n   ```\n\n2. **Verify volumes exist:**\n\n   ```bash\n   ls -lh ~/.provisioning/coredns/\n   ```\n\n3. **Check container status:**\n\n   ```bash\n   provisioning dns docker status\n   docker ps -a | grep coredns\n   ```\n\n4. **Recreate container:**\n\n   ```bash\n   provisioning dns docker stop\n   provisioning dns docker remove --volumes\n   provisioning dns docker start\n   ```\n\n### Dynamic Updates Not Working\n\n**Symptoms:** Servers not auto-registered in DNS\n\n**Solutions:**\n\n1. **Check if enabled:**\n\n   ```bash\n   provisioning dns config show | grep -A 5 dynamic_updates\n   ```\n\n2. **Verify orchestrator running:**\n\n   ```bash\n   curl http://localhost:9090/health\n   ```\n\n3. **Check logs for errors:**\n\n   ```bash\n   provisioning dns logs | grep -i error\n   ```\n\n4. **Test manual registration:**\n\n   ```nushell\n   use lib_provisioning/coredns/integration.nu *\n   register-server-in-dns "test-server" "10.0.0.1"\n   ```\n\n---\n\n## Advanced Topics\n\n### Custom Corefile Plugins\n\nAdd custom plugins to Corefile:\n\n```\nuse lib_provisioning/coredns/corefile.nu *\n\n# Add plugin to zone\nadd-corefile-plugin \\n    "~/.provisioning/coredns/Corefile" \\n    "provisioning.local" \\n    "cache 30"\n```\n\n### Backup and Restore\n\n```\n# Backup configuration\ntar czf coredns-backup.tar.gz ~/.provisioning/coredns/\n\n# Restore configuration\ntar xzf coredns-backup.tar.gz -C ~/\n```\n\n### Zone File Backup\n\n```\nuse lib_provisioning/coredns/zones.nu *\n\n# Backup zone\nbackup-zone-file "provisioning.local"\n\n# Creates: ~/.provisioning/coredns/zones/provisioning.local.zone.YYYYMMDD-HHMMSS.bak\n```\n\n### Metrics and Monitoring\n\nCoreDNS exposes Prometheus metrics on port 9153:\n\n```\n# View metrics\ncurl http://localhost:9153/metrics\n\n# Common metrics:\n# - coredns_dns_request_duration_seconds\n# - coredns_dns_requests_total\n# - coredns_dns_responses_total\n```\n\n### Multi-Zone Setup\n\n```\ncoredns_config: CoreDNSConfig = {\n    local = {\n        zones = [\n            "provisioning.local",\n            "workspace.local",\n            "dev.local",\n            "staging.local",\n            "prod.local"\n        ]\n    }\n}\n```\n\n### Split-Horizon DNS\n\nConfigure different zones for internal/external:\n\n```\ncoredns_config: CoreDNSConfig = {\n    local = {\n        zones = ["internal.local"]\n        port = 5353\n    }\n    remote = {\n        zones = ["external.com"]\n        endpoints = ["https://dns.external.com"]\n    }\n}\n```\n\n---\n\n## Configuration Reference\n\n### CoreDNSConfig Fields\n\n| Field | Type | Default | Description |\n| ------- | ------ | --------- | ------------- |\n| `mode` | `"local" \| "remote" \| "hybrid" \| "disabled"` | `"local"` | Deployment mode |\n| `local` | `LocalCoreDNS?` | - | Local config (required for local mode) |\n| `remote` | `RemoteCoreDNS?` | - | Remote config (required for remote mode) |\n| `dynamic_updates` | `DynamicDNS` | - | Dynamic DNS configuration |\n| `upstream` | `[str]` | `["8.8.8.8", "1.1.1.1"]` | Upstream DNS servers |\n| `default_ttl` | `int` | `300` | Default TTL (seconds) |\n| `enable_logging` | `bool` | `True` | Enable query logging |\n| `enable_metrics` | `bool` | `True` | Enable Prometheus metrics |\n| `metrics_port` | `int` | `9153` | Metrics port |\n\n### LocalCoreDNS Fields\n\n| Field | Type | Default | Description |\n| ------- | ------ | --------- | ------------- |\n| `enabled` | `bool` | `True` | Enable local CoreDNS |\n| `deployment_type` | `"binary" \| "docker"` | `"binary"` | How to deploy |\n| `binary_path` | `str` | `"~/.provisioning/bin/coredns"` | Path to binary |\n| `config_path` | `str` | `"~/.provisioning/coredns/Corefile"` | Corefile path |\n| `zones_path` | `str` | `"~/.provisioning/coredns/zones"` | Zones directory |\n| `port` | `int` | `5353` | DNS listening port |\n| `auto_start` | `bool` | `True` | Auto-start on boot |\n| `zones` | `[str]` | `["provisioning.local"]` | Managed zones |\n\n### DynamicDNS Fields\n\n| Field | Type | Default | Description |\n| ------- | ------ | --------- | ------------- |\n| `enabled` | `bool` | `True` | Enable dynamic updates |\n| `api_endpoint` | `str` | `"http://localhost:9090/dns"` | Orchestrator API |\n| `auto_register_servers` | `bool` | `True` | Auto-register on create |\n| `auto_unregister_servers` | `bool` | `True` | Auto-unregister on delete |\n| `ttl` | `int` | `300` | TTL for dynamic records |\n| `update_strategy` | `"immediate" \| "batched" \| "scheduled"` | `"immediate"` | Update strategy |\n\n---\n\n## Examples\n\n### Complete Setup Example\n\n```\n# 1. Install CoreDNS\nprovisioning dns install\n\n# 2. Generate configuration\nprovisioning dns config generate\n\n# 3. Start service\nprovisioning dns start\n\n# 4. Create custom zone\nprovisioning dns zone create myapp.local\n\n# 5. Add DNS records\nprovisioning dns record add web-01 A 10.0.1.10\nprovisioning dns record add web-02 A 10.0.1.11\nprovisioning dns record add api CNAME web-01.myapp.local --zone myapp.local\n\n# 6. Query records\nprovisioning dns query web-01 --server 127.0.0.1 --port 5353\n\n# 7. Check status\nprovisioning dns status\nprovisioning dns health\n```\n\n### Docker Deployment Example\n\n```\n# 1. Start CoreDNS in Docker\nprovisioning dns docker start\n\n# 2. Check status\nprovisioning dns docker status\n\n# 3. View logs\nprovisioning dns docker logs --follow\n\n# 4. Add records (container must be running)\nprovisioning dns record add server-01 A 10.0.1.10\n\n# 5. Query\ndig @127.0.0.1 -p 5353 server-01.provisioning.local\n\n# 6. Stop\nprovisioning dns docker stop\n```\n\n---\n\n## Best Practices\n\n1. **Use TTL wisely** - Lower TTL (300s) for frequently changing records, higher (3600s) for stable\n2. **Enable logging** - Essential for troubleshooting\n3. **Regular backups** - Backup zone files before major changes\n4. **Validate before reload** - Always run `dns config validate` before reloading\n5. **Monitor metrics** - Track DNS query rates and error rates\n6. **Use comments** - Add comments to records for documentation\n7. **Separate zones** - Use different zones for different environments (dev, staging, prod)\n\n---\n\n## See Also\n\n- [Architecture Documentation](../architecture/coredns-architecture.md)\n- [API Reference](../api/dns-api.md)\n- [Orchestrator Integration](../integration/orchestrator-dns.md)\n- Nickel Schema Reference\n\n---\n\n## Quick Reference\n\n**Quick command reference for CoreDNS DNS management**\n\n---\n\n### Installation\n\n```\n# Install CoreDNS binary\nprovisioning dns install\n\n# Install specific version\nprovisioning dns install 1.11.1\n```\n\n---\n\n### Service Management\n\n```\n# Status\nprovisioning dns status\n\n# Start\nprovisioning dns start\n\n# Stop\nprovisioning dns stop\n\n# Restart\nprovisioning dns restart\n\n# Reload (graceful)\nprovisioning dns reload\n\n# Logs\nprovisioning dns logs\nprovisioning dns logs --follow\nprovisioning dns logs --lines 100\n\n# Health\nprovisioning dns health\n```\n\n---\n\n### Zone Management\n\n```\n# List zones\nprovisioning dns zone list\n\n# Create zone\nprovisioning dns zone create myapp.local\n\n# Show zone records\nprovisioning dns zone show provisioning.local\nprovisioning dns zone show provisioning.local --format json\n\n# Delete zone\nprovisioning dns zone delete myapp.local\nprovisioning dns zone delete myapp.local --force\n```\n\n---\n\n### Record Management\n\n```\n# Add A record\nprovisioning dns record add server-01 A 10.0.1.10\n\n# Add with custom TTL\nprovisioning dns record add server-01 A 10.0.1.10 --ttl 600\n\n# Add with comment\nprovisioning dns record add server-01 A 10.0.1.10 --comment "Web server"\n\n# Add to specific zone\nprovisioning dns record add server-01 A 10.0.1.10 --zone myapp.local\n\n# Add CNAME\nprovisioning dns record add web CNAME server-01.provisioning.local\n\n# Add MX\nprovisioning dns record add @ MX mail.example.com --priority 10\n\n# Add TXT\nprovisioning dns record add @ TXT "v=spf1 mx -all"\n\n# Remove record\nprovisioning dns record remove server-01\nprovisioning dns record remove server-01 --zone myapp.local\n\n# Update record\nprovisioning dns record update server-01 A 10.0.1.20\n\n# List records\nprovisioning dns record list\nprovisioning dns record list --zone myapp.local\nprovisioning dns record list --format json\n```\n\n---\n\n### DNS Queries\n\n```\n# Query A record\nprovisioning dns query server-01\n\n# Query CNAME\nprovisioning dns query web --type CNAME\n\n# Query from local CoreDNS\nprovisioning dns query server-01 --server 127.0.0.1 --port 5353\n\n# Using dig\ndig @127.0.0.1 -p 5353 server-01.provisioning.local\ndig @127.0.0.1 -p 5353 provisioning.local SOA\n```\n\n---\n\n### Configuration\n\n```\n# Show configuration\nprovisioning dns config show\n\n# Validate configuration\nprovisioning dns config validate\n\n# Generate Corefile\nprovisioning dns config generate\n```\n\n---\n\n### Docker Deployment\n\n```\n# Start Docker container\nprovisioning dns docker start\n\n# Status\nprovisioning dns docker status\n\n# Logs\nprovisioning dns docker logs\nprovisioning dns docker logs --follow\n\n# Restart\nprovisioning dns docker restart\n\n# Stop\nprovisioning dns docker stop\n\n# Health\nprovisioning dns docker health\n\n# Remove\nprovisioning dns docker remove\nprovisioning dns docker remove --volumes\nprovisioning dns docker remove --force\n\n# Pull image\nprovisioning dns docker pull\nprovisioning dns docker pull --version 1.11.1\n\n# Update\nprovisioning dns docker update\n\n# Show config\nprovisioning dns docker config\n```\n\n---\n\n### Common Workflows\n\n#### Initial Setup\n\n```\n# 1. Install\nprovisioning dns install\n\n# 2. Start\nprovisioning dns start\n\n# 3. Verify\nprovisioning dns status\nprovisioning dns health\n```\n\n#### Add Server\n\n```\n# Add DNS record for new server\nprovisioning dns record add web-01 A 10.0.1.10\n\n# Verify\nprovisioning dns query web-01\n```\n\n#### Create Custom Zone\n\n```\n# 1. Create zone\nprovisioning dns zone create myapp.local\n\n# 2. Add records\nprovisioning dns record add web-01 A 10.0.1.10 --zone myapp.local\nprovisioning dns record add api CNAME web-01.myapp.local --zone myapp.local\n\n# 3. List records\nprovisioning dns record list --zone myapp.local\n\n# 4. Query\ndig @127.0.0.1 -p 5353 web-01.myapp.local\n```\n\n#### Docker Setup\n\n```\n# 1. Start container\nprovisioning dns docker start\n\n# 2. Check status\nprovisioning dns docker status\n\n# 3. Add records\nprovisioning dns record add server-01 A 10.0.1.10\n\n# 4. Query\ndig @127.0.0.1 -p 5353 server-01.provisioning.local\n```\n\n---\n\n### Troubleshooting\n\n```\n# Check if CoreDNS is running\nprovisioning dns status\nps aux | grep coredns\n\n# Check port usage\nlsof -i :5353\nnetstat -an | grep 5353\n\n# View logs\nprovisioning dns logs\ntail -f ~/.provisioning/coredns/coredns.log\n\n# Validate configuration\nprovisioning dns config validate\n\n# Test DNS query\ndig @127.0.0.1 -p 5353 provisioning.local SOA\n\n# Restart service\nprovisioning dns restart\n\n# For Docker\nprovisioning dns docker logs\nprovisioning dns docker health\ndocker ps -a | grep coredns\n```\n\n---\n\n### File Locations\n\n```\n# Binary\n~/.provisioning/bin/coredns\n\n# Corefile\n~/.provisioning/coredns/Corefile\n\n# Zone files\n~/.provisioning/coredns/zones/\n\n# Logs\n~/.provisioning/coredns/coredns.log\n\n# PID file\n~/.provisioning/coredns/coredns.pid\n\n# Docker compose\nprovisioning/config/coredns/docker-compose.yml\n```\n\n---\n\n### Configuration Example\n\n```\nimport provisioning.coredns as dns\n\ncoredns_config: dns.CoreDNSConfig = {\n    mode = "local"\n    local = {\n        enabled = True\n        deployment_type = "binary"  # or "docker"\n        port = 5353\n        zones = ["provisioning.local", "myapp.local"]\n    }\n    dynamic_updates = {\n        enabled = True\n        auto_register_servers = True\n    }\n    upstream = ["8.8.8.8", "1.1.1.1"]\n}\n```\n\n---\n\n### Environment Variables\n\n```\n# None required - configuration via Nickel\n```\n\n---\n\n### Default Values\n\n| Setting | Default |\n| --------- | --------- |\n| Port | 5353 |\n| Zones | ["provisioning.local"] |\n| Upstream | ["8.8.8.8", "1.1.1.1"] |\n| TTL | 300 |\n| Deployment | binary |\n| Auto-start | true |\n| Logging | enabled |\n| Metrics | enabled |\n| Metrics Port | 9153 |\n\n---\n\n## See Also\n\n- [Complete Guide](COREDNS_GUIDE.md) - Full documentation\n- Implementation Summary - Technical details\n- Nickel Schema - Configuration schema\n\n---\n\n**Last Updated**: 2025-10-06\n**Version**: 1.0.0
