DNS

Manage authoritative DNS the Kubernetes way. Declare a domain and its records as ordinary Kubernetes resources, and the DNS service programs them into an authoritative DNS backend and publishes them to a globally distributed serving layer — no zone files, no backend API calls, no manual nameserver wiring.

You manage DNS through native Kubernetes resources, so it works with kubectl and any Kubernetes client, and inherits your platform's identity, RBAC, and audit controls.

This repository provides the DNS operator, the control-plane component that reconciles those resources and programs the backend. See the Architecture Overview for how the operator fits into the wider service.

What it does

• Zones and records as resources — Model domains with DNSZone and records with DNSRecordSet, covering A, AAAA, CNAME, ALIAS, TXT, MX, SRV, CAA, NS, SOA, PTR, TLSA, HTTPS, and SVCB types.
• Pluggable backends — A cluster-scoped DNSZoneClass selects the backend and nameserver policy, keeping backend choice out of individual zones. PowerDNS is supported today.
• Multi-tenant by design — Each tenant authors DNS in their own control plane; the operator discovers and serves many control planes from one shared authoritative backend, with per-domain ownership accounting.
• Automatic zone bootstrap — Default SOA and NS records are created for every zone from its nameserver policy, without clobbering user-authored apex records.
• Clear status — Accepted and Programmed conditions report whether a zone or record is valid and actually serving, mirrored back from the authoritative backend.

How it works

Users declare DNSZone and DNSRecordSet resources in their own control plane. A replicator mirrors that desired state into a shared authoritative cluster, where a downstream agent programs it into the DNS backend. The authoritative data is then replicated to a read-only serving layer that answers live queries.

For the full picture — components, control planes, and the serving layer — see the Architecture Overview.

Documentation

Architecture

• Architecture Overview — System design and core concepts
• Deployment Topology — Roles, control planes, and the serving layer
• Replication Model — How desired state and status move between clusters
• API Reference — Full resource schema and conditions

Guides

• Service Catalog — DNS as a billable platform service

Deploying

The operator runs in one of two roles, deployed with the Kustomize overlays in config/. See Deployment Topology for how the roles fit together.

Agent with embedded PowerDNS

Runs the operator as a downstream agent alongside PowerDNS and a storage backend — the quickest way to a working DNS service:

kubectl apply -k config/overlays/agent-powerdns

Then create a DNSZoneClass, DNSZone, and DNSRecordSet (see config/samples and the API Reference).

Replicator (upstream → downstream)

Runs the operator as a replicator that mirrors DNS resources from tenant control planes into a downstream authoritative cluster:

# Provide the downstream cluster kubeconfig
kubectl -n dns-replicator-system create secret generic downstream-kubeconfig \
  --from-file=kubeconfig=/path/to/downstream/kubeconfig

kubectl apply -k config/overlays/replicator

The replicator mirrors upstream DNSZone / DNSRecordSet resources downstream and synthesizes their status back upstream. See Replication Model.

Local federation environment

Brings up kind clusters on the shared datum-cloud/test-infra tooling to exercise the full production topology end to end: a replicator on an "upstream" cluster, dns-operator + PowerDNS on a "control" cluster, and PowerDNS alone on an "edge" cluster. Zone data replicates from control to edge with PowerDNS LightningStream over a shared RustFS (S3-compatible) bucket — the same mechanism production uses to replicate to edge PoPs over GCS.

export TASK_X_REMOTE_TASKFILES=1
task env:up          # upstream (replicator) + control (operator + PowerDNS + RustFS) + edge (PowerDNS)
task env:dns-check   # confirm the sample record replicated from control to edge
task env:down        # tear down every cluster

See Taskfile.yaml for the individual env:upstream-up, env:control-up, and env:edge-up steps, and config/overlays/agent-powerdns-federated and config/dependencies/rustfs for the underlying manifests.

Development

• Build: make docker-build (see the Makefile)
• Generate code / manifests: make generate and make manifests
• End-to-end tests: see test/e2e/ and the samples under config/samples/