In a multi-tenant Kubernetes cluster using the Gateway API, how does an HTTPRoute in one namespace get attached to a Gateway in another, and what controls does the cluster operator have over which namespaces are allowed to attach?

## The handshake Gateway API deliberately avoids letting either side act unilaterally. If routes could attach to any Gateway just by naming it, one tenant could hang a route for `admin.example.com` off the shared edge and hijack traffic. If Gateways had to enumerate every route, self-service would be impossible. So attachment is a two-sided handshake, and both sides must say yes. **Route side — `parentRefs`.** An HTTPRoute lists one or more parents. Each entry has `name`, optional `namespace` (defaults to the route's own), and optionally `sectionName` (a listener name) or `port` to narrow which listener it attaches to. Omitting both means "every compatible listener on that Gateway", which is convenient but blunt: a route with no `sectionName` on a Gateway with an HTTP and an HTTPS listener attaches to both. **Gateway side — `allowedRoutes`.** Each listener carries an `allowedRoutes` block with two parts: - `namespaces.from`: `Same` (default — only routes in the Gateway's own namespace), `All`, or `Selector`, which takes a `selector` matched against **Namespace labels**. The selector matches namespace objects, not routes, which is what makes it an operator-controlled gate: the tenant cannot label their own namespace unless you let them. - `kinds`: restricts which route kinds may attach, e.g. only `HTTPRoute` on an HTTPS listener, so nobody bolts a TLSRoute onto it. **Hostname intersection.** Independently of permissions, the route's `hostnames` must intersect the listener's `hostname`. A listener with `hostname: *.example.com` accepts routes for `shop.example.com`; a route claiming `other.test` intersects nothing and is not attached, with reason `NoMatchingListenerHostname`. A route with no hostnames inherits the listener's. ## ReferenceGrant — a different axis People conflate two kinds of cross-namespace reference. Attachment is route → Gateway and is governed by `allowedRoutes`. A **backend** reference is route → Service and, when it crosses namespaces, is governed by `ReferenceGrant`. The same mechanism guards a Gateway referencing a TLS Secret in another namespace. `ReferenceGrant` lives in the *target* namespace — the one being referenced — and says "resources of kind X in namespace Y may reference resources of kind Z here". This inverts the trust direction correctly: the owner of the Secret or Service grants access; the referrer cannot self-authorise. Without a grant, the reference is refused and the route's `ResolvedRefs` condition reports `RefNotPermitted`. This exists because Kubernetes RBAC governs who may *write* objects, not what those objects may *point at* — without ReferenceGrant, anyone able to create a route could exfiltrate traffic to a Service in a namespace they cannot read. ## Overlap and hostname conflicts Once several tenants attach to one listener, overlapping matches are inevitable. The spec defines deterministic precedence rather than leaving it to controller internals: exact path match beats prefix; among prefixes, the longest wins; then method match, then the number of matching header conditions, then query params. Ties are broken by the route with the oldest `creationTimestamp`, then namespace/name ordering, then rule order within the route. "Oldest wins" is worth remembering because it means a squatter who created a route first keeps a contested hostname — an argument for keeping shared hostnames on operator-controlled routes or per-team listeners. Gateways may also report `ListenerConditionConflicted` when two listeners on the same port declare incompatible protocol or hostname configurations. ## Operating patterns Three patterns cover most clusters: 1. **Shared Gateway, selector-gated.** One `edge` Gateway in an infra namespace, `namespaces.from: Selector` matching a label the platform team applies during namespace onboarding. Cheap, one load balancer, and onboarding is an explicit act. 2. **Gateway per tenant.** Each team gets its own Gateway (and often its own address) with `from: Same`. Strong isolation and independent blast radius, at the cost of more load balancers. 3. **Listener per team on a shared Gateway.** One listener per hostname with a narrow selector, and teams pin `sectionName`. Good middle ground: shared address, per-hostname authorisation, no squatting. ## Debugging checklist Run `kubectl get httproute <name> -o yaml` and read `status.parents[]`. For each parent you get `Accepted` (`NotAllowedByListeners`, `NoMatchingListenerHostname`, `NoMatchingParent`) and `ResolvedRefs` (`BackendNotFound`, `RefNotPermitted`, `InvalidKind`). Then check the Gateway: `Programmed`, per-listener `attachedRoutes` count, and `ResolvedRefs` for the certificate. The pair of statuses almost always localises the failure without touching controller logs.