Chapter 13: Routing traffic using the Gateway API

Introduction

Introduces the Gateway API as a broader alternative to Ingress for exposing Kubernetes Services externally.

• Gateway API and Ingress scope: Explain why the Gateway API is presented as an alternative to Ingress and what kinds of Services its gateway proxies can expose.
  Why it matters: This distinction explains why the chapter moves beyond Ingress to gateway-based routing.

Key terms: Ingress API, Gateway API, gateway proxies, L7, L4

13.1 Introducing the Gateway API

Introduces the Gateway API as Kubernetes resources for routing external traffic through a gateway proxy to Services.

• Gateway API traffic routing: Explain that Gateway API resources set up a gateway proxy to direct traffic from outside the cluster to Services, including ordinary ClusterIP Services.
  Why it matters: It clarifies that a Service can remain cluster-internal while a gateway provides a route to it from outside the cluster.

Key terms: Gateway API, gateway proxy, ClusterIP Services, NodePort, LoadBalancer

13.1.1 Comparing Gateway API to Ingress

This section compares Ingress with the Gateway API and explains the benefits of separating gateways from routes.

• Gateway and route resource roles: Explain how Gateway, GatewayClass, and Route objects compare with Ingress and IngressClass objects, and where each API specifies the services to expose.
  Why it matters: This distinction helps you recognize which object holds the gateway configuration and which objects connect services to it.
• Benefits of separate routes: Explain why keeping routing rules in separate Route objects helps with configuration and division of responsibility.
  Why it matters: Separating gateway ownership from application routing lets teams manage their own part without putting every rule in one object.
• Cross namespace gateway sharing: Describe how routes can reference gateways and services across namespaces and what that makes possible.
  Why it matters: Cross-namespace references allow services in different namespaces to share an external entry point.

Key terms: Ingress, IngressClass, Gateway, GatewayClass, Route, Route objects, TLS, gRPC, TCP, namespaces

13.1.2 Understanding the Gateway API implementation

This section explains why the Gateway API needs a separate provider and how release channels and support levels affect API stability and portability.

• Gateway API implementation model: Explain that the Gateway API defines resources and behavior but Kubernetes does not implement it; an installed third-party provider supplies the implementation.
  Why it matters: It explains why creating Gateway API resources alone is not enough to get a working gateway.
• Standard and experimental channels: Distinguish the standard and experimental release channels and explain what choosing a channel when installing Gateway API CRDs makes available.
  Why it matters: The channel choice determines whether you can use experimental parts of the API and accept possible future changes.
• Feature support and portability: Distinguish core, extended, and implementation-specific support levels, and explain why a stable API feature is not necessarily supported by every provider.
  Why it matters: It helps you tell whether a configuration will keep working—and mean the same thing—if you change providers.
• Gateway provider choice: Describe the available choice of Gateway API providers and why this book uses Istio without requiring its service mesh functionality.
  Why it matters: It explains why the book installs Istio while leaving room for other providers in your own cluster.

Key terms: Gateway API, Gateway API provider, implementation, Custom Resource Definitions (CRDs), standard channel, experimental channel, support level, core features, extended features, implementation-specific features

13.1.3 Deploying Istio as the Gateway API provider

Explains how to prepare a cluster for Gateway API by installing its resource definitions and a provider that manages those resources.

• Gateway API resource setup: Describe how to check whether a cluster supports Gateway API resources and what to install if it does not.
  Why it matters: This check tells you whether the cluster can accept the resources used in the chapter’s examples.
• Kustomize manifest processing: Explain why the installation uses kubectl apply -k and how Kustomize applies customizations.
  Why it matters: It explains the unfamiliar -k option used to install the Gateway API resources.
• Gateway API provider deployment: Explain why CRDs alone are insufficient and describe the provider and readiness checks presented for Istio, including the GKE alternative.
  Why it matters: A Gateway resource needs a running provider to have an effect, not just an installed definition.

Key terms: Gateway API Custom Resource Definitions, CRDs, experimental channel, kubectl apply -k, Kustomize, kustomization.yaml, patches, controller, Gateway API provider, Istio

