Kubernetes Gateway API: Separating Infrastructure, Routing, and Application Ownership

Kubernetes Ingress standardized basic HTTP routing but left many advanced behaviors to controller-specific annotations. Gateway API defines role-oriented resources with typed attachment and status. It is an API project, not a bundled proxy: an implementation still programs a load balancer, gateway, or service mesh.

The ownership model

Infrastructure providers manage GatewayClass objects and their controllers. Cluster operators create Gateway listeners, addresses, TLS, and namespace attachment policy. Application teams create HTTPRoute, GRPCRoute, or other supported route resources. This separation reduces the need to grant every application team control over shared edge infrastructure.

Attachment and policy

Routes attach only when parent references, listener rules, namespaces, and permitted references agree. Controllers report conditions in status; a YAML object existing does not mean traffic is accepted. Cross-namespace references require explicit authorization, preventing a route from silently binding another team’s Secret or Service.

Migration and observability

Inventory every Ingress annotation and verify that the selected Gateway implementation supports an equivalent, portable feature or a documented extension. Run parallel endpoints, compare TLS, redirects, source IPs, timeouts, retries, and metrics, then change DNS gradually. Alert on rejected routes and controller reconciliation errors as well as data-plane latency.

Limits

Gateway API does not eliminate vendor differences, DNS management, certificate lifecycle, network policy, or cloud load-balancer cost. Use conformance information for the exact implementation and version. The benefit is a clearer, extensible contract—not magic portability.

Listeners are explicit attachment boundaries

A Gateway listener declares protocol, port, hostname, TLS behavior, and which namespaces may attach routes. Route parentRefs request attachment; the controller evaluates listener compatibility and reports conditions such as acceptance and resolved references. Inspect status on GatewayClass, Gateway, and Route. An object can be syntactically valid while no controller accepts it or no data-plane configuration is programmed.

Use namespace selectors and allowedRoutes to express tenancy. Avoid allowing all namespaces to attach to a shared public listener without policy. Route hostnames and listener hostnames must intersect according to the API rules. Give application teams permission to manage only their Routes, while platform teams retain listeners, addresses, certificates, and GatewayClass parameters.

Gateway API uses ReferenceGrant in the target namespace to authorize supported cross-namespace references. This prevents a route owner from attaching another team’s Service or Secret merely by naming it. Keep grants narrow by source group, kind, and namespace, and review them as security policy. A grant permits the reference; it does not grant users direct read access to the referenced object.

Certificate references, backend references, and policy attachment each have implementation and API-version rules. Verify ResolvedRefs and controller events. Secret rotation, backend deletion, or a changed grant can invalidate traffic without modifying the Route itself.

Typed routes and filters

HTTPRoute defines matches, backend references, weights, and standardized filters for HTTP traffic. GRPCRoute, TLSRoute, TCPRoute, and UDPRoute have different support and release channels. Do not assume every implementation supports every route kind or filter. Consult the project’s conformance reports and controller documentation for the exact versions installed.

Backend weights express traffic proportions, not health-aware release approval. A controller may stop sending to unhealthy endpoints according to its data plane, but database compatibility, retry safety, and business correctness remain application concerns. Test timeout, retry, header mutation, redirects, mirroring, and protocol behavior rather than translating vendor annotations mechanically.

Policy attachment and extensions

Gateway API distinguishes portable core behavior from implementation-specific policy and extension points. Direct Policy Attachment and inherited policy mechanisms have defined target and status models that evolve with the API. Use standard policy resources where supported, and isolate vendor extensions so migration impact is visible. Avoid annotations that silently recreate the opaque Ingress model.

Record which policy controls TLS, authentication, authorization, rate limiting, timeout, retry, and observability. Conflicting policies should produce understandable status and tests. NetworkPolicy still controls pod traffic separately; Gateway resources do not automatically create east-west authorization.

Migration and failure testing

Inventory IngressClass, annotations, certificates, DNS, addresses, firewall rules, health checks, redirects, rewrites, affinity, timeouts, and source-IP expectations. Deploy a parallel Gateway endpoint, replay representative traffic, compare status and telemetry, then lower DNS TTL and shift gradually. Preserve the old path until rollback time and data compatibility are proven.

Test an unaccepted Route, missing ReferenceGrant, expired certificate, unavailable backend, controller restart, data-plane rollout, and cloud quota failure. Monitor configuration acceptance, programmed status, rejected references, certificate expiry, backend health, request SLOs, and data-plane saturation. Reconcile controller-created cloud resources through the owning implementation rather than editing them out of band.

Version and conformance governance

Gateway API resources have support levels and channels. Pin CRDs and controller versions within the implementation’s compatibility matrix, upgrade them through a representative cluster, and review conversion or field changes. A CRD upgrade alone does not upgrade the controller or data plane.

Keep a matrix of required features against the implementation’s published conformance. Portability means another conformant implementation can satisfy the same tested contract, not that every Gateway YAML behaves identically everywhere. The matrix, rendered resources, status, controller version, and traffic tests belong in the release evidence.

Security review must also cover the data plane that the API configures. Harden its service account, pod security context, network access, admin interface, metrics endpoint, and cloud credentials. Separate controller permissions from application route permissions. A compromised Route writer should not be able to replace a shared certificate, alter another namespace’s backend, or change the GatewayClass.

Back up declarative resources and certificate authority dependencies, then rehearse recreation of controller and Gateway in an isolated environment. Preserve allocated addresses and DNS strategy where recovery requires stable endpoints. Recovery is complete only after route status is accepted and real protocol traffic passes the intended authentication and TLS path.

Related:

Sources: