dynapi demo

tl;dr

  • coredns/dynapi v0.1.0 is out, published on 2026-10-01.
  • It is an external CoreDNS plugin. Applications read, replace and delete A and AAAA record sets through a JSON HTTP API.
  • The idea started as coredns/coredns#1822. I opened that PR on 2018-05-20. It was closed on 2018-09-29, when the coredns/dynapi repository was created.
  • That repository stayed empty for eight years. The plugin in v0.1.0 is a new design, not a port of the old code.

Why I needed it

At SumUp we had what felt like an amazing idea: build our own take on ArgoCD. It was a Kubernetes-based deployment system for on-demand dev environments, and it ran on bare metal instances. It worked.

Every new environment needed DNS names, and it needed them fast. So we needed a DNS server that was reliable, simple to run and extensible. CoreDNS fit those three needs. One thing was missing: a way to register addresses dynamically. The obvious answer was an HTTP API, because any language and any tool can call one.

The 2018 story

PR #1822 was titled “[WIP] Dynamic updates API with listen server”. It was an experimental REST API. A POST request with an A record added it to a zone managed by the file plugin.

My use case was narrow:

  • CoreDNS is the main DNS server.
  • I add records through an API.
  • There is no database as a second source of truth. In-memory storage was good enough for me.

We ran it in production from a little before 20 May 2018. A small daemon read DHCP leases and sent them to CoreDNS to register A records. It worked well, with one catch. Records created without a TTL got the default of 3600 seconds. That is far too long for short-lived environments, so the create and update requests got a TTL field.

The maintainers had a fair question. Miek Gieben asked why CoreDNS should provision records at all. Access control, users and permissions grow out of every API like this. The advice was to build it as an external plugin and put it at coredns/dynapi. John Belamaric suggested a different split: a Go “Writable” interface that plugins can implement, and separate plugins for the write protocols (DDNS, HTTPS, gRPC).

The same request was already open in #522 (“provide an API to manage host records”, 2017). In 2020 John Belamaric listed what a proper solution needs: a “writable” interface for backends, a plugin that exposes the REST API, and authentication that works across API plugins. #2073 asked for the same thing from the Ansible side, and #2517 was closed as unsupported, although a maintainer later said DNS UPDATE is “hard to do right, but I’m not against it”.

The repository was created in September 2018 and the PR was closed. Then my part stalled. COVID happened, I am bad at GitHub notifications, and I decided nobody needed the project. I never moved the code.

I was wrong about the last part. For years, people kept asking in the closed PR. Some found the empty repository. Some asked why CoreDNS has no REST API. Some discussed which record types to support and whether Envoy’s xDS is a better model.

On 2026-10-01, out of nowhere, I checked again and saw the idea was still relevant. And here we are.

What v0.1.0 does

dynapi runs inside CoreDNS and opens its own HTTP listener. The default address is 127.0.0.1:8080, and only loopback addresses are allowed.

There is one URL shape:

/v1/zones/{zone}/records/{name}/{type}

The type is A or AAAA. Names must be full names inside the configured zone.

  • GET returns the exact stored set, for example {"ttl":60,"addresses":["192.0.2.10"]}.
  • PUT replaces the whole set in one atomic step.
  • DELETE removes the set and returns 204, also when the set does not exist.

PUT is strict. It needs Content-Type: application/json, an explicit TTL from 0 to 2147483647, and 1 to 256 addresses of the right family. Duplicate addresses are removed. Bodies are limited to 64 KiB. Unknown fields and duplicate keys are rejected. The OpenAPI specification is generated from the Go models, and make verify checks that it is current.

curl -X PUT http://127.0.0.1:8080/v1/zones/example.org/records/host.example.org/A \
  -H "Authorization: Bearer $DYNAPI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ttl":60,"addresses":["192.0.2.10","192.0.2.11"]}'

dynupdate: the proposal I found while I was away

In 2018 CoreDNS had no way to change records at runtime, and I wrote my own. In 2026, an upstream proposal is trying to fill that gap. The dynupdate proposal in PR #8520 is still open as of this article. It is not part of a released CoreDNS version. The proposal adds an RFC 2136 writable zone, authenticated with TSIG, and describes interoperability with nsupdate and DHCP software such as Kea.

The proposal follows #6254 (“Support DDNS”, opened in 2023) and builds on two earlier changes: #8469 lets the server accept UPDATE messages, and #8471 exposes validated TSIG identity to plugins.

The proposal works like this:

  • One writable zone per server block. You give it a seed zone file. The plugin never modifies that file.
  • Persistence is optional. With database, every update goes to an embedded bbolt file before the new snapshot is visible and before the client sees success. Without it, updates live in memory and a restart loses them. The first access creates the database from the seed. After that, the database is the source of truth.
  • Authentication is TSIG. The tsig plugin validates the signature. dynupdate never sees the secret.
  • Authorization is explicit. Every change must match an allow KEY NAME TYPE rule. Nothing is allowed by default.
  • In the proposal, RFC 2136 prerequisites and updates are checked and applied atomically. It also describes CNAME and apex SOA/NS rules, SOA serial updates, AXFR of the current snapshot, and best-effort NOTIFY.
  • Caching is handled. The cache plugin bypasses dynamic zones, so authoritative answers are always current.
  • The proposed zone implementation is experimental and scoped to small, infrequently updated zones. It does not include IXFR history or multi-primary replication.

That scope fits my use case. If the proposal is accepted, CoreDNS would provide the write permissions and persistence layer, leaving the HTTP plugin thin.

How it works

