kudurru architecture

Thesis. kudurru is one Apache-2.0 Go binary that is a complete DNS server (authoritative with real serials, transfers and, later, DNSSEC; forwarding resolver with a node-local cache; blocky/AdGuard-grade blocking with client groups; Pi-hole-grade dashboard) and that is a first-class Kubernetes citizen and a docker run appliance without being two products. The object model is the product; persistence sits behind one Store interface with two drivers at v0.1 (Kubernetes CRDs via the apiserver; embedded SQLite) and zero consensus code, with follower (v0.2) and raft (v1.0) drivers arriving behind the same interface. dnsdist (edge/load balancing) and keepalived (VIP) are GPL siblings driven by a kudurru supervisor process inside their own images, never linked. Every deferral names the seam that keeps it additive.

The boundary-stone metaphor is the data model: a DNSZone is a recorded grant of authority (the stone kept in the temple = the store that is authoritative for configuration); clay copies are distributed by standard DNS (AXFR/IXFR, NOTIFY, TSIG, catalog zones) and by replication of the store itself.

1. Vision & principles

kudurru should feel to a platform engineer the way cert-manager or external-dns feel (install a chart, apply a few CRs, watch kubectl get zones turn Ready) and to a home-lab user the way Pi-hole feels (one container, one dashboard that explains every answer), with Technitium's zone depth and blocky/AdGuard's blocking underneath. Principles — each one is a rule used in a later section:

1. Correct before complete. v0.1 ships fewer zone types and no DNSSEC signing rather than wrong serials, wrong CNAME handling, or NXDOMAIN from an unsynced source [gravity §18.1, k8s §2.2].
2. One object model, one Store interface, zero consensus code in v0.1. In Kubernetes the apiserver is the replicated store (CRDs are the truth, Deployment, no PVC for config) [k8s §13 model 1, §16.2]; in Docker it is embedded SQLite. follower (v0.2) and raft (v1.0) drivers arrive behind the same interface [go-dns-stack §6.3].
3. Exactly one writer per object. metadata.managedBy (api | file:<path> | integration:<name> | bootstrap | system; in Kubernetes the apiserver's field manager) makes "two sources of truth" structurally impossible [k8s §16.1, gravity §18.2].
4. Serve from memory; degrade, never stop. The query path reads lock-free snapshots, never the store; replicas keep answering from the last good snapshot (persisted to local disk) when the store is unreachable; before the first sync they answer SERVFAIL, never NXDOMAIN [k8s §8, gravity §4.4].
5. Replicate configuration; never caches, logs or heartbeats. Query logs are per-node SQLite with scatter-gather views; metrics go to Prometheus; node status is scatter-gathered, not written anywhere [gravity §18.1/§18.8, observability §5].
6. Fixed pipeline, named stages. Stage order is code, not config; integrations attach to named stages and never run on the query path [technitium §3, integrations §1.2].
7. Records are external-dns Endpoints (a superset). DNSEndpoint ingestion, the external-dns webhook, the Cloudflare sink and the CRD spec share one shape [k8s §3.2, integrations §1.6].
8. Leader-only side effects. Status writes, serial stamping, blocklist fetch, NOTIFY, DNSSEC signing, ACME and integrations run on exactly one node (Lease / self / raft leader); serving runs on every node [k8s §8].
9. GPL stays outside the binary. dnsdist and keepalived are separate processes driven by rendered files, the dnsdist HTTP API, the console binary, signals, track_file and the notify FIFO; Technitium, AdGuard Home, Gravity and Pi-hole are idea sources only; blocky, dnsproxy and CoreDNS are the only upstreams whose code is copied or imported [blocking §1.1, dnsdist §4].
10. Secure by default, lessons from the 2026 CVEs of the comparables: no code-bearing or privileged setting reachable through the API (hostOnly keys), hashed tokens with constant-time compare, Argon2id with server-fixed parameters, sealed HttpOnly cookies, bounded metric labels, probes on an unauthenticated ops port, Restricted PSS out of the box [pihole §17.7, technitium §21.10, auth §10].
11. Multi-node from day one in the UI. Node selector + "all nodes" on every stat, "which node answered" on every log row, even with one node [pihole §17.2].
12. Every deferral has a seam. §13.1 lists, per deferred feature, the interface or schema field that already exists in v0.1.

2. Language, stack, key libraries

Go, because every reusable component (CoreDNS, blocky, dnsproxy, external-dns, controller-runtime) is Go and shares miekg/dns v1 types; Rust's hickory-dns has an experimental recursor and no IXFR [go-dns-stack §1]. Versions are the ones verified in the research on 2026-10-10.

Explicitly not used: embedded etcd (1 GB floor, bespoke join, fsync-sensitive [go-dns-stack §6.2, gravity §16]), dragonboat, marmot, Litestream-as-replication, DuckDB/mattn (cgo), urlfilter/AdGuard Home packages (GPL), go-plugin as the primary extension API, Casbin/OpenFGA as the primary authorizer, viper, logrus/zap, a bespoke dnsdist console client (we exec the dnsdist binary).

3. Component architecture

3.1 One binary, roles, runnables

kudurru runs a set of roles selected by config (roles: [dns, api, controller, querylog, ops], Gravity-style [gravity §17.1]) scheduled by a controller-runtime-shaped manager where each runnable declares whether it is always-on (every replica) or leader-only [k8s §8]. Every role implements Ready() (bool, []string) and feeds /healthz/ready.

store.Elector is backed by a Kubernetes Lease (kube driver), "always leader" (sqlite driver), "never leader" (follower driver, v0.2) and raft leadership (v1.0).

3.2 Diagram

                      clients (Do53 / DoT / DoH / DoQ / DoH3)
                                   │
            ┌──────────────────────▼───────────────────────┐   optional edge tier (GPL, separate container)
            │ dnsdist 2.1  :53/:853/:443  packet cache      │   PID 1 = `kudurru edge run` (render → check → exec)
            │ pools: resolver(chashed) authoritative(leastOutstanding)  DynBlocks (eBPF opt-in) │
            └──────────────────────┬───────────────────────┘
                     PROXYv2 (client IP preserved)  → :5353 (or :53 when no edge)
┌───────────────────────────────────▼─────────────────────────────────────────────────┐
│ kudurru node (every replica)                                                         │
│  dnsserver ─▶ PIPELINE  ingress ▸ identify ▸ control ▸ local ▸ authoritative ▸ blocking │
│                      ▸ rewrite ▸ cache ▸ dnssec-validate ▸ upstream ▸ postprocess ▸ log │
│       ▲ reads lock-free snapshots (atomic.Pointer) of:                                   │
│       │   zone trees │ policy/clientgroup index │ compiled blocklists │ upstream groups   │
│  zonecache ◀── Store.Watch(kind…) ──────────────┐  ──▶ local.db (last-good snapshot)      │
│  api (huma, UI, SSE)  querylog (ring→SQLite→rollups→sinks)  ops/metrics  internal :8082 │
│  controller / listfetcher / notifier / signer / integrations / acme  [leader-only] ─┼─┐ │
└──────────────────────────────────────────────────────────────────────────────────────┼─┼─┘
   STORE (config plane)   kube driver: CRDs via apiserver (replicated by k8s etcd)  ◀──┘ │
                          sqlite driver: /var/lib/kudurru/state.db (docker)        ◀────┘
                          follower (v0.2): sqlite mirror pulled from a primary; raft (v1.0): sqlite FSM
   RUNTIME (per node)     querylog.db, local.db (snapshot, audit, cache dump), lists/, keys/
   VIP (bare metal)       keepalived (VRRPv3) with PID 1 = `kudurru vip run`; in k8s: kube-vip / MetalLB / cloud LB

3.3 Dataplane packages

• internal/dnsserver: listeners on dns.Server (UDP/TCP with ReusePort, N sockets = GOMAXPROCS like CoreDNS multisocket), tcp-tls for DoT, net/http for DoH h1.1/h2, PROXYv2 parser restricted to listeners.proxyProtocolFrom (hard requirement because dnsdist fronts us [dnsdist §1.13]) and to headers carrying TLV 0xE0 equal to the shared listeners.proxyProtocolSecretFile value (32 random bytes; dnsdist adds it with SetAdditionalProxyProtocolValueAction, the supervisor renders it). Source-CIDR trust alone is spoofable by any host in the trusted range (any pod in the pod CIDR, any LAN host on a /24), which would let an attacker forge the client address that queryACL/transferACL/client-group policies and the query log rely on; headers without a matching TLV are dropped and counted in kudurru_dns_dropped_total{reason="proxy_unauthenticated"}. Loopback (127.0.0.1/32, ::1/128) is exempt when the secret is unset but must still be listed. Semantics pinned by the spike (D72, D76): headers are optional and a header-less query is attributed to its transport peer; LOCAL and AF_UNSPEC headers need the same authentication and keep the peer address; the TLV value is the secret file's bytes with trailing CR/LF trimmed, at least 32 bytes; CIDR entries in proxyProtocolFrom are accepted only when proxyProtocolSecretFile is set (pod IPs are dynamic; the TLV authenticates, the CIDR only narrows exposure), exact /32s otherwise. Transport limits: MaxTCPQueries unlimited with a 10 s idle timeout (miekg's default closed TCP/DoT after 128 queries), UDP read buffer 4096 B plus 2 KiB when PROXYv2 is on (the 512 B default silently dropped large EDNS queries), DoH body cap 65,535 B and headers 16 KiB, DoQ grants no unidirectional streams, QUIC connection cap configurable. All four TLS listeners share one certificate reloader per cert/key pair (fsnotify plus a 30 s poll); a half-rotated pair keeps serving the previous certificate. DoQ/DoH3 (v0.1, D67) copy CoreDNS/dnsproxy server code (ALPN doq/h3, 256 streams, 1024 workers, RFC 9250 error codes; never reuse a fixed DNS ID when bridging DoQ→UDP [go-dns-stack §4.1, §17.9]).
• internal/pipeline: the fixed stage chain (§7.1). Stages are packages under internal/stages/: ingress, identify, control, local, authoritative, blocking, rewrite, cache, dnssec, upstream, postprocess, log.

// internal/pipeline/stage.go
type Stage interface {
    Name() string                                   // fixed, documented stage id
    Serve(ctx *Request, next Next) (*Response, error)
}
type Next func(*Request) (*Response, error)
type Request struct {
    Ctx           context.Context
    Msg           *dns.Msg       // miekg only here and in dnsserver/xfr/upstream/dnssec
    Client        Client         // addr, proto, proxied-from, clientID (SNI/DoH path), MACs, GroupIDs (identify),
                                 // TSIGKey (set only after the transport verified the signature)
    Received, Deadline time.Time
    Zone          any            // *zone.Zone, set by authoritative when a zone matched
    UpstreamGroup string         // forward zone or Policy group for the upstream stage; beats the conditional map, never cached
    Policy        any            // *policy.Decision from identify (read with policy.FromRequest; shared, immutable)
    // Trace TraceInfo           (v0.2, with OTel)
}
type Response struct {
    Msg        *dns.Msg
    Status     Status              // taxonomy in §11.2 (forwarded, cached, authoritative, blocked_list, …)
    Upstream   string              // dictionary name, never a raw IP
    List, Rule string              // matched list and rule text (the UI "why" row)
    Cacheable  bool                // local/conditional answers are never cached (blocky rule)
    Transfer   iter.Seq[*dns.Msg]  // AXFR/IXFR stream; TCP/DoT write every message, Msg is the first
}

Optional capability interfaces discovered by type assertion (CoreDNS style): Ready() bool, Transfer(zone string, serial uint32) (<-chan []dns.RR, error), Reload(snapshot any).

• internal/zone: the record model (§4.1), per-zone in-memory tree (CoreDNS plugin/file/tree red-black tree, Apache-2.0), wildcard lookup, CNAME chasing (loop cap 20), SOA/serial management, journal for IXFR, AXFR/IXFR out via dns.Transfer, coalesced NOTIFY out; secondary-in (v0.2) copies the CoreDNS file/secondary.go flow [go-dns-stack §5].
• internal/blocking: compiled matcher chain (§7.3), clean-room adblock parser, snapshot compile.
• internal/cache: sharded TTL message cache with min/max/negative TTL, prefetch (threshold/window), serve-stale (RFC 8767: stale TTL 3 d, stale answer TTL 30 s, max wait 1.8 s — Technitium numbers), in-flight coalescing, OPT stripped, DO-aware keys; persisted to local.db on shutdown [technitium §20.8, blocking §6.5].
• internal/upstream: dnsproxy upstream groups with strategies parallel_best (default), strict, random, rtt_weighted; conditional forwarding by longest suffix; bootstrap list; dnsmasq [/domain/] import syntax.

3.4 Control-plane packages