13.2 Deploying a Gateway

This introduction establishes that a Gateway object must specify a Gateway class and that a cluster may offer more than one class.

• Gateway class selection: Explain that a Kubernetes cluster may provide multiple Gateway classes and that creating a Gateway object requires specifying one.
  Why it matters: This tells you what must be selected when creating a Gateway.

Key terms: Gateway class, Gateway object

13.2.1 Understanding Gateway classes

Explains what GatewayClass objects represent, what their definitions specify, and why each Gateway must name a class.

• Gateway classes and selection: Explain that a GatewayClass object represents an available gateway class, identifies the controller that manages its gateways, and must be referenced by each Gateway object.
  Why it matters: The class reference tells Kubernetes which gateway controller should manage a Gateway.

Key terms: GatewayClass, Gateway, controllerName, Istio, parameters

13.2.2 Creating a Gateway object

Shows how to define and create a Gateway, then inspect the externally reachable proxy resources Istio creates for it.

• Gateway manifest and listener: Describe how the example Gateway selects a GatewayClass and defines where it accepts HTTP connections, including the role of an optional address.
  Why it matters: These fields determine which implementation handles the Gateway and where it accepts connections.
• Gateway creation and address check: Describe how the example Gateway is created and how its assigned address is checked.
  Why it matters: Checking the assigned address tells you where external clients may reach the Gateway.
• Istio gateway traffic path: Trace how Istio’s created Service and proxy pod carry external traffic for this Gateway, and distinguish that arrangement from a Gateway API requirement.
  Why it matters: It explains what receives traffic at the Gateway’s address without mistaking Istio’s resources for a universal Gateway API design.

Key terms: Gateway, gatewayClassName, GatewayClass, listener, addresses, kubectl apply, kubectl get, ADDRESS, gtw, LoadBalancer Service

13.2.3 Exploring the Gateway’s status

This section shows how to read a Gateway’s status to find its reachable addresses, assess its conditions, and diagnose listener problems.

• Gateway status addresses: Describe how to find the addresses at which a gateway can be reached and explain why they may differ from addresses in its spec.
  Why it matters: The status tells you where to try reaching the gateway, even when you did not request a particular address.
• Gateway condition interpretation: Explain how to read a Gateway condition and what its Programmed condition indicates.
  Why it matters: Conditions help you tell whether gateway configuration is progressing and where to look when it is not.
• Listener status diagnosis: Describe what each listener’s status reports and explain why the example gateway returns a 404 despite its listener having no errors.
  Why it matters: Checking the listener as well as the Gateway can explain a failed request even when the listener itself reports no errors.

Key terms: status.addresses, spec.addresses, IPAddress, Hostname, conditions, type, status, reason, message, Programmed

13.3 Exposing HTTP services using HTTPRoute

This section identifies HTTPRoute as the common Gateway API route kind for connecting an HTTP Service to one or more gateways.

• HTTPRoute role in Gateway API: Explain that HTTPRoute is a common kind of Gateway API Route object used to connect an HTTP Service to one or more gateways.
  Why it matters: This gives you the basic purpose of HTTPRoute before you configure one.

Key terms: Gateway API, Route object, HTTPRoute, HTTP Service, gateway

13.3.1 Creating a simple HTTPRoute

This section creates a basic HTTPRoute, explains the defaults visible in its spec, and shows how its status helps diagnose routing problems.

• Basic HTTPRoute traffic path: Explain how the kiada HTTPRoute connects a Gateway to a Service and which traffic it forwards. Describe how to create the route and test access through the Gateway’s address.
  Why it matters: These references establish where incoming HTTP traffic enters and where the route sends it.
• Defaulted HTTPRoute spec fields: Describe what inspecting the created HTTPRoute’s YAML reveals beyond the original manifest, including default reference kinds and the rule’s match.
  Why it matters: The stored spec makes implicit routing choices visible before you configure more selective routes.
• Per-parent route status: Explain why HTTPRoute status has separate parent entries and how to use those entries when traffic is not flowing.
  Why it matters: Per-parent status helps locate a routing problem without assuming every Gateway handles the route the same way.