The v0.1.0 development build uses no record store in dynapi. It sends signed DNS requests over pooled loopback TCP to a CoreDNS build that includes the proposed dynupdate implementation.

  • GET is a signed AXFR (zone transfer).
  • PUT and DELETE are DNS UPDATE transactions.
  • The proposed dynupdate plugin owns the zone database, persistence, atomic updates, and write permissions. It is supplied by the CoreDNS change under review, not by a released CoreDNS build.
  • tsig authenticates the DNS requests.
  • transfer allows the AXFR.

There are two separate credentials. HTTP clients use a bearer token of at least 32 characters. It permits reads across the whole zone. The DNS side uses a TSIG key (HMAC-SHA256), and dynupdate allow rules limit what that key can write.

In the code, a PUT becomes one DNS UPDATE message:

  1. A prerequisite asserts that no CNAME exists at the name. RFC 2136 would silently ignore an add next to a CNAME, so this check keeps the HTTP response honest.
  2. The first update deletes the whole record set of that type.
  3. The next updates add the new addresses with the requested TTL.

The server applies all of it as one transaction, so readers never see a half-replaced set. DELETE is the same message without the prerequisite and the adds. GET sends a signed AXFR and scans the transfer for the one name and type. The pool reuses TCP connections, and a connection that failed or was cancelled is discarded.

dynupdate answers are mapped to HTTP status codes. A failed prerequisite is 409, a refused update is 403, and any other rejection is 502.

This Corefile is for the development build described above. It depends on the dynupdate proposal and is not expected to work with an unmodified CoreDNS release:

example.org:1053 {
    bind 127.0.0.1

    dynapi 127.0.0.1:8080 {
        token_env DYNAPI_TOKEN
        upstream 127.0.0.1:1053
        identity update-key.example.org.
        secret_env DYNAPI_TSIG_SECRET
    }

    tsig {
        secret update-key.example.org. {$DYNAPI_TSIG_SECRET}
        require_opcode UPDATE
        require AXFR
    }

    transfer {
        to 127.0.0.1
    }

    dynupdate {
        file example.org.zone
        database example.org.db
        allow update-key.example.org. host.example.org. A AAAA
    }
}

Why signed DNS and not a record store

This design keeps the HTTP plugin from owning a second record store. In the development build, dynupdate supplies zone storage and write permissions while tsig authenticates DNS requests. The upstream dynupdate implementation remains under review in PR #8520.

ADR 0001 records the decision and what it rejects:

  • Its own record store. It would duplicate persistence, permissions and authoritative DNS behavior.
  • Direct calls into dynupdate. That needs an upstream interface with defined transactions, permissions and lifecycle rules.
  • Normal DNS queries for reads. They can expand wildcards and follow CNAMEs, so they cannot return the exact stored set. AXFR can.
  • A web framework. Three HTTP operations do not need one, so dynapi uses net/http.

PUT also checks for a conflicting CNAME in the same transaction.

The design has costs. GET scans the whole zone. Connections come from a pool limited by max_requests, which defaults to 32. Writes are never retried, because a change may commit before the response is lost.

What is not done

  • Only A and AAAA records work. The 2018 thread asked for more types, and Miek wanted storage that does not care about record types. That is future work.
  • The development build needs Go 1.27 or newer and a pinned CoreDNS revision containing the proposed dynupdate plugin. This is why the v0.1.0 repository builds its own CoreDNS binary.
  • Corefile reloads are rejected. Restart CoreDNS to change the configuration.
  • Conditional writes (record revisions) are still open.

Next: 0.2.0

The loopback DNS bridge works, but it is a detour. An HTTP request turns into a signed DNS message, goes over TCP to the same process, gets parsed and verified, and only then reaches the zone. A GET transfers the whole zone to read one record set.

ADR 0002 proposes the fix for 0.2.0. dynapi would call the zone provider directly. That removes the TCP hop, the full-zone reads and the TSIG key from dynapi. It is also the “Writable” interface John Belamaric described in 2018.

I am not the first to ask. #7259 is an open proposal for a REST API plugin with a backend-agnostic api.Backend interface. Its author argues that the interface should live in the main CoreDNS project and that backends such as etcd should implement it. #7858 asks for a plugin that manages records through API or gRPC. Both point at the same gap.

The change in CoreDNS is needed first, because today plugins have no shared way to be written to:

  • A Go interface to read, replace and delete stored record sets, with explicit errors. It starts with exact A and AAAA sets.
  • Provider lookup by zone. CoreDNS would find the writable provider for a zone and manage its startup and shutdown.
  • A provider that implements it. The interface alone stores nothing. dynupdate can be the first one.
  • Clear rules for permissions, for when a write counts as durable, and for how cached answers are invalidated.
  • Reload behavior. A Corefile reload must replace providers without sending requests to a retired zone. This also fixes the “reloads are rejected” limit above.
  • Record revisions, so conditional writes can stop two clients from overwriting each other.

The HTTP API stays the same during the move. The signed DNS adapter from v0.1.0 stays until the interface exists. Whether the writable provider ships with CoreDNS or as an optional plugin is still an open question. The first step is to agree on the interface upstream in the CoreDNS repository, before dynapi changes.

Try it

make builds CoreDNS with dynapi, dynupdate and tsig. Run ./coredns -plugins to check that all three are in the binary.

To add dynapi to another CoreDNS build, put this line in plugin.cfg after acl:

dynapi:github.com/coredns/dynapi/plugins/dynapi

Then run:

go get github.com/coredns/dynapi/plugins/dynapi@v0.1.0
go generate coredns.go
go build -o coredns .

The examples/ directory has a starter Corefile and an annotated Go client.

Sorry to all the patient people waiting. :D Now we’ll follow normal OSS cadence. Any feedback, issues and PRs are welcome in the GitHub repo.