• api/v1alpha1: Go types for every kind with kubebuilder markers. The same structs are what the sqlite driver persists (JSON) and what the API/CLI/UI exchange. CRD OpenAPI + CEL validation is executed locally in Docker mode with the apiextensions validator so both modes reject the same inputs [k8s §13].
• internal/store: the Store interface (§4.3), drivers kube, sqlite, follower (v0.2), raft (v1.0), the shared validator, the schema version/migration contract, and the conformance suite every driver must pass.
• internal/controller: one reconciler per kind (never a mega-controller), idempotent, level-triggered, writing metav1.Conditions + observedGeneration; finalizers for external cleanup; Events on every operational transition (SerialBumped, NotifyFailed, ListFetchFailed, PublishConflict, Duplicated).
• internal/config: koanf loader, JSON Schema, and the settings metadata table (schema.go: key, type, default, help, restartRequired, envLocked, writeOnly, hostOnly) that drives file, env, kudurru config, PATCH /node/config, the "All settings" page and the docs page; a test asserts docs cannot drift.
• internal/auth, internal/rbac: §8. internal/rbac/permissions.yaml is the single source for roles, aggregated ClusterRoles, docs and the route-permission lint.
• internal/api: huma routes under /api/v1, uniform envelope (took_ms, {error:{key,message,hint}}), 201+Location, 204 on delete, :batchDelete, keyset pagination, SSE; Scalar docs at /api/docs at the running version.
• internal/integration: registry, manifest, lifecycle, leader-scoped runner, plan engine, ledger (§9).
• internal/edge/{dnsdist,keepalived}: renderers + supervisors (§3.6).
• internal/cluster: node identity, membership source abstraction (static | endpointslice | follower | raft), scatter-gather client, internal listener, promote/fencing (v0.2).
• internal/querylog, internal/audit, internal/metrics, internal/health: §11.

3.5 UI and CLI

• UI: SPA at /, talks only to /api/v1; node selector and "all nodes" scope first-class from v0.1 even with one node. Pages in §10.
• CLI kudurru (seven letters): serve, login, get|apply|delete|describe -f, zones, records, lists, blocking enable|disable 5m, query (dig-like), health [--vrrp], lameduck, backup|restore|export, import bind|pihole|adguard|blocky|technitium, edge render|run, vip render|run, cluster status|promote|join-token (v0.2+), integrations list|check|sync|preview|webhook conformance (v0.2), admin reset-password|create-token (unix socket, uid-gated), config get|set|schema, doctor, api <path>, version, completion. All commands use the generated OpenAPI client except serve, admin, doctor and the supervisors. --context picks a kubeconfig (CRD verbs go straight to the apiserver) or a kudurru API endpoint.

3.6 dnsdist and keepalived: supervisors, not sidecars, not shell loops

Both tools are GPL-2.0 and must remain separate programs [dnsdist §4]. The dnsdist REST API cannot manage backends, YAML has no reload, and membership changes go through the console (whose behaviour when dnsdist was started from YAML is UNVERIFIED) [dnsdist §1.11, §1.12, §1.16, §7]. The lowest-risk orchestration is a kudurru supervisor process that is PID 1 in the same image as the tool (mere aggregation: two separate executables, GPL text and source offer shipped in the image README).

ghcr.io/robertherbaugh/kudurru-dnsdist:<dnsdist>-k<kudurru> = FROM powerdns/dnsdist-21@sha256:<digest> + /usr/local/bin/kudurru. Entrypoint kudurru edge run:

