Skip to content

design

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

design

README.md

dns-api Design

docs/design/ is the source of truth for the current dns-api design. Proposal history and temporary notes do not live here. Downstream implementation and user documentation should follow the committed files in this directory.

Documents

  • Overview: project scope, initial provider scope, resource model, and condition scope.
  • Common Design: roles, DEP process, namespace boundaries, descriptions, license, manual reconcile, and adoption.
  • Core API: ZoneClass, Zone, RecordSet, ZoneUnit, statuses, conditions, and events.
  • Provider Extension: Provider contract, schemas, validation, support levels, and provider data.
  • Controllers and Webhooks: controller responsibilities, modules, acceptance boundary, and admission webhook.
  • Cloudflare Provider: Cloudflare identity, schema, ZoneClass parameters, provider data, reconciliation, deletion, and record mapping.
  • Route 53 Provider: Route 53 identity, provider settings, and record-set provider schema.
  • External Provider: verify-only provider for customer-managed DNS: resolver policy, exact-set verification, conditions, scheduling bounds, deletion semantics, and conversion decision.
  • Hosted Provider: authoritative provider that renders ZoneUnit into HostedZone snapshots served by dns-api's own DNS server; credentialless, withdrawal-capable, no external DNS API.
  • Gateway API Integration: HTTPRoute / Gateway DNS report, Zone selection, and generated RecordSet behavior.
  • UI: reusable DNS API UI package, screens, workflows, components, and mockup design.
  • Headlamp Desktop Plugin: Headlamp Desktop plugin package, distribution, and Desktop-specific behavior.
  • Development Environment: devbox, Taskfile, kind / Tilt, local credentials, and CI setup.
  • Test Policy: kest, envtest, conformance scope, and initial scenario requirements.
  • Open Decisions: unresolved design decisions.

Source Rules

  • Current behavior is described in present tense in these files.
  • One-off proposals, pseudocode, resolved feedback, and obsolete manuals are not source of truth.
  • API changes that need history or alternatives belong in deps/ as DEP documents, then accepted behavior is reflected back here.