Key terms: HTTPRoute, parentRefs, backendRefs, Gateway, Service, hostname, spec, weight, matches, status

13.3.2 Splitting traffic between multiple backends

This section shows how to split HTTPRoute traffic between stable and canary Services using weighted backends.

• Weighted HTTPRoute backend traffic: Explain how multiple backendRefs and their weights divide requests between Services, including what happens when weights are omitted.
  Why it matters: Weights let you control how much traffic each application version receives.
• Distinct stable and canary Services: Explain why the example needs separate Services for the stable and new pods, and how to check that they target the intended pods.
  Why it matters: Weights cannot give each version its intended share if a backend Service itself sends traffic to both versions.
• Canary traffic risk limitation: Explain why a small share of requests might be sent to a canary Service.
  Why it matters: A limited canary share reduces the impact of problems in a new version.

Key terms: HTTPRoute, backendRefs, weight, Service, kiada Service, kiada-new Pod, kiada-new Service, kiada-stable Service, endpoints, canary Service

13.3.3 Routing HTTP requests to different backends

This section explains how an HTTPRoute sends requests to different backend services by matching data in each HTTP request.

• Request matching and fallback: Explain when a request matches an HTTPRoute entry and how a rule without match conditions handles remaining requests.
  Why it matters: These matching rules explain why a request reaches a particular backend rather than another one.
• HTTP request matching options: Describe the request properties an HTTPRoute can match and the matching options illustrated for headers, paths, and query parameters.
  Why it matters: Choosing the right request property and match type lets you direct the intended requests to a service.
• Combined conditions and backends: Explain how multiple request conditions can be combined and what can happen to traffic after it matches.
  Why it matters: Combining conditions narrows which requests qualify, while weighted backends can divide the qualifying traffic.

Key terms: HTTPRoute, matches, catch-all rule, backend service, method, headers, path, queryParams, Exact, PathPrefix

13.3.4 Augmenting HTTP traffic with filters

Explains how HTTPRoute filters modify HTTP traffic, redirect requests, mirror them to another service, and use implementation-specific extensions.

• Request and response headers: Describe how HTTPRoute filters add, set, or remove request and response headers, including the difference between add and set when a header already exists.
  Why it matters: Header filters let a gateway adjust messages without changing the application.
• Full and prefix path rewrites: Distinguish replacing the entire request path from replacing only its matched prefix before forwarding a request to a backend.
  Why it matters: Rewriting lets an external URL work with a backend that expects a different path.
• Client redirects without backends: Explain how a RequestRedirect filter points a client to another URL without routing its request to a backend.
  Why it matters: A gateway can handle redirects such as HTTP to HTTPS without application code.
• Mirrored requests and client responses: Trace what happens to the original request, its mirrored copy, and their responses when a RequestMirror filter is used.
  Why it matters: Mirroring lets a new service version receive production requests without changing client responses.
• Implementation-specific filter references: Describe how an HTTPRoute refers to an implementation-specific filter and where that filter’s configuration resides.
  Why it matters: Extensions let implementations offer filters beyond those standardized in the Gateway API.

Key terms: RequestHeaderModifier, responseHeaderModifier, add, set, remove, URLRewrite, ReplaceFullPath, ReplacePrefixMatch, matched prefix, RequestRedirect

13.4 Configuring a gateway for TLS

Introduces the two ways a Gateway can handle TLS and explains how each affects what the gateway can see.

• Gateway TLS handling options: Distinguish terminating TLS at the gateway from passing TLS through to the backend, including what the gateway can see in each case.
  Why it matters: Where TLS ends determines whether the gateway can inspect HTTP requests.

Key terms: TLS termination, TLS pass-through, backend, Server Name Identification (SNI)

13.4.1 Terminating TLS sessions at the gateway

Explains how to terminate HTTPS at a Gateway, route the resulting HTTP traffic with an HTTPRoute, and recognize that traffic to the backend is then unencrypted.

• Gateway TLS termination setup: Describe how to configure an HTTPS Gateway listener to terminate TLS using a certificate and private key stored in a Secret, so a backend that does not support TLS can receive HTTP.
  Why it matters: This lets clients use HTTPS even when the backend service does not support TLS.
