Gateway: hostname-less tenant listeners rejected with misleading 'must be unique' (default-listener injection collision)

[ecv]

Summary

A tenant Gateway (class datum-external-global-proxy) whose listeners use the default ports/protocols (80/HTTP, 443/HTTPS) without a hostname is rejected at admission with a misleading upstream message:

Gateway.gateway.networking.k8s.io "http-gateway" is invalid: spec.listeners:
  Invalid value: Combination of port, protocol and hostname must be unique for each listener

The spec is valid per upstream Gateway API (listener hostname is optional). The rejection comes from NSO's default-listener injection colliding with the tenant's listeners.

Reproduction (live, kubectl apply --dry-run=server)

#	Listeners	Hostname(s)	Result
A	2 — 80/HTTP, 443/HTTPS	none	❌ "must be unique"
B	1 — 80/HTTP	none	❌ "must be unique"
C	2 — 80/HTTP, 443/HTTPS	distinct	✅
D	1 — 80/HTTP	set	✅
E	2 — 80/HTTP, 443/HTTPS	same hostname	✅

Probe B is decisive: a single tenant listener cannot collide with itself, yet it is rejected — so the failure is not tenant-side tuple duplication.

Root cause

SetDefaultListeners (internal/util/gateway/listeners.go) unconditionally appends two listeners, both without a hostname at creation:

• default-http → 80 / HTTP
• default-https → 443 / HTTPS

IsDefaultListener keys off the listener name (default-http / default-https) only. When a tenant defines their own 80/HTTP and/or 443/HTTPS listeners under different names and omits hostname, defaulting produces duplicate (port, protocol, hostname=∅) tuples — e.g. tenant http (80,HTTP,∅) + injected default-http (80,HTTP,∅). The upstream Gateway API CRD CEL then rejects the whole object with Combination of port, protocol and hostname must be unique for each listener.

Probes C/D/E pass because giving the tenant listeners a hostname makes their tuple distinct from the hostname-less injected defaults.

Separately, validateListeners (internal/validation/gateway_validation.go:72) already requires a hostname on non-default listeners (must be set to "…" or a custom hostname). So hostname-less tenant listeners are unsupported by design — but the tenant never sees that clear message; the injected-default collision trips the CEL first and surfaces the confusing "must be unique" error instead.

Impact

• Misleading error: tenants see a uniqueness complaint about listeners they didn't duplicate, with no indication that defaults were injected.
• Blocks datum-cloud/infra integration test tests/networking/http-gateway (datum-cloud/infra#2804), whose Gateway defines plain http/https listeners with no hostname.

Suggested fixes (pick per design intent)

1. Make defaulting idempotent against tenant listeners — skip injecting default-http/default-https when a tenant listener already covers that port/protocol (dedupe by (port, protocol), not just name).
2. Set the expected DNS hostname on the injected default listeners at creation so their tuples are always distinct.
3. If hostname-less listeners are simply unsupported, fail fast in validateListeners with the clear hostname is required message before defaulting can produce a colliding tuple — so the surfaced error is actionable.

Refs

• datum-cloud/infra#2804 (test failure + full investigation matrix)

[ecv]

Which fix matches design intent

Short answer: Fix #3 (reject the listener with a clear "hostname required" error) — but it must be enforced in the mutating defaulting webhook, not the validating webhook. Fixes #1 and #2 conflict with the existing design.

Why #3 is the right intent

The design already treats a distinguishing hostname as mandatory for every tenant listener:

• Permitted ports are locked to {80, 443} (ValidPortNumbers) and protocols to HTTP/HTTPS, so a tenant listener must share (port, protocol) with a default — hostname is the only available uniqueness axis.
• validateListeners (internal/validation/gateway_validation.go:72) already encodes this: a non-default listener with Hostname == nil → field.Required(… "must be set to %q or a custom hostname").
• The injected default-http / default-https are meant to coexist with tenant listeners (each carrying the canonical <uid>.<targetDomain> hostname, stamped by the controller) — commit 411dec035: "the user may remove these listeners if they wish."

So a tenant listener on 80/443 without a hostname is already an unsupported configuration. The only defect is that it surfaces as the upstream CEL's misleading "must be unique" instead of NSO's own clear message.

The ordering catch — why #3 can't live in the validating webhook

Kubernetes admission runs in this fixed order:

1. mutating admission webhooks → GatewayCustomDefaulter.Default injects default-http/default-https (hostname-less at create)
2. CRD schema + x-kubernetes-validations CEL → the upstream "Combination of port, protocol and hostname must be unique" rule
3. validating admission webhooks → GatewayCustomValidator → ValidateGateway/validateListeners

Because the defaulter (step 1) always occupies both 80 and 443 with hostname-less defaults, any hostname-less tenant listener on those ports produces a duplicate (port, protocol, ∅) tuple, so the CEL at step 2 rejects the object before NSO's validator at step 3 ever runs. That's exactly what the live repro showed — the CEL message, never NSO's. Consequence: validateListeners's Hostname == nil → field.Required branch is effectively dead code for tenant listeners at create.

A validateListeners change therefore cannot replace the confusing message — it's preempted.

Recommended implementation

Move/duplicate the hostname-required check into GatewayCustomDefaulter.Default (internal/webhook/v1/gateway_webhook.go:135), which returns error and so denies admission before the CEL stage. Before SetDefaultListeners, reject any non-default listener on a valid port whose Hostname is nil, with the intended message (ideally surfacing the canonical <uid>.<targetDomain> value so the tenant knows what to set). Keep the default-listener injection unchanged — coexistence is preserved. Optionally retain the validateListeners check as defense-in-depth for the update path.

Why not #1 / #2

• Initialize project with kubebuilder init. #1 (dedupe defaulting by (port, protocol)) breaks the canonical-hostname guarantee: it would suppress the <uid>.<targetDomain> default listener whenever a tenant adds any 80/443 listener. Per 411dec035 the default listeners exist precisely so the gateway always serves its canonical hostname; defaults and tenant listeners are meant to coexist via distinct hostnames, not be collapsed.
• Initial commit of Datum Networking APIs. #2 (stamp the DNS hostname on defaults at create) isn't possible at create: the canonical hostname is derived from gateway.UID (config.go GatewayDNSAddress), which isn't available in the create mutating webhook — the documented reason the controller stamps it later (gateway_controller.go ~L182). A placeholder would fight that inject-then-stamp lifecycle.

Note

Even with #3, consider whether the long-term intent is to reject hostname-less tenant listeners or to absorb them (e.g., treat a bare user listener as a request for a default). Current code and tests point firmly at "reject with guidance," so #3 is the conservative, intent-aligned choice.