aoliveti/kdns repository overview

⁠KDNS

KDNS is a lightweight, zero-dependency authoritative DNS server written from scratch in Go.

It is designed for low latency, low memory footprint, and simple operations. It holds records in an in-memory radix tree for fast resolution and persists mutations to disk using a Write-Ahead Log (WAL) with compressed snapshots.

Source code and documentation: github.com/aoliveti/kdns⁠

⁠Features

• Fast & Lightweight: In-memory reverse-label radix tree routing with zero heap allocations on resolution.
• Modern Transports: Supports standard UDP/TCP (port 5353), DNS-over-TLS (DoT, port 853), and DNS-over-HTTPS (DoH, port 8443).
• Durability & Replication: Append-only Write-Ahead Log (WAL) with periodic compressed snapshots and live Primary/Replica streaming.
• DNSSEC & Dynamic Updates: Dynamic on-the-fly RRSIG signing, NSEC denial proofs, and RFC 2136 UPDATE support authenticated with TSIG.
• Minimal Footprint: Multi-arch Distroless base image (amd64 and arm64), running as non-root with an image size of only ~4 MB.

⁠Quick Start

Run a standalone KDNS instance:

docker run -d \
  --name kdns \
  -p 5353:5353/udp \
  -p 5353:5353/tcp \
  -p 8080:8080/tcp \
  -e KDNS_API_TOKEN="your-secret-token-here" \
  -v kdns_data:/data \
  aoliveti/kdns:latest

Test that the server is running:

curl -i http://localhost:8080/livez

Add your first record via REST API:

curl -X PUT http://localhost:8080/v1/records/app.example.com \
  -H "Authorization: Bearer your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"type":"A","ttl":300,"rdata":["192.0.2.1"]}]}'

Query the server:

dig @127.0.0.1 -p 5353 app.example.com A +short

⁠Docker Compose

services:
  kdns:
    image: aoliveti/kdns:latest
    container_name: kdns
    environment:
      - KDNS_MODE=standalone
      - KDNS_ADDRESS=:5353
      - KDNS_HTTP_ADDR=:8080
      - KDNS_API_TOKEN=your-secret-token-here
      - KDNS_STORAGE_DIR=/data
    ports:
      - "5353:5353/udp"
      - "5353:5353/tcp"
      - "8080:8080"
    volumes:
      - kdns_data:/data
    restart: unless-stopped

volumes:
  kdns_data:

⁠Configuration & Environment Variables

⁠Monitoring & Health Checks

KDNS exposes standard Kubernetes probes and Prometheus metrics:

• Liveness probe: GET http://localhost:8080/livez
• Readiness probe: GET http://localhost:8080/readyz
• Startup probe: GET http://localhost:8080/startupz
• Prometheus metrics: GET http://localhost:8080/metrics

⁠Contributing & Issues

For bugs, feature requests, and documentation:

• GitHub Repository: github.com/aoliveti/kdns⁠
• Issues: github.com/aoliveti/kdns/issues⁠
• License: BSD 3-Clause License⁠