• HTTPRoute behavior after termination: Explain why an HTTPRoute can route requests received over either HTTP or HTTPS when the gateway terminates TLS, and distinguish client-to-gateway encryption from gateway-to-backend traffic.
  Why it matters: HTTPS at the gateway does not by itself provide encryption all the way to the service.
• Optional listener TLS settings: State where additional TLS settings can be specified and why the available settings may vary.
  Why it matters: It helps you distinguish the basic termination setup from implementation-dependent TLS tuning.

Key terms: Gateway listener, tls.mode, Terminate, certificateRefs, Secret, HTTPRoute, TLS termination, backend service, tls.options, minimum TLS version

13.4.2 End-to-end encryption using TLSRoutes and pass-through TLS

This section shows how to pass encrypted traffic through a Gateway to a pod and route it with a TLSRoute.

• End-to-end TLS traffic flow: Trace a request from the client through the Gateway to the Envoy sidecar, and explain why TLS pass-through keeps HTTP traffic off the network.
  Why it matters: It explains where decryption happens and why the HTTP request is not sent unencrypted over a network.
• Pass-through Gateway configuration: Describe how the Gateway listener is configured for TLS pass-through and why it uses the TLS protocol rather than HTTPS.
  Why it matters: The listener must accept TLS without treating the encrypted traffic as visible HTTP.
• TLSRoute routing limits: Explain why pass-through traffic needs a TLSRoute and what the Gateway can use to choose a backend.
  Why it matters: It identifies which routing decisions remain possible when the Gateway cannot decrypt requests.

Key terms: TLS pass-through, Envoy sidecar, loopback device, listener, tls.mode, Passthrough, TLS, TLSRoute, HTTPRoute, Server Name Identification (SNI)

13.5 Exposing other types of services

This section introduces Gateway API route resources for TCP, UDP, and gRPC services and prepares a test service for the following examples.

• Routes for non-HTTP services: Distinguish the Gateway API’s support for TCP, UDP, and gRPC services from the Ingress API, and name the route resource provided for each.
  Why it matters: These resource names help you recognize which Gateway API route applies to each type of service.

Key terms: Gateway API, Ingress API, TCPRoute, UDPRoute, GRPCRoute

13.5.1 Exposing a TCP service with a TCPRoute

This section shows how a TCP listener and TCPRoute expose a backend Service through a gateway, and explains the limits of TCP routing.

• TCP listener and route: Explain how to expose a TCP Service by adding a TCP listener to a Gateway and creating a TCPRoute that links the Gateway to the backend Service.
  Why it matters: The listener and route have different jobs, and both are needed to expose the Service.
• TCP backend selection limits: Distinguish weighted traffic splitting across TCPRoute backends from content-aware routing, and describe what happens to a connection in the section's example.
  Why it matters: It clarifies what TCPRoute can distribute and what it cannot inspect to make routing decisions.

Key terms: TCP listener, TCPRoute, Gateway, backend service, backends, weight, content-aware routing

13.5.2 UDPRoute

This subsection shows how to expose a UDP service with a gateway listener and UDPRoute, then how to recognize that the example implementation has not processed the route.

• UDP Listener and Route: Describe how a UDP listener and UDPRoute work together to expose a UDP service through a gateway. In the example, the listener accepts traffic on UDP port 300, and the UDPRoute links the kiada Gateway to port 3000 of the test Service.
  Why it matters: The listener alone does not establish the link to the backend Service.
• UDPRoute Support Check: Explain what the example's echo test and UDPRoute status reveal about implementation support. State that Istio did not support UDPRoutes at the time of writing, so the test gets no reply, and that the route's missing status indicates no controller has processed it.
  Why it matters: A created route may not work if the chosen Gateway API implementation does not process it.

Key terms: UDP listener, UDPRoute, Gateway, backend service, status, controller, Istio

13.5.3 GRPCRoute

This section shows how a GRPCRoute directs gRPC calls through a Gateway and briefly describes its matching rules, filters, and implementation support.

