Skip to content

Internal DNS and Cutover Contract

Purpose: Define the contract between internal DNS authority, service endpoint publication, and DNS cutover automation.

1. Scope

This contract defines:

  • where internal service DNS records should live
  • how service modules publish endpoint intent
  • how cutover automation should update records

It does not define:

  • the public internet DNS model
  • specific provider forwarding-zone implementation details

2. Roles

2.1 Internal DNS authority

The internal DNS authority MUST:

  • host the authoritative internal zone
  • accept API-driven updates
  • live outside the primary on-prem failure domain

Current preferred implementation:

  • PowerDNS Authoritative

Current preferred topology:

  • writable primary on a dedicated Hetzner shared control-plane host
  • read-only secondary on-prem
  • optional additional secondary later in a cloud control plane

2.2 Endpoint publishers

Service modules and DR blueprints MUST publish:

  • the intended stable endpoint name
  • the resolved current target
  • whether cutover is required

2.3 DNS cutover automation

DNS cutover automation MUST:

  • consume the published endpoint contract
  • update the internal DNS authority
  • record evidence of the intended and applied target

3. Required endpoint fields

At minimum, the endpoint publication SHOULD contain:

  • endpoint_dns_name
  • endpoint_target
  • endpoint_target_type
  • endpoint_port
  • endpoint_cutover_required

4. Naming rule

Internal service clients SHOULD use DNS names following the shared zone pattern:

  • <service>.<env>.hyops.internal
  • <service>.shared.hyops.internal

Examples:

  • postgres.dev.hyops.internal
  • postgres.prod.hyops.internal
  • netbox.shared.hyops.internal

5. Cutover behavior

Failover and failback workflows SHOULD follow this sequence:

  1. restore or promote the data/platform target
  2. validate readiness
  3. update the internal DNS record
  4. allow applications to reconnect using the stable DNS name

Workflows MUST NOT expect applications to retarget raw IPs manually.

DNS cutover automation MUST update the writable shared authority, not the on-prem secondary.

6. Source-of-truth boundary

Infrastructure metadata systems such as NetBox MAY provide:

  • IPAM
  • ownership
  • intended endpoint metadata

They MUST NOT be assumed to be the authoritative DNS engine unless explicitly implemented as such.

7. Tarball safety

HybridOps MUST remain tarball-safe:

  • contracts and automation logic ship in the product
  • operators may deploy the shared internal DNS authority separately
  • runtime DNS authority state must not depend on a docs website or ad hoc workstation scripts

8. Current HybridOps direction

The first clean HybridOps direction is:

  1. Cloudflare for public DNS
  2. PowerDNS primary on a dedicated Hetzner shared control-plane host
  3. PowerDNS secondary on-prem for local resilience
  4. env-scoped service names under hyops.internal
  5. DNS cutover automation layered on top of published endpoint contracts