1. Build a Topology{Binds, TLS, Pools, Backends[], Cache, Console, Webserver, Rules, DynBlocks} from flags/config and the membership source: --backends 10.0.0.11:5353,… (static, compose), --backends-from endpointslice:<ns>/<headless-svc> (Kubernetes), --backends-from cluster (follower/raft, v0.2+). Backend id = uuid5(kudurru-node-name) so the chashed ring is stable; use_proxy_protocol: true; health check health.kudurru.internal. TXT with must_resolve: true and a 2.1 validation_function checking the node id (interval 1, max_failures 2, rise 2).
2. Render dnsdist.yml (every backends[], binds[], pools[] resolver (chashed, packet cache) and authoritative (leastOutstanding, uncached by default; edge.authoritativeCache enables a short max_ttl with flush-on-serial-change), query_rules refusing XFR/NOTIFY/UPDATE from unknown sources, dynamic_rules, webserver/console loopback-only with credentials generated per start; the API key is also written to /run/kudurru/dnsdist-api.key (0640, group keepalived_script) on the shared kudurru-run volume so kudurru health --vrrp in the keepalived container and the local kudurru's /edge page can read it) plus dnsdist.lua with functions only (never enableLuaConfiguration()) [dnsdist §6.5].
3. dnsdist --check-config -C candidate.yml; atomic rename; exec dnsdist --supervised --disable-syslog -C /etc/dnsdist/dnsdist.yml as a child; forward SIGTERM; expose :8084/healthz/ready = GET /api/v1/servers/localhost (X-API-Key) reports ≥ 1 backend up — so Kubernetes probes the supervisor, not the API key.
4. On membership change — v0.1 baseline: regenerate YAML and restart the child (readiness 503 → drain → sub-second restart; invisible behind a VIP/LB with ≥ 2 edge replicas; the packet cache is lost on every restart) [dnsdist §1.16 option 3]. Membership events are debounced 5 s and only endpoints with conditions.ready (or serving during a rollout) are rendered, so a kudurru Deployment rollout restarts each edge replica once per surge batch rather than once per pod; a lone edge replica (compose edge profile, single-node k8s) accepts the ~0.5 s blip, which keepalived's fall 3 does not count as a VIP failure. v0.2, gated on the week-1 spike: dnsdist -C dnsdist.yml -e 'newServer({...})' / getServer("<uuid>"):setDown() → 5 s purge delay → rmServer("<uuid>"), then regenerate YAML so a restart converges [dnsdist §1.16 option 1]. If the spike fails, the supervisor renders Lua (dnsdist.conf) instead — both renderers share Topology.
5. Cert change (fsnotify) → v0.1 restart; v0.2 reloadAllCertificates() over the console. Zone serial change (polled from GET http://<backend>:8082/internal/zones every 5 s; SSE in v0.2) → DELETE /api/v1/cache?pool=authoritative&suffix=<zone> when the authoritative pool is cached. UI "block this client at the edge for 10 min" → Lua registerWebHandler('/kudurru/dynblock') → addDynamicBlock (v0.2).

ghcr.io/robertherbaugh/kudurru-keepalived:<keepalived>-k<kudurru> = Alpine multi-stage build compiling keepalived 2.4.3 from the release tarball (upstream Dockerfile.in pattern: --enable-json, VRRP only, no LVS/BFD, user keepalived_script) + /usr/local/bin/kudurru. Alpine's package is 2.3.4 [dnsdist §2.1], which has no auth_hmac; if an operator forces a 2.3.x binary (vip.keepalived.legacy: true) the renderer drops auth_hmac, keeps check_unicast_src + unicast_fault_no_peer, and doctor warns that adverts are unauthenticated. Entrypoint kudurru vip run, full contract:

• Render keepalived.conf: global_defs { router_id <node>; enable_script_security; script_user keepalived_script; vrrp_version 3; vrrp_garp_master_refresh 30; vrrp_notify_fifo /run/kudurru/vrrp.fifo; vrrp_notify_fifo_script "/usr/local/bin/kudurru vip fifo" }; per VIP a vrrp_instance with state BACKUP, nopreempt, deterministic priority 200 - 10*idx (never 255), advert_int 1, unicast_src_ip, unicast_peer {…}, unicast_fault_no_peer, check_unicast_src, auth_hmac { key 1 file:/run/secrets/vrrp_hmac_<vrid>; active_key 1; anti_replay monotonic }, virtual_ipaddress { <addr>/<len> dev <iface> }, track_script { chk_<vip> }, track_file { tf_<vip> }.
• vrrp_script chk_<vip> = kudurru health --vrrp --dns <vip>:53 --qname health.kudurru.internal. --dnsdist-api http://127.0.0.1:8083 --dnsdist-api-key-file /run/kudurru/dnsdist-api.key --require-backends 1 (probes the VIP address on :53 udp and tcp while MASTER and loopback while BACKUP — a loopback-only check would pass with a misbound dnsdist [dnsdist §2.7] — and requires ≥ 1 healthy backend via the dnsdist API; interval 1 timeout 1 fall 3 rise 2 weight 0 → FAULT on failure; runs as keepalived_script under enable_script_security, so the binary path is root-owned and the key file is group-readable).
• track_file tf_<vip> = /run/kudurru/weight-<vip>, weight -1: the local kudurru writes 0 (healthy serving member), 60 (prefer-not: lowers the effective priority so this node loses the next election), 300 (→ FAULT: must not hold the VIP) [dnsdist §2.6]. Because every instance runs nopreempt, a priority reduction alone never moves a VIP away from the current MASTER (a higher-priority BACKUP does not preempt by design); only FAULT does. Decision D51 (project owner, 2026-10-10): kudurru lameduck never touches the VIP. Lameduck makes the local kudurru fail dnsdist's backend health check, so the node drains out of every edge's backend pool while the VIP stays with it for as long as its own dnsdist is healthy with ≥ 1 backend. The VIP moves only on real failure (dnsdist down, no healthy backend, node loss, FAULT from track_script) or when an operator explicitly runs kudurru vip drain / maintenance mode, which writes 300. 60 is reserved for "not the leader / not a voter" hints that only matter when the VIP is next re-elected. The 2-VM e2e asserts three behaviours: lameduck keeps the VIP, vip drain moves it within fall/down-timer time, node loss moves it (spike (h), §14).
• keepalived -t -f candidate.conf before swap; atomic rename, previous file kept; SIGHUP the child on re-render; stop_grace_period: 20s; the VRID is a hostOnly config value and never auto-allocated or changed on re-render.
• FIFO consumer emits kudurru_vip_master{vip}, audit cluster.vip.changed, event vip.master_changed; never blocks.
• Optional second VIP with reversed priorities = active/active across two resolver addresses. With nopreempt, after a failover and recovery both VIPs stay on the surviving node until kudurru vip rebalance (writes 300 for the VIP that should move, then 0) or the operator sets vip.preemptDelay: 60 on the second VIP instead of nopreempt.
• Every node's dnsdist lists all kudurru nodes as backends, so VIP ownership follows dnsdist health, not kudurru health: a node whose kudurru is unhealthy but whose dnsdist is fine still serves [dnsdist §3.2].

Both supervisors ship in v0.1 (compose edge and ha-static profiles; Kubernetes edge Deployment behind edge.enabled). keepalived is never the default VIP in Kubernetes [k8s §16.14, dnsdist §6.12]. Alternative for operators who must run unmodified upstream images: edge.image.mode: upstream runs the agent as a sidecar sharing an emptyDir and converges by restart only (documented, non-default).

The VIP abstraction the risk table (§14 #4) refers to:

// internal/edge/vip/provider.go — implemented by keepalived (track_file + FIFO), kube-vip and MetalLB (Service status + annotations), none
type Provider interface {
    Name() string                                   // keepalived | kube-vip | metallb | none
    VIPs() []VIP                                    // {Name, Address, VRID?, Owner string, Weight int}
    Owner(vip string) (node string, ok bool)        // current MASTER / announcing node, from FIFO or Service status
    SetWeight(ctx context.Context, vip string, w Weight) error   // Weight = Serving(0) | PreferNot(60) | Fault(300); no-op for Service-based providers
    Events() <-chan VIPEvent                        // {VIP, Node, State MASTER|BACKUP|FAULT|STOP, Priority, At}
}

4. Data model, storage, replication, HA

4.1 Objects

All objects are api/v1alpha1 Go structs with metadata{name,namespace?,labels,annotations,uid,generation,resourceVersion,creationTimestamp,managedBy}, spec, status{observedGeneration,conditions[]}. Names are stable keys. Record data is the external-dns Endpoint shape plus a kudurru extension block.

// api/v1alpha1/dnszone_types.go (cluster-scoped)
type DNSZoneSpec struct {
    ZoneName     string         `json:"zoneName"`                 // immutable (CEL self==oldSelf), FQDN with trailing dot
    Type         ZoneType       `json:"type"`                     // primary | forward | secondary(v0.2) | stub(v0.2) | external(v0.2) | catalog(v1.0) | secondaryCatalog(v1.0)
    SOA          *SOASpec       `json:"soa,omitempty"`            // mname, rname, refresh, retry, expire, minimum; serial lives in status
    Nameservers  []string       `json:"nameservers,omitempty"`
    DefaultTTL   uint32         `json:"defaultTTL,omitempty"`     // 300
    Policy       ZonePolicy     `json:"policy"`                   // Technitium's six-way vocabulary [technitium §4.2]
    Forward      *ForwardSpec   `json:"forward,omitempty"`        // upstreamGroup, dnssecValidation
    Secondary    *SecondarySpec `json:"secondary,omitempty"`      // primaries[], tsigKeyRef, transferProtocol tcp|tls (v0.2)
    Stub         *StubSpec      `json:"stub,omitempty"`           // nameservers[] (v0.2)
    External     *ExternalSpec  `json:"external,omitempty"`       // ingress/gateway/loadbalancer sources (v0.2)
    DNSSEC       *DNSSECSpec    `json:"dnssec,omitempty"`         // enabled, algorithm, denial nsec|nsec3, keySecretRef, kskRollover, zskRolloverDays (v1.0; schema reserved)
    RecordSetSelector *RecordSetSelector `json:"recordSetSelector,omitempty"` // namespaces[]/labelSelector allowed to add DNSRecordSets
    Publish      []PublishRule  `json:"publish,omitempty"`        // split-horizon: integrationRef + selector + types + policy + defaults (v0.2)
}
type ZonePolicy struct {
    QueryAccess  AccessMode `json:"queryAccess"`     // deny|allow|allowOnlyPrivate|allowOnlyZoneNameServers|useNetworkACL|zoneNameServersAndACL
    QueryACL     []string   `json:"queryACL,omitempty"`      // "10.0.0.0/8", "!10.0.0.2": ordered, first match wins, default deny
    ZoneTransfer AccessMode `json:"zoneTransfer"`
    TransferACL  []string   `json:"transferACL,omitempty"`
    TransferTSIGKeyRefs []string `json:"transferTSIGKeyRefs,omitempty"`
    Notify       NotifyMode `json:"notify"`          // none|zoneNameServers|specified|both
    NotifyTargets []string  `json:"notifyTargets,omitempty"`
    Update       AccessMode `json:"update"`          // RFC 2136 (v0.2)
    UpdatePolicies []UpdatePolicy `json:"updatePolicies,omitempty"` // {tsigKeyRef, name, types[]}
}
type DNSZoneStatus struct {
    ObservedGeneration  int64              `json:"observedGeneration"`
    Serial              uint32             `json:"serial"`             // stamped by the leader = max(prev+1, unix_now); replicas serve this value
    ContentHash         string             `json:"contentHash"`        // sha256 of canonical RRsets; drives the serial-divergence panel
    RecordCount         int                `json:"recordCount"`
    NameserverAddresses []string           `json:"nameserverAddresses,omitempty"` // auto-detected LB IPs (k8s_gateway idea)
    DNSSEC              *DNSSECStatus      `json:"dnssec,omitempty"`   // ds[], keys[]{id,type,state}, nextResign (v1.0)
    Published           []PublicationStatus `json:"published,omitempty"` // per integration: managed, drift, conflicts, lastSync (v0.2)
    Conditions          []metav1.Condition `json:"conditions"`        // Ready, Transferred, Signed, Published, Degraded
}

// api/v1alpha1/dnsrecordset_types.go (namespaced; the "clay copies" app teams own)
type DNSRecordSetSpec struct {
    ZoneRef   ObjectRef  `json:"zoneRef"`                 // immutable
    Endpoints []Endpoint `json:"endpoints"`               // ≤ 1000 per object (CRD size ceiling), many objects per zone
}
type Endpoint struct {                                    // superset of sigs.k8s.io/external-dns/endpoint.Endpoint; ToExternalDNS() drops Kudurru
    DNSName          string             `json:"dnsName"`
    RecordType       string             `json:"recordType"`   // A AAAA CNAME DNAME MX NAPTR NS PTR SRV TLSA TXT CAA HTTPS SVCB SSHFP + TYPEnnn (RFC 3597)
    Targets          []string           `json:"targets"`      // presentation-format rdata
    RecordTTL        int64              `json:"recordTTL,omitempty"`
    SetIdentifier    string             `json:"setIdentifier,omitempty"`
    Labels           map[string]string  `json:"labels,omitempty"`        // e.g. kudurru.io/publish: cloudflare
    ProviderSpecific []ProviderSpecific `json:"providerSpecific,omitempty"` // cloudflare/proxied, cloudflare/targets …
    Kudurru          *EndpointExt       `json:"kudurru,omitempty"`       // comment, disabled, expiresAt, view (public | <ClientGroup>) (view v0.2)
}

Other kinds (abbreviated; full schemas are generated into charts/kudurru-crds):

Validation is CRD OpenAPI + CEL first (bounded lists, immutability, has(self.cloudflare) == (self.type == 'cloudflare')); the admission webhook is optional (webhook.enabled=false) so a basic install needs no cert-manager [k8s §7.3]. Cross-object checks (record under its zone, duplicates across namespaces) are reconciler conditions (OutsideZone, Duplicated), PowerDNS-Operator style.

Example (both modes; kudurru apply -f accepts this verbatim):

apiVersion: kudurru.io/v1alpha1
kind: DNSZone
metadata: { name: home-example-com }
spec:
  zoneName: home.example.com.
  type: primary
  soa: { mname: ns1.home.example.com., rname: hostmaster.example.com., refresh: 3600, retry: 900, expire: 1209600, minimum: 300 }
  nameservers: [ns1.home.example.com., ns2.home.example.com.]
  policy: { queryAccess: allow, zoneTransfer: useNetworkACL, transferACL: ["10.0.0.0/8"], notify: zoneNameServers, update: deny }
  recordSetSelector: { namespaces: [dns, apps] }
  publish:                                           # v0.2 split-horizon
  - integrationRef: { name: cf-public, namespace: dns }
    selector: { matchLabels: { kudurru.io/publish: cloudflare } }
    types: [A, AAAA, CNAME, TXT, MX, SRV, CAA]
    policy: sync
status:
  serial: 1791234567
  recordCount: 42
  nameserverAddresses: [10.0.0.53]
  conditions:
  - { type: Ready, status: "True", reason: Serving, observedGeneration: 3 }
---
apiVersion: kudurru.io/v1alpha1
kind: DNSRecordSet
metadata: { name: nas, namespace: apps, labels: { kudurru.io/publish: cloudflare } }
spec:
  zoneRef: { name: home-example-com }
  endpoints:
  - { dnsName: nas.home.example.com, recordType: A, targets: ["10.0.0.20"], recordTTL: 300, kudurru: { comment: "Synology" } }
  - { dnsName: nas.home.example.com, recordType: HTTPS, targets: ["1 . alpn=h2,h3"] }
  - dnsName: nas.home.example.com                     # v0.2: published to Cloudflare, never served internally
    recordType: CNAME
    targets: [tunnel-7f3a.cfargotunnel.com]
    providerSpecific: [{ name: cloudflare/proxied, value: "true" }]
    kudurru: { view: public }
---
apiVersion: kudurru.io/v1alpha1
kind: BlockList
metadata: { name: default-ads, namespace: dns }
spec: { mode: block, sources: [{ url: https://big.oisd.nl/, format: auto }], refreshInterval: 24h }
---
apiVersion: kudurru.io/v1alpha1
kind: ClientGroup
metadata: { name: kids, namespace: dns }
spec: { clients: [{ cidr: 10.0.20.0/24, name: "Kids VLAN" }, { hostname: "ps5*" }] }
---
apiVersion: kudurru.io/v1alpha1
kind: Policy
metadata: { name: kids, namespace: dns }
spec: { clientGroupRefs: [kids], blockListRefs: [default-ads, adult], blockMode: zeroIP, blockTTL: 10m, schedule: { weekdays: [mon,tue,wed,thu,fri], start: "08:00", end: "20:00", tz: Europe/Berlin }, priority: 10 }

4.2 Record semantics the comparables got wrong

• Zones have types and SOA/serial management from v0.1 (Gravity hard-codes serial 1337 [gravity §18.6]). Serial rule everywhere: status.serial = max(prev+1, unix_now), stamped by the leader whenever the zone's contentHash changes (kube driver: leader stamps on informer events; sqlite driver: in the same transaction). Replicas serve status.serial; the window where a replica has newer content than the stamped serial is bounded by lease renewal (≤ 15 s) and only matters to external secondaries, which the leader NOTIFYs after stamping [k8s §8].
• Typed RRsets in presentation format; all common types incl. SVCB/HTTPS (browsers bypass overrides without it [gravity #1335]), CAA, TLSA, SSHFP, NAPTR; unknown types as RFC 3597.
• CNAME exclusivity and duplicate detection across namespaces (Duplicated on the later object); mergeStrategy: union opt-in.
• Records never carry secrets. Labels, ProviderSpecific and kudurru{comment,disabled,expiresAt,view} are the only extension points; split-horizon overrides live in providerSpecific (cloudflare/targets, cloudflare/proxied) and in kudurru.view [integrations §2.5].
• Per-record disabled and expiresAt (Technitium's expiry TTL) are honoured by zonecache, not by the store.

4.3 The Store interface (the seam everything depends on)

// internal/store/store.go
type Key struct{ Kind Kind; Namespace, Name string }
type Store interface {
    Get(ctx context.Context, key Key, into Object) error
    List(ctx context.Context, kind Kind, opts ListOptions) (ObjectList, error)   // keyset pagination, label selectors
    Apply(ctx context.Context, obj Object, opts ApplyOptions) (Object, error)    // whole-object apply; see contract below
    Delete(ctx context.Context, key Key, opts DeleteOptions) error              // honours finalizers
    UpdateStatus(ctx context.Context, obj Object) error                          // leader-only callers
    Watch(ctx context.Context, kind Kind, opts WatchOptions) (Watcher, error)    // list+watch, resync, compaction-safe; Added|Modified|Deleted|Bookmark
    Elector(name string) Elector                                                 // leader election primitive (named: controller, integration-<ns>-<name>)
    Snapshot(ctx context.Context, w io.Writer, opts SnapshotOptions) error       // `kind: List` YAML of all kinds (+ internal kinds unless --safe)
    Restore(ctx context.Context, r io.Reader) error                              // = apply
    Info() Info                                                                  // driver, SchemaVersion, ClusterID, Epoch, Leader
}
type ApplyOptions struct {
    Manager                 string   // "api" | "file:<path>" | "integration:<name>" | "bootstrap" | "system"  → metadata.managedBy
    ExpectedResourceVersion string   // optimistic concurrency; mismatch → ErrConflict (409 conflict)
    Force                   bool     // override managedBy (admin only, audited)
}
type Elector interface { Run(ctx context.Context, onStarted, onStopped func()) error; IsLeader() bool; Leader() string }

Apply contract (bounds the "SSA emulation" to something a small team can keep correct):

1. Whole-object apply; no partial KV puts. The API layer computes merges for PATCH and records convenience routes and then calls Apply.
2. metadata.managedBy must equal opts.Manager or be empty (first write); otherwise ErrManagedBy{Owner} → HTTP 409 managed_by with the owner in hint (UI shows "managed by file objects/zones.yaml" / "managed by Kubernetes"). In Kubernetes the kube driver uses server-side apply with FieldOwner(manager) and ForceOwnership only when Force; managedBy is mirrored in the annotation kudurru.io/managed-by. Field-manager tracking below the whole object is not emulated in the sqlite driver — by design.
3. The caller (API/controller) stamps uid, creationTimestamp, timestamps and serial candidates; drivers store them verbatim (the apiserver necessarily overrides uid/resourceVersion/creationTimestamp in k8s). This keeps the future raft FSM deterministic without touching callers.
4. Validation (OpenAPI + CEL, bounded lists, immutability) runs in the driver-independent store.Validator before any driver; both modes reject the same inputs. Entry points (D70): Validate for Apply, ValidateStatus for UpdateStatus, ValidateUnstructured for API and file input (strict unknown fields, complete defaulting, then conversion to the Go type). The validator writes schema defaults back into the object. Every list whose items carry CEL rules needs maxItems or the CRD will not install (the apiserver's static cost estimate; TestEmbeddedCRDsInstall enforces it); optional struct-typed fields with defaults use omitzero.
5. Status and generation (D70): Apply writes the main resource and ignores status; UpdateStatus writes status and ignores spec; generation increments only when the spec changes and an identical re-apply is a no-op (resourceVersion may stay). Force is a whole-object takeover (field ownership reassigned first).
6. Audit: the audit row for a mutation is written in the same SQLite transaction as the mutation in the sqlite driver (table audit in state.db); in the kube driver the apiserver audit log covers the write and kudurru's audit (in local.db) adds actor/why.

Schema versioning (every driver, from v0.1): store.SchemaVersion is compiled into the binary; state.db/local.db carry meta.schema_version. On open: a newer on-disk version than the binary → refuse to start loudly (doctor explains); older → migrate inside one transaction. Follower (v0.2): the primary serves snapshots with X-Kudurru-Schema-Version; a follower at a lower version halts replication with a diagnosis message instead of guessing. Raft (v1.0): every Command carries MinVersion; cluster version = min(node versions); the leader applies Migrate only when every member is at or above the target.

Rules that keep the drivers interchangeable: serving never reads the store on the query path; runtime data (query log, cache, sessions) never goes through Store; backup format = Snapshot output = the YAML kudurru apply -f accepts = kubectl get kudurru.io -A -o yaml (kind: List); the conformance suite (internal/store/conformance) runs against sqlite and kube (envtest) in CI and later against follower and raft.

4.4 Exact HA decision per deployment shape

Cold start without the apiserver . zonecache writes the complete materialised object set (all kudurru.io kinds as JSON + the resourceVersion high-water mark) to local.db after every successful sync and then at most every 30 s when changed. On start, if informers have not synced within store.kube.startupTimeout (15 s), the pod loads local.db, sets Degraded{reason: ServingFromSnapshot}, exposes kudurru_store_snapshot_serving 1 and kudurru_store_snapshot_age_seconds, and reports ready (so it takes traffic: cached and forwarded answers and primary zones from the snapshot). When informers sync, the snapshot is swapped out. If the snapshot is older than store.kube.snapshot.maxAge (24 h), primary zones answer SERVFAIL (never NXDOMAIN) while forwarding continues. local.db lives on emptyDir by default (survives container restarts and node reboots while the pod stays assigned) and on a PVC with persistence.local.enabled for clusters that need DNS before their control plane. With priorityClassName: system-cluster-critical and dnsPolicy: Default this closes the "DNS needed to bring the cluster up" trap.

Fenced promotion (follower mode, v0.2). state.db.meta carries cluster_epoch and primary_id. kudurru cluster promote on a follower increments the epoch and records itself as primary; every node advertises {epoch, primary_id} on /internal/status; a former primary that reconnects and sees a higher epoch demotes itself to follower of the new primary, refuses writes (503 fenced), and raises kudurru_cluster_fenced 1 + an alert. The UI only offers "Promote" when the old primary has been unreachable for ≥ 2 pull intervals and requires typing the node name; the residual split-brain window exists only while partitioned and promoted — documented, and the reason raft replaces this in v1.0.

Why not embedded etcd or raft in v0.1: the k8s path already has a replicated store; the single-Docker path needs none; writing membership/join/snapshot/mixed-version logic is where Gravity accumulated its worst bugs (#837, #894, #1093, #1389, #927, #1949) [gravity §16]; we never have two editable sources of truth [k8s §16.1]. The raft driver adopts the single-binary-first proposal's safety rules up front: a node with existing raft state ignores bootstrap settings; a failed join retries forever with backoff and never bootstraps a new cluster; doctor warns on 2-node quorum; hostnames are raft addresses; preStop runs kudurru cluster leave.

4.5 Runtime data placement

4.6 Leader-only work and what happens on failover

Leader loops are idempotent and level-triggered; timers they need to resume (nextResign, secondary refresh, list refresh, resync) are stored in object status, so any new leader resumes without redoing work. Specific rules:

• Blocklists: leader fetches, publishes status.sources[].digest; replicas pull bodies from the leader's :8082/internal/lists/<digest> (sha256-verified) and compile locally; after 10 min without a reachable leader a replica falls back to its disk cache, then to fetching itself (§7.3).
• Secondary zones (v0.2): every replica transfers independently from the configured external primaries and persists the zone in local.db (no leader in the transfer path, so leader flaps cannot re-transfer); NOTIFY-in arrives at whichever pod the LB picks and is fanned out over :8082/internal/events; the leader only reports Transferred.
• Signed zones (v1.0): the leader signs; signed RRsets and the journal are zone data (never CRDs) held in the leader's local.db and served to replicas by IXFR over the headless Service with a chart-generated TSIG key; replicas persist them. A new leader does not re-sign on takeover: it loads the current signed state by IXFR from any replica (or its own copy), reads keys from the Secret and continues the schedule in status.dnssec.nextResign; it signs only RRsets whose content changed or whose RRSIGs are within the resign window. ECDSA non-determinism is therefore irrelevant (one signer at a time, sequential) [go-dns-stack §3.2, §17.4].
• Integrations (v0.2): one Lease per instance so instances spread across replicas and fail over independently.
• NOTIFY/AXFR towards external secondaries from Kubernetes: NOTIFY leaves from the leader pod and is SNAT'ed to a node/egress IP on most CNIs and clouds, and the secondary's allow-notify/primaries list must contain that address, not the Service VIP; kudurru doctor reports the observed egress address (via a self-NOTIFY round trip to the health.kudurru.internal. listener) and the chart documents an egress gateway / hostNetwork DaemonSet as the fix when a stable source is required. AXFR/IXFR to kudurru (secondaries, v0.2) and from kudurru (TCP via the LoadBalancer) are unaffected.

5. Kubernetes model

"Kubernetes-native" means three separable things [k8s §1]; kudurru does all three, staged:

1. Good-citizen dataplane (v0.1): non-root on :53 under the Restricted PSS, /healthz/* split, lameduck, Deployment + PDB + topology spread, Helm OCI + kustomize, dnsPolicy: Default.
2. Kubernetes API as configuration surface (v0.1 for DNS/blocking kinds, v0.2 for IAM/Integration/Kudurru): CRDs reconciled by a Lease-elected controller inside the same binary; status.conditions per api-conventions; Events; never phase.
3. Kubernetes as a DNS data source (v0.2): DNSZone.type: external synthesises records from Ingress / Gateway API routes / LoadBalancer Services via stripped, indexed informers (k8s_gateway / CoreDNS technique), honouring external-dns.kubernetes.io/{hostname,target,ttl} (+ legacy alpha prefix). Replacing CoreDNS for cluster.local is not in scope before 1.x (§15).

5.1 Objects shipped

• CRD chart kudurru-crds (Helm never upgrades crds/; separate chart + helm.sh/resource-policy: keep; docs show kubectl apply --server-side -f crds.yaml) [k8s §9.5].
• v0.1 CRDs: DNSZone (cluster), DNSRecordSet, BlockList, ClientGroup, Policy (namespaced); compatibility watch of externaldns.k8s.io/v1alpha1 DNSEndpoint (zone inferred by suffix, read-only, never owned).
• v0.2 CRDs: Kudurru, Integration, IdentityProvider, RoleBinding, ServiceAccount. Typed Secrets: kudurru.io/tsig, kudurru.io/dnssec-key, kudurru.io/session-key.
• Aggregated ClusterRoles kudurru-viewer|editor|admin labelled rbac.authorization.k8s.io/aggregate-to-view|edit|admin (PowerDNS-Operator pattern) plus kudurru-auditor, which aggregates nowhere because it reads the query log; make rbac-manifests generates them from internal/rbac/permissions.yaml into charts/kudurru/templates/rbac-aggregated.yaml and a test fails on drift [k8s §10].
• Print columns and short names: kubectl get zones → ZONE TYPE SERIAL RECORDS READY AGE; rrsets → ZONE NAMES READY PUBLISHED AGE; blocklists → MODE ENTRIES LAST-FETCH READY; shortNames zone, rrset, blocklist, cg, pol, integ, idp.
• Events on CRs: SerialBumped, NotifyFailed, ListFetchFailed, Duplicated, OutsideZone, PublishConflict, Transferred, Signed.
• API versions v1alpha1 → v1beta1 (v1.0 release) → v1; storage-version progression with no-op conversion until a breaking change forces a webhook.

5.2 Workload, Helm values outline, probes, ports

Chart charts/kudurru (values modelled on the CoreDNS chart):

mode: kubernetes                    # kubernetes = kube driver + Deployment | standalone = sqlite driver + StatefulSet(1) + PVC, no CRDs
replicaCount: 2
image: { repository: ghcr.io/robertherbaugh/kudurru, tag: "", digest: "", pullPolicy: IfNotPresent }
service:
  dns:  { type: LoadBalancer, port: 53, splitProtocols: false, loadBalancerIP: "", loadBalancerClass: "",
          externalTrafficPolicy: Local, ipFamilyPolicy: PreferDualStack, trafficDistribution: "", annotations: {} }
        # one mixed-protocol Service by default (GA since 1.26); splitProtocols=true emits dns-udp + dns-tcp with metallb.io/allow-shared-ip
  dot:  { enabled: false, port: 853 }
  doh:  { enabled: false, port: 443 }
  doq:  { enabled: false, port: 853 }             # udp
  doh3: { enabled: false, port: 443 }             # udp
  api:  { type: ClusterIP, port: 8080 }           # expose via Ingress/HTTPRoute; OIDC redirect URL derived from ingress.host
  headless: { name: kudurru-dns, publishNotReadyAddresses: true }   # edge backends, IXFR between replicas, NOTIFY source
ingress: { enabled: false, className: "", host: "", tls: [] }
listen: { port: 53 }                # 1053 escape hatch for clusters that forbid NET_BIND_SERVICE
edge:                               # dnsdist tier (v0.1 behind a flag; default off)
  enabled: false
  mode: deployment                  # deployment | sidecar (single-node k8s: shares the pod netns, kudurru on 5353) | daemonset (with vip.provider=keepalived)
  replicas: 2
  image: { repository: ghcr.io/robertherbaugh/kudurru-dnsdist, digest: "" }
  authoritativeCache: false
  dynblocks: { enabled: false }
  ebpf: { enabled: false }          # opt-in "performance" profile; needs retained caps
  proxyProtocolSecret: ""           # generated once if empty; mounted in edge AND kudurru pods; PROXYv2 TLV 0xE0 (§3.3) — pod-CIDR trust alone is spoofable
vip:
  provider: none                    # none | kube-vip | metallb | keepalived
  address: ""                       # emits kube-vip.io/loadbalancerIPs or metallb.io/loadBalancerIPs (+ allow-shared-ip when split)
  keepalived: { nodeSelector: { kudurru.io/vip: "true" }, interface: "", vrid: 53, hmacSecret: "" }  # opt-in DaemonSet + hostNetwork edge
hostNetwork: { enabled: false }     # switches to DaemonSet, NET_BIND_SERVICE, dnsPolicy ClusterFirstWithHostNet
securityContext: { runAsNonRoot: true, runAsUser: 65532, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false,
                   seccompProfile: { type: RuntimeDefault }, capabilities: { drop: [ALL], add: [NET_BIND_SERVICE] } }
resources: { requests: { cpu: 100m, memory: 256Mi }, limits: { memory: 1Gi } }
podDisruptionBudget: { enabled: true, minAvailable: 1 }
topologySpreadConstraints: [ { topologyKey: kubernetes.io/hostname, whenUnsatisfiable: ScheduleAnyway } ]
priorityClassName: ""               # system-cluster-critical when kudurru is the cluster resolver
dnsPolicy: Default                  # never ClusterFirst for the DNS server itself
persistence:
  querylog: { enabled: false, storageClass: "", size: 10Gi, accessModes: [ReadWriteOnce] }
  local:    { enabled: false, size: 1Gi }         # local.db on a PVC for "DNS before control plane" clusters
  standalone: { size: 5Gi }                       # mode=standalone only
config:                             # rendered into TWO ConfigMaps: kudurru-node (hostOnly/restartRequired keys → checksum annotation rolls pods)
  node: {}                          #                             kudurru-settings (hot-reloaded on change, no restart)
  settings: {}                      # the Kudurru singleton (v0.1 ConfigMap; v0.2 CRD)
objects: []                         # optional inline kudurru.io objects applied by a post-install Job (seed only; then kubectl owns)
auth:
  encryptionKeySecret: ""           # generated once if empty
  bootstrapAdminSecret: ""          # generated once if empty; printed by `helm status` notes
  oidc: { issuer: "", clientID: "", clientSecretRef: {}, groupsClaim: groups, groupsPrefix: "corp:" }
  kubernetes: { mode: sar }         # sar (default) | impersonate (v0.2, needs the impersonate ClusterRole and auth.kubernetes.usernamePrefix/groupsPrefix)
rbac: { create: true, aggregateToDefaultRoles: true }
webhook: { enabled: false }         # validating webhook optional; CEL does the rest
serviceMonitor: { enabled: false }  prometheusRule: { enabled: false }  grafanaDashboard: { enabled: false }
networkPolicy: { enabled: false }
externalDNS: { webhook: { enabled: false, listen: ":8888" } }   # kudurru as an external-dns webhook provider (in-process) or sidecar values

The shipped chart differs from this outline where milestone M3 decided so (D105): node and settings files at /etc/kudurru/node/ and /etc/kudurru/settings/, preStop: sleep until a server-side POST /lameduck exists (the client is kudurru lameduck 5s), the ip_unprivileged_port_start sysctl instead of a file capability, a StatefulSet for per-pod persistence, keepalived as a second container of the edge DaemonSet, and auth.oidc.providers (a list rendered into auth.identityProviders) instead of the single-issuer auth.oidc; docs/deploy/helm.md lists every value.

Pod template facts: image ghcr.io/robertherbaugh/kudurru:<ver>@sha256 (distroless static, uid 65532, file capability cap_net_bind_service=+p raised only when a port < 1024 is configured, blocky-style) [k8s §9.2]; checksum/config annotation covers only the kudurru-node ConfigMap (CRD and settings changes never restart pods) [k8s §16.6]; terminationGracePeriodSeconds: 30 with preStop: kudurru lameduck 5s; args serve --store=kube --node-name=$(POD_NAME) --proxy-protocol-from=<edge pod CIDR> (a CIDR is accepted only together with the TLV secret, D72).

Probes on the ops listener :8081 (no auth) [observability §4.1]:

Ports: 53/udp+tcp DNS (5353 PROXYv2-only when the edge is enabled), 853/tcp DoT, 853/udp DoQ, 443/tcp DoH, 443/udp DoH3 (8443 if not root-capable), 8080 API/UI, 8081 ops, 9153 metrics, 8082 internal (node-to-node), 8084 edge supervisor readiness, 8888 external-dns webhook (optional), 7000/7001 raft + peer API (v1.0).

5.3 Leader election, leases, RBAC for the kudurru ServiceAccount

Lease kudurru-controller in the release namespace, 15 s/10 s/2 s, identity = pod name; runnables implement NeedLeaderElection() per §3.1; per-integration Leases integration-<ns>-<name> (v0.2); kudurru_leader{role} gauge; no per-node Lease and no NodeStatus objects — the Nodes page scatter-gathers /internal/status over the headless EndpointSlice [observability §5].

Election lifecycle is decoupled from process lifetime (D44). The election is driven by internal/cluster with client-go's leaderelection.LeaderElector directly, not by the controller-runtime Manager's process-level election: OnStartedLeading starts the leader-only runnable group under a child context, OnStoppedLeading cancels only that group and re-enters Run after RetryPeriod; the process never exits on leadership loss. Stock controller-runtime stops the whole Manager when the lease is lost and kubebuilder scaffolds exit the binary (LeaderElectionReleaseOnCancel "requires the binary to immediately end when the Manager is stopped" [k8s §7.4]) — that would kill the DNS dataplane on every pod during exactly the apiserver outage §4.4 is designed to survive (lease renewal fails after RenewDeadline 10 s). ReleaseOnCancel semantics are applied only on SIGTERM (kudurru lameduck). A leader that loses the lease while a leader-only loop is mid-operation relies on the idempotent, level-triggered rules of §4.6; the dataplane's informers keep serving the last snapshot throughout.

Least-privilege ClusterRole for the kudurru SA:

get,list,watch,create,patch,delete   kudurru.io/* (server-side apply needs create+patch; file objects and finalizers need delete);
get,list,watch            externaldns.k8s.io/dnsendpoints; "" services,namespaces; discovery.k8s.io/endpointslices;
                          networking.k8s.io/ingresses; gateway.networking.k8s.io/httproutes,tlsroutes,grpcroutes (v0.2, only when external zones are enabled)
update,patch              kudurru.io/*/status
create,patch              "" events
get,create,update         coordination.k8s.io/leases   (Elector(name) → Lease `kudurru-<name>`; integrations use `kudurru-integration-<ns>-<name>`, D78)
get,list,watch,create,update,patch,delete   "" secrets   (Role in the release namespace only: internal kinds, TSIG, DNSSEC keys, session key; revocation and user/RoleBinding deletion delete Secrets)
create                    authentication.k8s.io/tokenreviews; authorization.k8s.io/subjectaccessreviews   (system:auth-delegator; v0.1)
impersonate               "" users,groups,serviceaccounts; authentication.k8s.io/userextras/*   (ONLY when auth.kubernetes.mode=impersonate, v0.2)

5.4 Edge and VIP in Kubernetes

• Default: no dnsdist; the LoadBalancer Service points at kudurru pods; externalTrafficPolicy: Local preserves client IPs (per-client stats and client groups are the product) [k8s §16.12].
• edge.enabled=true (v0.1): Deployment kudurru-edge from the supervisor image with anti-affinity and a PDB; backends from the headless EndpointSlice (--backends-from endpointslice:<ns>/kudurru-dns), stable UUID per pod name, chashed for the resolver pool, leastOutstanding for authoritative, use_proxy_protocol: true; readiness probe GET :8084/healthz/ready on the supervisor; the Service then targets the edge pods and kudurru listens on 5353 with proxyProtocolFrom = the edge pods' CIDR plus the edge.proxyProtocolSecret TLV check (§3.3) — the pod CIDR is shared with every other workload, so CIDR trust alone would let any pod forge client addresses; the chart's networkPolicy template additionally restricts :5353 ingress to pods labelled app.kubernetes.io/component=edge. edge.mode: sidecar for single-node k8s shares the pod netns (loopback, no TLV needed) [dnsdist §1.15].
• VIP: vip.provider kube-vip/metallb only add annotations (both Apache-2.0 and Service-aware) [dnsdist §2.5]. keepalived deploys a DaemonSet (hostNetwork, NET_ADMIN/NET_RAW/NET_BROADCAST, nodeSelector kudurru.io/vip=true) running kudurru vip run with unicast_peer rendered from the selected Nodes and switches the edge to a hostNetwork DaemonSet on the same nodes so the VIP owner actually listens on :53 [dnsdist §3.3]; re-render + SIGHUP on Node-list change (shared PID namespace not required: the supervisor is PID 1).

5.5 Kubernetes identities and authorization (v0.1: SAR; v0.2: impersonation opt-in)

• Bearer tokens that are projected ServiceAccount tokens (audience: kudurru) are verified via the cluster's OIDC discovery/JWKS (issuer read from /.well-known/openid-configuration with the pod's own token), falling back to TokenReview with an audience check, cached ≤ 2 min by token hash; principal system:serviceaccount:<ns>:<name> with its groups [auth §4.6].
• SubjectAccessReview on kudurru.io resources — real CRDs and virtual resources (querylogs, stats, caches, blocking, audits, clusters, settings) — makes k8s RBAC the policy for Kubernetes identities without any extra CRD; RBAC rules are strings. The kudurru SA needs only system:auth-delegator.
• OIDC humans use kudurru RoleBindings (§8.5). Precedence rule: a request is allowed if either path allows it; the audit record names the path that granted (authz: sar|binding).
• auth.kubernetes.mode: impersonate (v0.2, opt-in): UI/API writes are sent with Impersonate-User/Group headers so apiserver RBAC and audit see the real user. Not the default because the impersonate grant makes an internet-facing DNS/HTTP server cluster-admin-equivalent if compromised, and the research never vetted it [k8s §10].

5.6 external-dns compatibility

kudurru natively serves the external-dns webhook provider contract (GET /, GET/POST /records, POST /adjustendpoints, application/external.dns.webhook+json;version=1, 204 on apply, 5xx-only retries, 32 MiB cap) on :8888 in-process on every replica (reads come from the zone snapshot; applied Changes go through Store.Apply, which any replica can perform in kube mode because the apiserver is the store — a leader-only listener behind a Service would 503 on non-leader pods) or as a kudurru externaldns-webhook sidecar in the external-dns pod; applied Changes become DNSRecordSets with managedBy: integration:external-dns in a configured namespace; external-dns TXT ownership records are stored as ordinary TXT. DNSEndpoint CRs are additionally read directly [k8s §3.4, §3.5].

5.7 Packaging

charts/kudurru + charts/kudurru-crds (OCI), config/ kubebuilder kustomize tree with overlays metallb, kube-vip, cloud-lb-mixed, hostnetwork-daemonset, standalone, with-edge; release artifacts crds.yaml + install.yaml; ServiceMonitor/PodMonitor, Grafana dashboard ConfigMap and PrometheusRule (§11.6) behind values. Minimum Kubernetes 1.30. OLM bundle only after v1 CRDs.

6. Single-instance Docker model

6.1 Image

ghcr.io/robertherbaugh/kudurru:<ver> built by goreleaser kos: + ko from gcr.io/distroless/static:nonroot (digest pinned), linux/amd64, linux/arm64 only (D68), cosign keyless signature + SBOM + SLSA provenance. EXPOSE 53/udp 53/tcp 853/tcp 853/udp 443/tcp 443/udp 8080 8081 9153. HEALTHCHECK CMD ["kudurru","health","--ready"]. uid 65532; :53 binds through the net.ipv4.ip_unprivileged_port_start=0 sysctl the chart and Docker provide (D105). Host networking cannot use that sysctl: <ver>-hostnetwork (and latest-hostnetwork) is the same binary with the file capability cap_net_bind_service=+ep, built by publish.yml from the ko image (ko cannot set file capabilities; images/hostnetwork/Dockerfile), and the chart's hostNetwork.enabled runs it with NET_BIND_SERVICE added and allowPrivilegeEscalation: false. Startup contract copied from the dnsdist image: env → rendered config fragment, KUDURRU_DEBUG_CONFIG=yes prints the effective config with secrets masked. A -debug variant is built on distroless debug-nonroot, which adds busybox (a shell and nslookup; distroless has no dig, D105). Both bases are pinned by digest.

6.2 Config file (/etc/kudurru/kudurru.yaml) — metadata-driven, two scopes

One metadata table (internal/config/schema.go) describes every key: type, default, allowed values, help, flags restartRequired, envLocked, writeOnly, hostOnly. It drives the YAML loader (JSON Schema published for # yaml-language-server), KUDURRU_<SECTION>__<KEY> env overrides and *_FILE variants (env-set values become read-only in the UI, Pi-hole's single-source rule), kudurru config get|set|schema, PATCH /api/v1/node/config, the generated "All settings" page and the docs page; the generator is tested so docs cannot drift [pihole §16.8]. Code-bearing or privileged keys are hostOnly from v0.1 (listener addresses, TLS paths, data dir, proxyProtocolFrom, edge/vip paths and VRIDs, cluster peers) and can never be set through the API — the Pi-hole 2026 RCE class made structural [pihole §17.7].

Two scopes in one file: node settings (node, listeners, data, log, edge, vip, cluster) are host-local; cluster settings (upstreams, cache, blocking, querylog, auth, rbac) are the Kudurru singleton and are replicated in multi-node shapes. Objects (zones, lists, groups, policies, bindings, integrations) may be embedded under objects: or dropped into objects.d/*.yaml (file-managed, managedBy: file:<path>, re-applied on fsnotify change; deleting a document deletes the object), or live in the store and be edited through UI/API/CLI (managedBy: api). kudurru apply -f accepts CRD YAML verbatim.

# /etc/kudurru/kudurru.yaml  (v0.1)
node: { name: "${HOSTNAME}", dataDir: /var/lib/kudurru }                 # hostOnly
listeners:                                                               # hostOnly
  dns:  [{ address: "0.0.0.0:53", protocols: [udp, tcp] }]
  dot:  [{ address: "0.0.0.0:853", tls: { certFile: /certs/tls.crt, keyFile: /certs/tls.key } }]
  doh:  [{ address: "0.0.0.0:443", path: /dns-query, tls: { certFile: /certs/tls.crt, keyFile: /certs/tls.key } }]
  doq:  [{ address: "0.0.0.0:853", tls: { certFile: /certs/tls.crt, keyFile: /certs/tls.key } }]                     # udp, ALPN doq
  doh3: [{ address: "0.0.0.0:443", path: /dns-query, tls: { certFile: /certs/tls.crt, keyFile: /certs/tls.key } }]   # udp, ALPN h3
  proxyProtocolFrom: []             # ["127.0.0.1/32","::1/128"] when dnsdist shares the netns; exact /32s, never a LAN /24 (§3.3)
  proxyProtocolSecretFile: ""       # PROXYv2 TLV 0xE0 shared with the dnsdist supervisor; required when proxyProtocolFrom is non-loopback
  api:  { address: "0.0.0.0:8080", tls: { auto: selfsigned }, pathPrefix: "" }
  ops:  { address: "0.0.0.0:8081" }
  metrics: { address: "0.0.0.0:9153" }
  internal: { address: "0.0.0.0:8082", tokenFile: "",                 # token + node cert derived from the encryption key unless set; always TLS
              tls: { certFile: "", keyFile: "", caFile: "", serverName: "" } }   # all empty: the CA and certificate derived from the encryption key
  sockets: 0                        # SO_REUSEPORT sockets per udp/tcp DNS listener; 0 = GOMAXPROCS, 1 = a single socket
upstreams:
  groups:
    default: { servers: ["tls://1.1.1.1", "tls://9.9.9.9"], strategy: parallel_best, timeout: 2s }
    internal-ad: { servers: ["10.0.0.5:53"], strategy: strict }
  bootstrap: ["1.1.1.1:53"]
  conditional: { "corp.example.": internal-ad, "10.in-addr.arpa.": internal-ad }
  ecs: { mode: strip, ipv4Prefix: 24, ipv6Prefix: 56 }   # strip (privacy default) | forward | add
cache: { maxEntries: 200000, minTTL: 5s, maxTTL: 24h, negativeTTL: 5m, prefetch: { threshold: 5, window: 2h },
         serveStale: { ttl: 72h, answerTTL: 30s, maxWait: 1800ms } }
blocking:
  enabled: true
  defaultResponse: zeroIP           # zeroIP | nxdomain | customIP | refused (discouraged)
  blockTTL: 10m
  initStrategy: fast                # fast | blocking | failOnError (disk-seeded)
  refreshInterval: 24h
  allowDegraded: true
  listsDir: ""                      # hostOnly; list body cache, default <dataDir>/lists
ratelimit:                          # per-prefix QPM on UDP at ingress (§7.1 step 2); TCP/DoT/DoH/DoQ/DoH3 and loopback never limited
  enabled: true
  ipv4: { "32": 600, "24": 6000 }
  ipv6: { "128": 600, "64": 6000, "56": 12000 }
  slip: 50                          # % of over-limit queries answered TC=1, the rest dropped
  maxBuckets: 65536
  exempt: []
querylog: { enabled: true, privacy: full, retention: { raw: 720h, maxDBBytes: 10GiB }, exclude: { domains: [], clients: [], sudn: true } }
auth:
  localLogin: enabled               # enabled | admins-only | disabled
  bootstrap: { adminPasswordFile: /run/secrets/admin_password }
  session: { idleTimeout: 30m, lifetime: 12h, secure: auto }   # auto = Secure when TLS terminates here or a trusted proxy sends X-Forwarded-Proto: https; plain-HTTP labs still get SameSite=Lax + CSRF header
  identityProviders:
  - id: corp-sso
    issuer: https://auth.example.com/application/o/kudurru/
    clientID: kudurru
    clientSecretFile: /run/secrets/oidc_client_secret
    cliClientID: kudurru-cli
    scopes: [openid, profile, email, groups]
    claimMappings: { username: { claim: preferred_username }, groups: { claim: groups, prefix: "corp:" } }
    provisioning: { autoProvision: mapped-only, syncGroups: true }
  kubernetes: { mode: sar }         # hostOnly; sar (v0.1) | impersonate (v0.2)
  adminSocket: { path: /run/kudurru/kudurru.sock, group: -1 }   # hostOnly; `kudurru admin` (D101); empty path disables
rbac:
  bindings:
  - { role: admin, scope: { kind: cluster }, subjects: [{ kind: Group, name: "corp:/dns-admins" }] }
edge: { enabled: false }            # hostOnly; see compose profiles
vip:  { enabled: false }            # hostOnly
objects:                            # optional inline CRD-shaped objects (managedBy: file:kudurru.yaml)
- apiVersion: kudurru.io/v1alpha1
  kind: BlockList
  metadata: { name: default-ads }
  spec: { mode: block, sources: [{ url: https://big.oisd.nl/ }], refreshInterval: 24h }
- apiVersion: kudurru.io/v1alpha1
  kind: Policy
  metadata: { name: default }
  spec: { clientGroupRefs: [default], blockListRefs: [default-ads] }

6.3 Persistence under /var/lib/kudurru

state.db        # sqlite store driver: all api/v1alpha1 objects + internal kinds (JSON rows), change feed, zone journals, audit table; meta.schema_version
querylog.db     # per-node fact table + rollups (WAL, synchronous=NORMAL, incremental_vacuum)
local.db        # (kube driver only) last-good snapshot + audit; (all drivers) response-cache dump on shutdown
lists/          # sha256(url) disk cache of blocklist bodies
keys/           # cookie/encryption key if not provided via env; TSIG/DNSSEC material (encrypted, v0.2+)
edge/           # rendered dnsdist.yml / keepalived.conf (compose profiles mount read-only; supervisors render their own)
backups/        # `kudurru backup` output when --out is omitted

Backup: kudurru backup --out kudurru-backup.tar.zst = Store.Snapshot (kind: List YAML) + optional query log; --safe strips secrets, sessions, tokens; kudurru restore applies it; kudurru export --safe -o cluster.yaml emits applyable YAML; the same YAML seeds followers (v0.2) and first boot (KUDURRU_IMPORT=/path.yaml). kudurru import bind|pihole|adguard|blocky|technitium converts foreign formats into the same YAML.

6.4 Compose: single instance (+ edge profile)

# deploy/compose/single/docker-compose.yml
services:
  kudurru:
    image: ghcr.io/robertherbaugh/kudurru:0.1.0
    restart: unless-stopped
    ports: ["53:53/udp", "53:53/tcp", "8080:8080"]            # dropped when profile edge owns :53
    environment:
      KUDURRU_ADMIN_PASSWORD_FILE: /run/secrets/admin_password
      KUDURRU_ENCRYPTION_KEY_FILE: /run/secrets/encryption_key
      TZ: Europe/Berlin
    volumes: ["./kudurru.yaml:/etc/kudurru/kudurru.yaml:ro", "./objects.d:/etc/kudurru/objects.d:ro", "kudurru-data:/var/lib/kudurru"]
    secrets: [admin_password, encryption_key]
    healthcheck: { test: ["CMD", "kudurru", "health", "--ready"], interval: 10s, timeout: 3s, retries: 5, start_period: 60s }
  dnsdist:                                                    # profile: edge (optional)
    profiles: [edge]
    image: ghcr.io/robertherbaugh/kudurru-dnsdist:2.1.2-k0.1.0@sha256:<digest>
    command: ["kudurru", "edge", "run", "--backends", "127.0.0.1:5353", "--tls-dir", "/certs"]
    ports: ["53:53/udp", "53:53/tcp", "853:853/tcp", "853:853/udp", "443:443/tcp", "443:443/udp"]
    volumes: ["certs:/certs:ro"]
    depends_on: [kudurru]
  # with profile edge: kudurru uses network_mode: "service:dnsdist", listeners.dns address 127.0.0.1:5353, proxyProtocolFrom ["127.0.0.1/32"]
volumes: { kudurru-data: {}, certs: {} }
secrets:
  admin_password: { file: ./secrets/admin_password }
  encryption_key: { file: ./secrets/encryption_key }

First boot prints the generated admin password once (if no secret), creates the root zone . as a forwarder to upstreams.groups.default, ClientGroup/default + Policy/default, and loads the build-time-embedded starter blocklist from the embedded FS so blocking works offline (Gravity's loopback-list idea without the loopback server) [gravity §17.11]. The embedded list is built at release time from permissively licensed sources only (candidate: StevenBlack/hosts, MIT — list licences are not covered by the research and must be confirmed in the release checklist) and carries its own NOTICE entry; copyleft-licensed lists (e.g. hagezi's GPL-3.0 lists, AdGuard's filters) may be referenced by URL at runtime like any other data but are never redistributed inside the image, and licenses.yml checks the embedded list's provenance file.

6.5 Compose HA with dnsdist + keepalived

One directory per node (deploy/compose/ha/node-{a,b,c}/), identical except NODE_NAME, NODE_IP, priority index. v0.1 ha-static: every node runs the same file-managed configuration (kudurru.yaml + objects.d/ distributed by git/ansible/rsync — cluster.role: static makes the API/UI read-only for every kudurru.io object, shows "managed by file", and a diagnosis message explains that writes must go through the distributed files); v0.2: the same compose with KUDURRU_CLUSTER_ROLE=follower on nodes b/c and KUDURRU_CLUSTER_PRIMARY=https://10.0.0.11:8082 makes the UI writable on the primary and replicated; v1.0: KUDURRU_CLUSTER_PEERS + bootstrapExpect turns the same three nodes into raft voters. The dnsdist and keepalived services do not change across the three versions.

# deploy/compose/ha/node-a/docker-compose.yml   (node-a: 10.0.0.11, prio 200; node-b: 10.0.0.12, prio 190; node-c: 10.0.0.13, prio 180)
services:
  kudurru:
    image: ghcr.io/robertherbaugh/kudurru:0.1.0
    network_mode: host                                   # binds :5353 for dnsdist, :8080 API, :8082 internal; the VIP is held by keepalived
    restart: unless-stopped
    environment:
      KUDURRU_NODE__NAME: node-a
      KUDURRU_LISTENERS__DNS: "0.0.0.0:5353"
      KUDURRU_LISTENERS__PROXYPROTOCOLFROM: "127.0.0.1/32,10.0.0.11/32,10.0.0.12/32,10.0.0.13/32"   # exact peers, never the LAN /24
      KUDURRU_LISTENERS__PROXYPROTOCOLSECRETFILE: /run/secrets/proxy_secret
      KUDURRU_ADMIN_PASSWORD_FILE: /run/secrets/admin_password
      KUDURRU_ENCRYPTION_KEY_FILE: /run/secrets/encryption_key
      KUDURRU_LISTENERS__INTERNAL__TOKENFILE: /run/secrets/internal_token         # optional: defaults to a value derived from the encryption key
      # v0.2: KUDURRU_CLUSTER__ROLE=follower  KUDURRU_CLUSTER__PRIMARY=https://10.0.0.11:8082   (nodes b, c)
      # v1.0: KUDURRU_CLUSTER__BOOTSTRAPEXPECT=3  KUDURRU_CLUSTER__PEERS=10.0.0.11:7000,10.0.0.12:7000,10.0.0.13:7000
    volumes: ["./kudurru.yaml:/etc/kudurru/kudurru.yaml:ro", "./objects.d:/etc/kudurru/objects.d:ro", "kudurru-data:/var/lib/kudurru", "kudurru-run:/run/kudurru"]
    secrets: [admin_password, encryption_key, internal_token, proxy_secret]
    healthcheck: { test: ["CMD", "kudurru", "health", "--ready"], interval: 10s, timeout: 3s, retries: 5, start_period: 60s }
  dnsdist:
    image: ghcr.io/robertherbaugh/kudurru-dnsdist:2.1.2-k0.1.0@sha256:<digest>
    network_mode: host                                   # recommended so dnsdist binds the VIP as it appears (0.0.0.0:53)
    restart: unless-stopped
    command: ["kudurru", "edge", "run",
              "--backends", "10.0.0.11:5353,10.0.0.12:5353,10.0.0.13:5353",   # EVERY node lists ALL kudurru nodes
              "--pool-resolver", "chashed", "--pool-authoritative", "leastOutstanding",
              "--tls-dir", "/certs", "--api", "127.0.0.1:8083", "--console", "127.0.0.1:5199",
              "--api-key-out", "/run/kudurru/dnsdist-api.key", "--proxy-protocol-secret-file", "/run/secrets/proxy_secret"]
    secrets: [proxy_secret]
    volumes: ["certs:/certs:ro", "kudurru-run:/run/kudurru"]
    depends_on: [kudurru]
  keepalived:
    image: ghcr.io/robertherbaugh/kudurru-keepalived:2.4.3-k0.1.0@sha256:<digest>
    network_mode: host
    cap_add: [NET_ADMIN, NET_RAW, NET_BROADCAST]
    restart: unless-stopped
    stop_grace_period: 20s                               # keepalived must release the VIP before the container goes
    command: ["kudurru", "vip", "run",
              "--vip", "dns=10.0.0.53/24@eth0#53",        # name=addr/len@iface#vrid  (VRID is hostOnly, never changes on re-render)
              "--vip", "dns2=10.0.0.54/24@eth0#54",       # optional second VIP, reversed priorities → active/active
              "--peers", "10.0.0.12,10.0.0.13", "--priority-index", "0",
              "--hmac-key-file", "/run/secrets/vrrp_hmac",
              "--track-dnsdist-api", "http://127.0.0.1:8083", "--dnsdist-api-key-file", "/run/kudurru/dnsdist-api.key", "--require-backends", "1"]
    volumes: ["kudurru-run:/run/kudurru"]
    secrets: [vrrp_hmac]
    depends_on: [dnsdist]
volumes: { kudurru-data: {}, kudurru-run: {}, certs: {} }
secrets:
  admin_password: { file: ./secrets/admin_password }
  encryption_key: { file: ./secrets/encryption_key }
  internal_token: { file: ./secrets/internal_token }
  proxy_secret:   { file: ./secrets/proxy_secret }
  vrrp_hmac:      { file: ./secrets/vrrp_hmac }

Behaviour: keepalived decides VIP ownership only (VRRPv3 unicast, state BACKUP, nopreempt, auth_hmac); track_script probes the local dnsdist on :53 udp+tcp and requires ≥ 1 healthy backend; track_file /run/kudurru/weight-dns is written by the local kudurru (0/60/300); the FIFO consumer emits kudurru_vip_master{vip="dns"}. Because every dnsdist lists all nodes, a node whose kudurru is unhealthy but whose dnsdist is healthy still serves, and query logs stay correct on every node through PROXYv2 [dnsdist §3.2]. External secondaries doing AXFR from ha-static twins should transfer from one named node (serials are max(prev+1, unix_now) on each twin and therefore close but not identical); follower mode (v0.2) removes that caveat.

7. Query path and the blocking engine

7.1 Step by step (one A query from a LAN client, dnsdist in front)

1. dnsdist (optional) accepts on :53/:853/:443, ACL, DynBlocks/eBPF drop abuse, packet cache (resolver pool only), picks a backend (chashed on qname for cache locality), prepends PROXYv2 with the real client address, forwards to kudurru:5353.
2. ingress: parse PROXYv2 only from proxyProtocolFrom (else drop), parse the message (FORMERR on garbage), EDNS version check, global ACL, per-prefix QPM limiter (/32: 600 udp, /24: 6000, IPv6 /128,/64,/56; over-limit UDP → TC=1 for a percentage, then drop) [technitium §20.9]; NSID/CHAOS id.server/version.bind/hostname.bind and health.kudurru.internal. (TXT <node-id> <serial-epoch>, never logged) answered directly.
3. identify: client → ClientGroups: exact IP → longest-prefix CIDR → (v0.2) MAC via inventory → hostname/rDNS → DoT/DoH client ID (<id>.dot.<domain> SNI, /dns-query/<id>) → default. Equal-length CIDR ties raise a diagnosis message. The union of matching groups selects Policy objects (highest priority wins per setting) and the decision travels as Request.Policy [pihole §16.5, blocking §2.8].
4. control: Policy/global rules (allowedNetworks, drop malformed, refuse ANY, block qtypes) → Allow | DropSilently | Refuse; a drop returns pipeline.ErrDrop, after which the transport should send nothing (UDP/DoQ) or close the exchange (v0.1 transports still answer SERVFAIL; docs/followups.md).
5. local: custom host records / synthesised inventory names (UniFi, v0.2), SUDN (.local, .onion, RFC 6303 reverse without a zone → NXDOMAIN). Status: local_record; never cached.
6. authoritative: longest-suffix zone match over the in-memory trees (root . is a forwarder by default). Enforce queryAccess/queryACL; answer with CNAME chase (loop cap 20; into other local zones, else into the rest of the pipeline when RD), wildcards by label replacement, NODATA vs NXDOMAIN on name existence (never NXDOMAIN while unsynced: SERVFAIL [k8s §2.2]); AXFR/IXFR here (transferACL, TSIG, dns.Transfer.Out); NOTIFY/UPDATE opcodes routed to handlers (NOTIMP in v0.1). Authoritative answers are not subject to blocking (Technitium rule: your own zone cannot be blocked by a list) [technitium §3].
7. blocking (recursive path only): allow-wins-across-groups → allow-only mode → in-list @@ exception → deny ($important beats @@) → after next returns, response-side CNAME/A/AAAA/HTTPS-hint inspection against deny sets [blocking §2.7, §6.1]. A hit synthesises the policy's response (zeroIP default, nxdomain with SOA, customIP, refused discouraged), blockTTL (10 m default), EDE 15/17, Status: blocked_*, List/Rule for the UI. Temporary disable (POST /dns/blocking {blocking:false, timer:300}) is cluster-wide via Kudurru.status.blocking.disabledUntil; in v0.1 Kubernetes, where Kudurru is still a ConfigMap without a status subresource, the kube driver keeps this one runtime field in the kudurru-runtime ConfigMap (annotation kudurru.io/blocking-disabled-until, server-side applied by whichever replica served the request, watched by all), and in Docker in state.db; ha-static twins toggle node-locally (badged).
8. rewrite (v0.2): $dnsrewrite/UI rewrites, client-group views (kudurru.view), DNS64.
9. cache: key (qname,qtype,qclass,DO,ECS-scope), positive/negative split, TTL countdown, prefetch when hot and near expiry, serve-stale when all upstreams fail, in-flight coalescing; dumped to local.db on shutdown and loaded at start. Status: cached|cached_stale.
10. dnssec-validate (v0.2): validate upstream answers (blocky's resolver/dnssec as reference), AD/CD, SERVFAIL + EDE on bogus, NTA list; only validated data enters the cache.
11. upstream: Request.UpstreamGroup (forward zones, a Policy's group) → else conditional map → group; strategy; dnsproxy exchange with per-group timeout; ECS per upstreams.ecs.mode (strip default, forward, add with ipv4Prefix/ipv6Prefix); Status: forwarded, Upstream: <group/server name>; errors → servfail_upstream|timeout_upstream.
12. postprocess (v0.2): rebinding protection, AAAA filtering, NXDOMAIN override, TRACEPARENT strip.
13. log: build the QueryEvent (§11.2), non-blocking enqueue to the per-worker ring, atomic counters/histograms, dnstap CLIENT_RESPONSE (v0.2), OTel attributes (v0.2). dnsserver writes the reply; dnsdist caches it (resolver pool) and answers the client.

The decisions that once overwrote steps 3, 4, 5, 9, 11 and 13 of this list are D54, D64, D60, D62, D65 and D67 in §16.

Hard rules: the query path never touches Store, never blocks on logging, never waits on a leader, and keeps answering from the last snapshot when the store is unreachable [gravity §4.4].

7.2 Policy model

Source     {url|inline|configMapRef, format auto|hosts|domains|adblock|regex, refresh, etag, digest, ruleCount, invalid, enabled}
BlockList  {name, mode block|allow, sources[], response override}            # blocky "group list"
ClientGroup{name, clients[ip|cidr|mac|clientID|hostname|nameGlob]{name,comment}, sources{integrationRef}}
Policy     {name, clientGroupRefs[], blockListRefs[], allowListRefs[], allowOnly, schedule, upstreamGroup, blockMode, blockTTL, queryLog, priority, rewrites[], safeSearch, safeSearchMode, blockedServices[], blockedCategories[], allowedServices[]}

Defaults: ClientGroup/default (matches everything), Policy/default. Pi-hole users map 1:1: Groups → ClientGroup + Policy, Lists → BlockList, Domains (exact/regex allow/deny) → an inline BlockList source, Clients → ClientGroup.clients. Blocked-services and safe-search data come from a kudurru-authored, Apache-2.0 catalogue embedded in the binary with per-entry provenance (AdGuard's tables are GPL) [blocking §6.6]; blocking.catalogue.url can replace it at runtime. It shipped in the v0.1 fix round instead of M2 (D60, D120, contract in docs/deploy/blocked-services.md).

7.3 Blocking engine design (performance is a named risk, §14)

Per BlockList, compile sources into a chain of three matchers, cheapest first; the exact-set layout, the cheapest-first chain and matched-rule reporting are borrowed from blocky (Apache-2.0, NOTICE) [blocking §2.5]:

1. Exact set: lower-cased entries bucketed by length, each bucket one sorted concatenated string, binary search, zero allocation.
2. Suffix set for ||domain^, *.domain and hosts-style entries with subdomain semantics: TLD-bucketed sorted sets plus a maphash bit filter and a fence index, walking parent labels broadest-first and returning the matched rule. This is kudurru's own design (blocky v0.35 uses a trie, D73); one process-wide maphash seed serves every list's filter. It fixes blocky's reduction of ||domain^ to exact match [blocking §8.2].
3. Regex scan indexed by a 4-byte piece of each expression's required literal (1,000 indexed regexes cost ~140 ns per miss); expressions with no such literal are scanned linearly (~25-75 ns each); warning above 50 unindexed regexes, hard cap 1,000 per list (CompileOptions.RegexHardCap, D73).
4. (v0.2) Modifier slow path: rules with $important, $badfilter, $dnstype, $dnsrewrite, $client, $ctag, $denyallow, mid-pattern wildcards: 5-byte shortcut index → candidate verify (urlfilter's idea re-implemented, never imported). Unknown modifier → rule ignored and counted in status.invalid, so browser lists are safe. v0.1 parses the whole grammar, compiles pure ||x^/@@||x^/hosts/domains/regex into matchers 1-3 and counts the rest as "unsupported in this version".

Compiled sets live in an atomic.Pointer[Snapshot] swapped copy-on-write per refresh; refresh is skipped when the CRC-32 of normalised rule lines is unchanged (AdGuard Home) [blocking §3.3]. The list pipeline is blocky's: ETag/Last-Modified conditional GET, sha256(url) disk cache with stale-on-unreachable, tee-to-temp + atomic rename, retry/cooldown, maxErrorsPerSource, keep-old-group-on-failure, bounded concurrency, init strategies with disk seeding, HTML/binary detection, ! Title: extraction, maxHTTPSize [blocking §2.6, §6.3].

Fetch once, serve everywhere (v0.1): the leader's listfetcher downloads, writes lists/<sha256(url)>, and publishes BlockList.status.sources[].digest; replicas pull GET :8082/internal/lists/<digest> from the leader (found via the Lease holder → EndpointSlice), verify the hash and compile locally; fall back to the disk cache, then to independent fetching, after 10 min without a reachable leader [k8s §16.11]. Compilation is node-local (CPU is cheap; a binary snapshot format would be another thing to version).

Match reporting: Contains(name) → map[list]rule so the query log explains "blocked by oisd: ||ads.example^", while Prometheus labels carry only list names.

Performance gate in CI (make bench): 1 M-entry suffix set, p99 lookup < 2 µs single-threaded, < 150 MB RSS for 3 M entries (steady state after GC in a fresh process; peak during a copy-on-write rebuild is tracked separately and needs roughly old + new + one list in flight), compile < 5 s; a +20 % regression against a committed, runner-class-specific baseline fails the build, each sample in its own process. Measured in the spike (docs/spikes/blocking.md): p99 1.18 µs hit / 0.71 µs miss at 1 M, 90 MB steady RSS (138 MB peak) at 3 M, 0.84 s compile, zero allocations per lookup. List semantics pinned there: @@ exceptions apply to their own list by default (a selection scope gives the merged behaviour); *.x also matches x; ||x is read as ||x^; hosts lines pointing at addresses other than 0.0.0.0/::/127/8/::1 are rewrites and counted unsupported; localhost boilerplate is ignored; bare IPs are matched against answer addresses. No published numbers exist for blocky/AGH [blocking §5.1], so kudurru publishes its own; a conformance corpus (OISD, Hagezi, StevenBlack samples) with expected block/allow decisions is cross-checked black-box against an AdGuard Home container (no code copied).

8. Auth: OIDC flows, RBAC, tokens, bootstrap

8.1 Principals and identities

Principal = User | ServiceAccount | KubernetesServiceAccount | LocalRoot (unix socket) | Node (internal token / mTLS peer); Node principals hold implicit viewer + auditor. The stored identities are internal kinds (LocalUser, APIToken, ServiceAccount, RoleBinding, IdentityProvider) in api/internalkinds/v1alpha1 (Go's internal-package rule forbids api/internal, D100): Secrets in the release namespace in Kubernetes, JSON rows in state.db in Docker, never CRDs. Identity key for OIDC users is (provider, iss, sub) — never email; email is trusted only when email_verified [auth §2.7, §10.4]. A User has zero or more identities (local password, OIDC) and local or IdP-managed group memberships.

8.2 Web login (BFF, authorization code + PKCE) and sessions

GET  /api/v1/auth/oidc/{idp}/start?next=/zones   → pre-auth cookie {state, nonce, verifier, next} (sealed, 10 min) → 302 IdP (S256, nonce)
GET  /api/v1/auth/oidc/{idp}/callback?code&state → exchange (confidential client) → verify id_token (go-oidc, JWKS cache) → nonce
                                                 → claimValidationRules → claimMappings → provisioning policy → bindings
                                                 → Set-Cookie kudurru_session (sealed, HttpOnly, Secure, SameSite=Lax) → 302 next (same-origin only)
GET  /api/v1/auth/me                              → principal, effective bindings, permission matrix, csrf token
POST /api/v1/auth/password                        → {currentPassword,newPassword} (local users); revokes every earlier session, sets a fresh cookie
GET  /api/v1/auth/status                          → {localLogin, localLoginMode, providers, hasDefaultCredentials, session}
POST /api/v1/auth/logout                          → clear cookie; RP-initiated logout via end_session_endpoint when present (v0.2)

Session = sealed cookie (AES-256-GCM, cluster-shared KUDURRU_ENCRYPTION_KEY / kudurru.io/session-key Secret) with payload {sid, principal, roles_snapshot, idp, iat, exp, idle_exp, csrf} (roles_snapshot = the resolved bindings, never the raw IdP group list, so a user with hundreds of groups cannot hit the 4 KiB guard and be unable to log in) re-sealed on each request to slide the idle timeout (30 m) under an absolute lifetime (12 h); 4 KiB guard with a hard error; no refresh token in the cookie. This is why any replica can serve any session in a Kubernetes Deployment with no shared DB. Revocation: User.status.sessionsValidAfter (set on password change, admin "kill sessions", disable) is checked per request from the store snapshot. Behind a SessionStore interface: sealed (v0.1 both modes) and db (v0.2 Docker; k8s only with an external store, v1.0) which adds session listing/killing and hourly IdP group re-evaluation via an encrypted refresh token — the auth research's preferred model [auth §4.1], accepted as the v0.1 trade-off because the kube driver has no relational store.

Implementation notes from the auth spike (D71): keys are derived per purpose as HKDF-SHA256(KUDURRU_ENCRYPTION_KEY, info=kudurru/<purpose>/v1) with purposes session and oidc-preauth, and every envelope carries a 4-byte key id so the _PREVIOUS key (D57) opens old cookies; roles_snapshot holds grants as role or role@kind:name, resolved at login and frozen until the next login, so deleting or narrowing a RoleBinding must bump sessionsValidAfter for its subjects (M3); the session cookie takes the __Host- prefix when Secure; the pre-auth cookie is single-use and path-scoped; discovery is lazy and a failing IdP yields idp_unavailable; logout clears the browser copy only. A user with 200 IdP groups seals to 546 bytes (raw groups would be 9,210 bytes), 68 zone-scoped grants fit under the 4 KiB guard. Entra-style group-overage claims are refused with an explanation instead of being read as "no groups"; IdP usernames are prefixed <idp>: by default so they can never match User bindings meant for local accounts; defaultRole may never be admin. go-oidc verifies neither nonce, azp nor at_hash and does not fetch distributed claims, so kudurru does the nonce and audience checks itself.

CSRF: Go 1.25 http.CrossOriginProtection on mutating routes + X-Kudurru-CSRF header required for cookie-authenticated writes + SameSite=Lax; bearer requests exempt [auth §4.1]. Security headers: CSP default-src 'self', X-Frame-Options: DENY, nosniff, HSTS when TLS terminates in kudurru. Multiple providers in auth.identityProviders[] / IdentityProvider objects; login page lists them; ?local=1 is break-glass.

// internal/auth/session.go
type SessionStore interface {
    Issue(ctx context.Context, s Session) (cookieValue string, err error)      // sealed: encrypt; db: insert row, return random id
    Load(ctx context.Context, cookieValue string) (Session, error)              // verifies seal/row, idle+absolute expiry, sessionsValidAfter
    Touch(ctx context.Context, s *Session) (cookieValue string, changed bool, err error)   // slides idle_exp; sealed re-seals at most once per minute
    Revoke(ctx context.Context, sid string) error                               // db only; sealed returns ErrUnsupported (use sessionsValidAfter)
    List(ctx context.Context, principal string) ([]SessionInfo, error)         // db only
}

8.3 CLI login

• v0.1: kudurru login --server https://dns.example --token kdr_… or --username/--password (local admin); credentials in the OS keyring (zalando/go-keyring) with a 0600 file fallback; --context picks a kubeconfig for CRD verbs.
• v0.2: kudurru login opens the browser for loopback + PKCE (ports 8000/18000, public client kudurru-cli), --device for RFC 8628 (prints user code and client name per RFC 10027); the CLI sends the IdP ID token as bearer; the server routes by iss, verifies against JWKS, requires aud to contain cliClientID (or clientID) and, when aud has several values, azp to equal one of them, rejects access tokens and tokens minted for other relying parties (otherwise any ID token the IdP issued for an unrelated app could be replayed against kudurru), caches the verdict by sha256(token) until min(exp, 15 m) (dex issues 24 h ID tokens by default), re-runs claim mapping per call [auth §4.2].

8.4 Claims → identity → bindings

Three Kubernetes-shaped layers [auth §4.3]: claimValidationRules ({claim, requiredValue}; v0.2 CEL expression), claimMappings (username{claim,prefix} with fallback preferred_username → upn → email → sub, groups{claim,prefix} tolerant of string-or-array and also reading roles, displayName, email), then authorization via bindings on the prefixed remote group (corp:/dns-admins) or a groupMap. provisioning: { autoProvision: always|mapped-only|never, syncGroups: bool, defaultRole: "" } — strict by default: a login yielding zero bindings is refused with a clear message (Grafana role_attribute_strict); never silently admin (Gravity's mistake) [auth §10.1].

8.5 RBAC model and permission matrix

Hand-rolled (subject, role, scope) bindings behind an Authorizer interface (Casbin/SAR pluggable) [auth §5]:

// internal/rbac/authorizer.go
type Attributes struct{ Resource, Verb string; Scope Scope /* {Kind cluster|zone|zonegroup|clientgroup, Name} */; Namespace, Name string }
type Decision struct{ Allowed bool; Path string /* binding | sar | local | none */; Missing *Attributes; Reason string }
type Authorizer interface {
    Authorize(ctx context.Context, p Principal, a Attributes) (Decision, error)   // pure for the binding authorizer; SAR authorizer caches ≤ 2 min by (token hash, attributes)
}
type Chain []Authorizer   // first Allowed wins (§5.5 precedence); Decision.Path is what the audit row records

Every route declares {resource, verb, scopeFromPath}; a lint fails the build if a route has no declaration. internal/rbac/permissions.yaml is the single source that generates the built-in roles, the aggregated ClusterRoles in the chart, the docs table below and the lint fixtures.

Resources × verbs (read|write|delete + extras): zones{transfer,sign,share}, records, blocklists{refresh}, policies, clientgroups, clients, querylog{export,purge}, stats, cache{flush}, blocking{toggle}, settings, node{config}, users, groups, serviceaccounts, tokens, identityproviders, rolebindings, integrations{sync,check,secrets,act}, cluster{join,promote,drain}, edge, audit{export}.

Scopes: cluster, zone:<name>, zonegroup:<label> (v0.2), clientgroup:<name> (v1.0, so a group owner sees only their clients' queries). The creator of a zone receives zone-admin on it (Technitium's initial grant) [auth §9.1]. Evaluation is a pure function with table tests; zone listing filters by scope. 403 responses carry missing:{resource,verb,scope} so the UI can explain. Kubernetes mapping: viewer ≡ kudurru-viewer, operator ≡ kudurru-editor, admin ≡ kudurru-admin, auditor ≡ kudurru-auditor; zone-admin ≡ a namespaced RoleBinding plus resourceNames on dnszones.

apiVersion: kudurru.io/v1alpha1
kind: RoleBinding
metadata: { name: platform-zone-admins, namespace: dns }
spec:
  role: zone-admin
  scope: { kind: zone, name: home-example-com }
  subjects:
  - { kind: Group, name: "corp:/dns-admins" }
  - { kind: ServiceAccount, name: external-dns, namespace: kube-system }   # k8s SA via projected token

8.6 API tokens and service accounts

Grafana-style service accounts owning N tokens; wire format kdr_<12-char id>_<43-char secret>; store sha256(secret) only; constant-time compare on the full hash, never prefix lookups (Technitium v15.6 oracle); unknown id and wrong secret return the same 401; optional expiry (auth.tokens.maxLifetime), lastUsedAt/IP, revocation, audit [auth §4.5]. Personal tokens inherit the owner's bindings ∩ optional scopes and die with the user. Integration credentials (Cloudflare token, UniFi key, dnsdist API key) are outbound secrets, not principals: secretRef/file/env only; fingerprints in status.

8.7 Local accounts, bootstrap, recovery

• First start with no users: admin from KUDURRU_ADMIN_PASSWORD[_FILE] else generated and printed once; mustChangePassword=true; hasDefaultCredentials in GET /auth/status so the UI nags [auth §4.4].
• KUDURRU_BOOTSTRAP_TOKEN[_FILE] creates a bootstrap service-account token (Helm post-install jobs, Terraform) — hash only at rest.
• Argon2id (m=19 MiB, t=2, p=1, PHC string), 1 KiB password cap, global hashing semaphore; per-IP (5 failures → 5 min) and per-user (10 → 15 min) limiters with 429 Retry-After, dummy hash for unknown users, sanitised usernames in logs [auth §7].
• localLogin: enabled|admins-only|disabled; /login?local=1 break-glass; kudurru admin reset-password|create-token|list-users over auth.adminSocket.path (default /run/kudurru/kudurru.sock) (SO_PEERCRED uid 0, or the uid the server itself runs as — 65532 in the distroless image, which is what docker exec/kubectl exec get without --user — or a configured gid) for docker exec/kubectl exec.
• TOTP (v0.2) with one attempt per second and last-counter replay protection.

8.8 Middleware order

Recover → RequestID → RealIP(trustedProxies) → SecurityHeaders → AccessLog → CrossOriginProtection → RateLimit(auth routes) → Authenticate(bearer kdr_ | bearer JWT by iss | k8s SA token | cookie+CSRF | unix peer | internal token) → LoadPrincipal(disabled? mustChange? sessionsValidAfter?) → Authorize(resource, verb, scope; SAR for k8s identities) → Handler → Audit(outcome, before/after, authz path).

9. Integration model

9.1 Tiers

Tier B wire shape (v0.2 client side; the server side of the four external-dns routes is v0.1, §5.6): GET / returns {filters:[...], capabilities:[records|clients|hooks|actions], manifest:{...}} when the kudurru media type is accepted; GET /clients → [Client], GET /networks → [Network] (the ClientSource shapes of §9.2); POST /events ← Event with X-Kudurru-Signature: sha256=<HMAC of body with the integration's secret> and X-Kudurru-Delivery id (2xx acknowledges, 5xx retries with backoff + dead-letter after 24 h, 4xx drops and raises Degraded); GET /actions → [ActionSpec{name, params JSON Schema, rbac verb}], POST /actions/{name} ← params [integrations §5.5].

No runtime-loaded in-process code, ever (Technitium's privilege-escalation path) [integrations §7.1, technitium §21.4].

9.2 Interfaces (internal/integration)

type Manifest struct {
    Type, DisplayName, Version string
    Capabilities []Capability      // RecordSink | ClientSource | Hook | Actions
    IOClass      string            // cloud_polling | local_polling | local_push
    ConfigSchema json.RawMessage   // JSON Schema; also becomes the Integration CRD one-of block and the UI form
    SecretKeys   []SecretKey       // which spec fields are secret refs + how to verify them
    Docs         string
}
type Integration interface {
    Manifest() Manifest
    Provision(ctx context.Context, host Host, spec json.RawMessage, secrets SecretResolver) error // strict unmarshal
    Validate(ctx context.Context) error              // offline
    Check(ctx context.Context) (Status, error)       // network: auth + reachability (token verify, /v1/info)
    Start(ctx context.Context) error                 // runs until cancelled; leader-scoped
    Stop(ctx context.Context) error
}
type RecordSink interface {                          // outbound; Endpoint/Changes are external-dns wire shapes
    DomainFilter() DomainFilter
    Records(ctx context.Context, zone string) ([]Endpoint, error)
    AdjustEndpoints(ctx context.Context, eps []Endpoint) ([]Endpoint, error)
    ApplyChanges(ctx context.Context, zone string, ch Changes) (ApplyResult, error)   // returns provider IDs for the ledger
}
type ClientSource interface {                        // inbound inventory
    ListClients(ctx context.Context) ([]Client, error)     // {ID, MACs, IPs, Name, Hostname, Network{Name,VLAN,CIDR,Domain}, FixedIP, Tags, LastSeen, Attributes}
    ListNetworks(ctx context.Context) ([]Network, error)
}
type Hook interface { Topics() []string; Handle(ctx context.Context, ev Event) error }   // at-least-once; host retries + dead-letter
type ActionProvider interface { Actions() []ActionSpec; Invoke(ctx context.Context, name string, params json.RawMessage) (json.RawMessage, error) }
type Host interface {                                // what the host lends an integration
    Zones() ZoneReader; Inventory() InventoryWriter; Ledger(name string) Ledger; Events() EventBus
    Logger() *slog.Logger; Metrics() prometheus.Registerer; Status() StatusWriter; Clock() clock.Clock
    Resolve(ctx context.Context, q dns.Question) (*dns.Msg, error)   // re-enter the pipeline (Technitium DirectQuery)
}
func Register(m Manifest, ctor func() Integration)   // panics on duplicate type

Host-owned, not per-integration: polling cadence, jitter, backoff, soft/hard error classification (429/5xx/EOF → requeue honouring Retry-After), rate budgets, dry-run preview, status conditions Ready/Authenticated/Synced/Degraded, secret-rotation re-provisioning (file watch / Secret informer), the plan engine (per-(dnsName,setIdentifier) table grouped by type, CNAME exclusivity, owner mismatch → skip + Conflict, policies sync|upsert-only|create-only; ~400 lines re-implemented with a conformance test against external-dns plan_test.go cases) and the ledger ((integration, zone, name, type) → {providerIDs[], contentHash, generation, lastApplied} as an internal kind) [integrations §5.2, §5.4].

Lifecycle events (the hook Technitium lacks): zone.changed{zone, serial, delta}, record.changed, client.seen|left, query.blocked (sampled), blocking.toggled, integration.error, cluster.leader_changed, vip.master_changed. Debounced 2-5 s; every sink also has a periodic full resync (default 10 m) and a manual "sync now" [integrations §7.9].

9.3 Declaring integrations: one schema, two carriers

# Docker: kudurru.yaml → objects[] or objects.d/           # Kubernetes: kind Integration (v0.2)
apiVersion: kudurru.io/v1alpha1
kind: Integration
metadata: { name: cf-public, namespace: dns }
spec:
  type: cloudflare
  credentials: { apiToken: { secretRef: { name: cloudflare-token, key: token } } }   # Docker: { file: /run/secrets/cf_token }; never inline
  cloudflare:
    zones:
    - zone: example.com
      zoneID: 023e105f4ecef8ad9ca31a8372d0c353          # optional; resolved via Zone:Read
      select: { labels: { kudurru.io/publish: cloudflare }, types: [A, AAAA, CNAME, TXT, MX, SRV, CAA], exclude: ["*.internal.example.com"] }
      defaults: { proxied: false, ttl: 1, comment: "kudurru:owner=home" }
      policy: sync                                      # sync | upsert-only | create-only
      adoptFrom: { externalDNSOwner: k8s-home }         # read heritage=external-dns TXT records and adopt
      adoptUnowned: false
    deletionPolicy: Retain
  resync: 10m
  suspend: false
status:
  conditions:
  - { type: Authenticated, status: "True", reason: TokenVerified }
  - { type: Synced, status: "False", reason: RateLimited, message: "429 retry-after 37s" }
  - { type: Ready, status: "True", reason: Running }
  lastSyncTime: "2026-10-10T21:03:11Z"
  records: { managed: 42, drift: 1, conflicts: 0 }
  provider: { rateLimitRemaining: 1150, sdk: cloudflare-go v7.12.0 }

CEL: has(self.cloudflare) == (self.type == 'cloudflare'). Spec never contains secret values; status shows fingerprints only. RBAC verbs: integrations.read|write|secrets|act.

9.4 Worked example 1 — Cloudflare split-horizon (v0.2)

Problem: example.com is authoritative inside (RFC 1918 answers) and public at Cloudflare; a subset (public hosts, ACME TXT, MX/SPF) must exist publicly, some proxied, without a second hand-maintained zone [integrations §2.5].

1. One zone, one truth. Records opt in with label kudurru.io/publish: cloudflare and/or DNSZone.spec.publish[] rules (selector + name glob + types).
2. Per-sink overrides and views. providerSpecific: [{cloudflare/targets: "203.0.113.10"}, {cloudflare/proxied: "true"}] publishes a different value than is served internally; an endpoint with kudurru.view: public is only published, never served (e.g. the tunnel CNAME in §4.1). Sink-level translate: {"203.0.113.0/24": "10.0.0.0/24"} offers Technitium-style 1:1 NAT for bulk cases. Proxied records force ttl: 1; only A/AAAA/CNAME are proxiable; proxied public answers are never mirrored inward.
3. Ownership. Internal ledger + Cloudflare comment: kudurru:owner=<clusterID> (works on Free) + tag kudurru-owner:<id> when the plan allows; external-dns heritage= TXT records are read for adoptFrom migrations, never written. Unowned records are never modified unless adoptUnowned: true; foreign-owned → Conflict + skip.
4. Reconcile (leader, level-triggered). desired = select(zone) ▷ overrides/views ▷ AdjustEndpoints; current = GET /zones/{id}/dns_records?per_page=5000[&comment.startswith=kudurru:] cached per resync; plan; apply via POST /zones/{id}/dns_records/batch in 200-op chunks (deletes → patches → puts → posts), 1 s between chunks, per-record fallback on chunk failure; a shared token bucket budgeted at 1,000 of the 1,200 requests / 5 min per user limit (cumulative across dashboard, keys and tokens of that user; exceeding it blocks all calls for 5 min [integrations §2.1]) across every Cloudflare sink whose token belongs to the same user; 429/5xx → requeue with Retry-After; status Synced, records{managed,drift,conflicts}, rateLimitRemaining.
5. Token. GET /user/tokens/verify + GET /zones?name= at Check(); documented scope Zone:Read + DNS:Edit restricted to the zone; cloudflare-go/v7 pinned exactly and wrapped thinly.
6. Status. DNSZone.status.published[] and DNSRecordSet.status.publications[]{integration, state Accepted|Programmed|Failed} (external-dns DNSRecord idiom) so kubectl get rrset shows whether Cloudflare is in sync; kudurru integrations preview cf-public prints the dry-run plan.

9.5 Worked example 2 — UniFi Network (v0.2)

Inbound ClientSource (polling, official Integration API X-API-Key at /proxy/network/integration/v1: sites, clients, networks, DNS policies with offset/limit paging) via unpoller/unifi/v6 (read-only library [integrations §3.4]); legacy /rest/user, /stat/sta, /v2/api/site/<site>/active-leases only for alias/hostname/fixed-IP/VLAN/leases, behind version detection (GET /v1/info) and per-endpoint 404 tolerance [integrations §3]. The optional push paths below need writes that unpoller does not provide: a thin in-house client (≈ 200 lines, X-API-Key) over the official PUT /v1/sites/{site}/networks/{id} and POST|PUT /v1/sites/{site}/dns/policies endpoints, and the legacy cmd/stamgr for block/unblock behind the same legacy flag; filipowm/go-unifi (MPL-2.0) is acceptable as an unmodified dependency if the in-house client grows.

apiVersion: kudurru.io/v1alpha1
kind: Integration
metadata: { name: unifi-home, namespace: dns }
spec:
  type: unifi
  credentials: { apiKey: { secretRef: { name: unifi-key, key: apiKey } } }      # Docker: { file: /run/secrets/unifi_key }
  unifi:
    endpoint: https://192.168.1.1
    tlsFingerprint: "sha256:…"                        # instead of insecureSkipVerify
    site: default
    poll: 60s
    inventory: { zoneRef: { name: lan-example-com }, reverseZones: auto, nameTemplate: "{{ .Alias | default .Hostname | slug }}", ttl: 120, includeNetworks: [LAN, IoT, Kids] }
    groups: { byNetwork: { IoT: iot, Kids: kids, Guest: guest }, byNote: "kudurru:group=" }
    push: { dhcpDNSServers: false, mirrorRecords: { enabled: false, types: [A, CNAME] } }