• gRPC listener and route setup: Describe how to expose a gRPC service by adding a Gateway listener and creating a GRPCRoute, using the Ping example to explain where a matching call goes. State the section’s caveat about Istio support.
  Why it matters: It connects the Gateway listener to the route that sends a gRPC call to its backend.
• gRPC request matching conditions: Explain what a GRPCRoute rule can match in an incoming gRPC request and distinguish the stated support for exact and regular-expression service or method matches.
  Why it matters: Matching conditions determine which gRPC calls a route rule applies to.
• Available GRPCRoute rule filters: Describe the kinds of changes or forwarding behavior the listed GRPCRoute filters provide.
  Why it matters: Filters let a GRPCRoute do more than select a backend.

Key terms: GRPCRoute, gRPC listener, Gateway, Service, matches, gRPC request headers, method, Exact, RegularExpression, filters

13.6 Using Gateway API resources across namespaces

This section introduces the permission requirement for routes that reference gateways or backend services across namespaces.

• Cross-namespace reference permissions: Explain that a route can reference a gateway or backend service in another namespace only with explicit permission, and that permission is granted differently for the two cases.
  Why it matters: This distinction helps you recognize why a route cannot automatically use resources in another namespace.

Key terms: route, gateway, backend service, namespace, explicit permission

13.6.1 Sharing a gateway across namespaces

Explains how a Gateway can accept routes from other namespaces and how a route references that Gateway.

• Listener namespace permissions: Explain how each Gateway listener controls which namespaces may attach routes, including the Same, All, and Selector options and the example’s different HTTP and TCP policies.
  Why it matters: A shared Gateway can grant different namespaces access to different listeners.
• Cross-namespace Gateway references: Describe what a route must specify to reference a Gateway in another namespace, and explain why the example HTTPRoute binds while the TCPRoute initially does not.
  Why it matters: Naming a Gateway in another namespace is not enough if its listener does not permit the route’s namespace.

Key terms: listener, allowedRoutes.namespaces, Same, All, Selector, parentRefs, namespace, HTTPRoute, TCPRoute, part-of=kiada

13.6.2 Routing to a service in a different namespace

This subsection explains how a ReferenceGrant permits an HTTPRoute to use a Service backend in another namespace and how to verify that the reference is allowed.

• Cross-namespace backend permission: Explain why an HTTPRoute cannot use a Service in another namespace without a ReferenceGrant, and where that grant must be created.
  Why it matters: A route’s backend reference will not resolve until the Service’s namespace permits it.
• ReferenceGrant scope and verification: Describe how a ReferenceGrant identifies allowed referrers and referents, and how the HTTPRoute status reflects whether its backend reference is permitted.
  Why it matters: The grant’s fields define the breadth of permission, and ResolvedRefs lets you check whether the reference is accepted.

Key terms: ReferenceGrant, referent, HTTPRoute, Service, from, to, ResolvedRefs

13.7 From ingress gateways to service mesh

The section explains how the Gateway API extends from exposing services to outside clients to configuring service-to-service traffic in a service mesh.

• North South and East West Traffic: Distinguish traffic between outside clients and cluster services from traffic between services within the cluster, and explain how a service mesh manages the latter.
  Why it matters: This distinction explains why the Gateway API can be useful beyond exposing applications to external clients.
• Shared Service Mesh Configuration: Explain why service mesh configuration became part of the Gateway API GAMMA initiative.
  Why it matters: It explains why service-to-service routing is discussed alongside the Gateway API’s original ingress use.
• Service Parent Route Attachment: Trace how an HTTPRoute can govern service-to-service traffic without sending it through an additional gateway.
  Why it matters: A Service parent lets familiar route rules apply to traffic originating within the cluster.

Key terms: north/south traffic, east/west traffic, service mesh, Service Mesh Interface (SMI), Gateway API Mesh Management and Administration (GAMMA), HTTPRoute, parentRefs, group, kind, Service

13.8 Summary

Summarizes how the Gateway API exposes services through gateways and routes HTTP, TLS, gRPC, TCP, and UDP traffic.