[jacaudi]

Summary

A per-object opt-out for the DNS handoff, plus the docs the operator survey called for. It lands before v1.10.0 is cut, so it ships in the same release as the handoff.

 Service / Gateway / HTTPRoute
+  metadata.annotations: towonel.io/dns-record: "false"     # present & not truthy → opt out (typos too, with a Warning)
 TowonelAgent.spec.services[]
+  dnsRecord: false                                        # new optional field; hand-written agents set it directly
 TowonelTunnel reconcile
   desiredDNSEndpoint(tt, view, edgeTargets
+                     , optOut)                            # any referencing agent opting a hostname out excludes it

• Fail closed. Only an absent annotation or a truthy value publishes. Anything else opts out, and an unrecognized value also raises InvalidAnnotation.
• Hub authorization unaffected. The hostname leaves only the DNSEndpoint and status.dnsRecords.
• Observe-only agents. An ObserveOnly agent that serves an opted-out hostname without dnsRecord: false gets a Warning, not silence.
• Docs (docs/dns.md):
  • Zone-apex hostnames. Apex CNAMEs depend on the provider; the remedy is the opt-out plus an ALIAS or A record.
  • Worked Recipe B. Reuse your existing public and LAN external-dns instances: audit first, label LAN-only objects and tunneled routes lan, then !=lan on the public instance and !=public on the LAN one. Gateways are filtered only by --gateway-label-filter (external-dns source/gateway.go:156-160).
  • k8s_gateway on the LAN.

Evidence

• Before: the annotation was reserved and ignored. TestDNSRecordAnnotationKeepsHostnameOutOfDNSEndpoint failed: endpoints = [extra private public], want [extra public].
  After: it passes, as does TestDNSRecordAnnotationRemovalRepublishesHostname (removing the annotation clears dnsRecord and republishes the hostname).
• Unit tests:
  • TestApplyDNSRecordAnnotation: absent, truthy, falsy, typo and empty values.
  • TestObserveUserAgentWarnsWhenDNSOptOutNotOnAgent.
  • TestDesiredDNSEndpointOptOut and TestDNSOptOutHostnames.
• Mutation checks by the reviewer: dropping the annotation call, the optOut filter, the fail-closed branch or the observe-only warning each makes a test fail.
• Full suite: task ci exits 0 (fmt, vet, -race tests with envtest, helm lint and template, verify-generated).

Merge Danger

Door: two-way. The field is additive and optional, and the annotation only removes records.

Blast Radius: DNS records

Raw-manifest installs must update the TowonelAgent CRD before relying on the annotation. A stale CRD that silently prunes dnsRecord leaves the hostname published.

🤖 Generated with Claude Code