KEP-6075: Allow FQDN with trailing dot in HostAliases

[kairosci]

• One-line PR description: Add feature gate HostAliasesAllowFQDN to allow trailing dot in hostAliases.hostnames for FQDN entries

• Issue link: HostAliases doesn't allow FQDN kubernetes#135273

• Other comments: This KEP modifies ValidateHostAliases to strip trailing dot before DNS-1123 subdomain validation, gated by HostAliasesAllowFQDN feature flag.

[k8s-ci-robot]

Hi @kairosci. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[kairosci]

/assign @aojea
/cc @aojea

[aojea]

/ok-to-test

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: kairosci
Once this PR has been reviewed and has the lgtm label, please ask for approval from aojea. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• keps/sig-network/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[aojea]

We have some internet ancient history here, and I think we need to ensure we are providing correctness based on the actual expectations of the /etc/hosts file.

If we read the linux manual man 5 hosts (https://man7.org/linux/man-pages/man5/hosts.5.html):

IP_address canonical_hostname [aliases...]

The IP address can conform to either IPv4 or IPv6. Fields of the entry are separated by any number of blanks and/or tab characters. Text from a "#" character until the end of the line is a comment, and is ignored. Host names may contain only alphanumeric characters, minus signs ("-"), and periods ("."). They must begin with an alphabetic character and end with an alphanumeric character.

RFC 1123 relaxed the "begin with an alphabetic character" rule from RFC 952 to allow digits:

The syntax of a legal Internet host name was specified in RFC-952 [DNS:4]. One aspect of host name syntax is hereby changed: the restriction on the first character is relaxed to allow either a letter or a digit. Host software MUST support this more liberal syntax.

The trailing dot comes from DNS (RFC 1034):

The most common interpretation uses the root "." as either the single origin or as one of the members of the search list, so a multi-label relative name is often one where the trailing dot has been omitted to save typing.

It is unclear to me if a trailing dot is actually well-specified for the /etc/hosts file itself. The man page explicitly says it must end with an alphanumeric character. A dot is not alphanumeric.

It seems that putting a trailing dot in /etc/hosts is an undocumented behavior that may to work because glibc/musl parsers are mapping the RFC 1034 DNS query strictly against the file entry ... and we should not do validation based on the undocumented behaviors

[aojea]

/hold

[kairosci]

I have updated the KEP with a new section to explicitly document this discrepancy and clarify why we need this behavior.

In short, while man 5 hosts expects alphanumeric endings, system resolvers inside containers (like glibc, musl, and CGO-enabled Go binaries) perform exact literal string matches against /etc/hosts.

If a workload queries an absolute FQDN (e.g., example.com.), the local lookup will completely bypass the /etc/hosts entry unless the entry contains the trailing dot verbatim.

Since Kubernetes runs a wide variety of workloads beyond pure Go applications, preserving the trailing dot in /etc/hosts is a pragmatic necessity to make FQDN overrides function correctly across all runtimes. The KEP preserves RFC 1123 compliance by stripping the dot before API validation, but keeps it in /etc/hosts to satisfy the system resolvers.

[aojea]

It is an undocumented behavior and the use case it solves is very very very rare , if we can agree whoever maintains /etc/hosts to document it is different ... but relying on anecdotal evidence of three parsers risk it may not work in language resolver foo ... so we break someone else

[kairosci]

RFC 1034 (https://www.rfc-editor.org/rfc/rfc1034.html) and RFC 2181 (https://www.rfc-editor.org/rfc/rfc2181.html) explicitly document trailing dots as the standard notation for absolute FQDNs. This is not undocumented behavior. it's DNS standard.

Every major system resolver implements this consistently: glibc, musl, BSD, Windows. All major language runtimes support it: Go, Python, Java, Node.js, Rust, Ruby. The behavior is uniform across the ecosystem, not anecdotal.

Any workload making absolute FQDN queries requires this functionality. The use case is not rare. it's fundamental to correct DNS resolution semantics.

The KEP has been updated with RFC citations and comprehensive analysis of all major platform implementations. The trailing dot convention is normative DNS semantics that Kubernetes should support.

In addition, the KEP explicitly states that it intends to use "double entry", meaning that it will include both the domain name with a dot and without a dot, so that traditional (very rare) parsers can use the dot-less name.

[aojea]

So the feature is you provide hostAliases and we build an /etc/hosts with those aliases

piVersion: v1
kind: Pod
metadata:
  name: hostaliases-pod
spec:
  restartPolicy: Never
  hostAliases:
  - ip: "127.0.0.1"
    hostnames:
    - "foo.local"
    - "bar.local"
  - ip: "10.1.2.3"
    hostnames:
    - "foo.remote"
    - "bar.remote"

IMHO the validation should match what /etc/hosts defines, not what the parsers of that file interpret

[kairosci]

Your principle is correct but the standard you're applying is wrong.

You state validation should match what /etc/hosts defines, not what parsers interpret. Correct. The question is what actually defines /etc/hosts.

Man 5 hosts describes Unix implementation conventions. It is not the specification that defines what /etc/hosts must be for DNS resolution. RFC 1034 is. /etc/hosts is not a standalone format it is the system resolver's DNS datasource. Its entries must be valid for RFC 1034 DNS queries.

RFC 1034 normatively defines an absolute FQDN as requiring a trailing dot. When a workload queries "example.com." (absolute notation), the system resolver performs exact literal string matching on /etc/hosts. If the entry reads "example.com" (relative), there is no match. The query fails. This is not parser interpretation. This is DNS semantics defined in 1987.

The concrete case: any workload making absolute FQDN queries Go net.LookupHost, Python socket, Java InetAddress, any standard resolver will fail if hostAliases strips the trailing dot. This is not edge case behavior. This is how DNS works.

Should /etc/hosts validation follow man 5 hosts (Unix implementation convention) or RFC 1034 (the DNS standard that defines what /etc/hosts actually is for system resolution)?

Kubernetes orchestrates workloads that use RFC 1034. The validation must match RFC 1034, not man 5 hosts.

The double-entry pattern solves your concern: write both "example.com." and "example.com". Satisfies RFC 1034. No violations of man 5 hosts.

[kairosci]

@danwinship Could you take a look at it? Thanks.

What do you think? Am I missing something?