undocumented CNAME targets normalization (removing trailing dots)

[lukasmetzner]

What happened:

I am developing a webhook for external-dns. When creating a CNAME record via the annotation external-dns.alpha.kubernetes.io/target, the trailing dot is stripped from the value. In the external-dns code this is referred to as "Normalization".

I am unsure if this is the intended behavior and possibly needs some more documentation.

For my understanding: Is it a supported feature that only the prefix is used in external-dns.alpha.kubernetes.io/target?
For example, given:

external-dns.alpha.kubernetes.io/hostname: "foo.example.com"
external-dns.alpha.kubernetes.io/target: "bar"

the resulting DNS record would be a CNAME:

foo.example.com. -> bar.example.com.

What you expected to happen:

Either to receive the raw value in the Endpoint.Targets field, or have more documentation on this topic.

How to reproduce it (as minimally and precisely as possible):

1. Create a Service with the annotations external-dns.alpha.kubernetes.io/hostname: example.mydomain.de and external-dns.alpha.kubernetes.io/target: www.example.com.
2. When developing a webhook the value in the endpoint.Targets array will have the trailing dot in www.example.com. removed → www.example.com

Anything else we need to know?:

• Downstream issue in my webhook: trailing dot removed (tested for CNAMEs) hetzner/external-dns-hetzner-webhook#73
• Downstream PR (how I plan to fix this in my webhook): fix: CNAME resolution when External DNS strips trailing dots hetzner/external-dns-hetzner-webhook#77

Environment:

• External-DNS version (use external-dns --version): v0.20.0
• DNS provider: Hetzner
• Others:

[ivankatliarchuk]

You could try to dig and update documentation, absolutely make sense. My understanding

The trailing dot convention comes from the core DNS specifications (RFC 1035) (for domain name)

Trailing dot in DNS (RFC 1035):

• A trailing dot indicates a Fully Qualified Domain Name (FQDN) - an absolute name from the root
• example.com. = absolute, no search domains appended
• example.com = potentially relative, resolver may append search domains

CNAME related

RFC 1035 - Domain Names (Section 5.1, Zone File Format):

In DNS zone files, names are interpreted as:

• With trailing dot → Absolute/fully qualified (e.g., target.example.com.)
• Without trailing dot → Relative, the zone origin is appended (e.g., target becomes target.example.com.)

For CNAME targets specifically:

  ; Zone: example.com
  www   CNAME   other.example.com.   ; Correct - absolute name
  www   CNAME   other.example.com    ; WRONG - becomes other.example.com.example.com.
  www   CNAME   other                ; Relative - becomes other.example.com. (sometimes intended)

In practice (DNS APIs):

Different DNS providers handle this differently:

• Some require trailing dots
• Some strip them automatically
• Some normalize either way

[jooola]

Thanks for digging up that documentation.

Now, looking at external dns, because the CNAME targets are always "normalized", we cannot make the difference between a absolute and relative value in our webhook.

• Should the relative CNAME feature explicitly be documented as not supported in external-dns?
• Should there be a way to get the raw value (no normalization) and leave the webhook developers implement and document such normalization (if needed)?

[ivankatliarchuk]

The project is open-source, and maintained on a best-effort basis. There is quite a few designs that needs addressing.

Feel free to create a proposal/standart here: , outlining the suggested contract. Once it’s approved, you can move ahead with implementing the solution across the project.

[ivankatliarchuk]

/kind design
/kind documentation