The Gateway API defines Kubernetes resources for accepting traffic from outside a cluster and routing it to Services. A gateway proxy is the entry point; routes tell it where to send traffic. Backend Services can be ordinary ClusterIP Services rather than NodePort or LoadBalancer Services. section 13.1
Compared with Ingress, the Gateway API keeps the network entry point and routing rules in separate objects. An administrator can manage a shared Gateway while application developers manage their own Routes, including Routes in other namespaces. It also supports more than HTTP: TLS, gRPC, TCP, and UDP have route types. section 13.1.1
Three resources form the basic path from client to Service:
- A GatewayClass identifies the controller that provisions Gateways of that class. A cluster may offer more than one class. section 13.2.1
- A Gateway selects a class and defines listeners: the protocols, ports, and optionally hostnames on which it accepts connections. Its controller typically creates a proxy and a LoadBalancer Service. section 13.2.2
- A Route references a parent Gateway and names backend Services. For HTTP traffic, an HTTPRoute can match requests and forward them to a Service. section 13.3.1
Listing 13.1 Defining a Gateway with a single listener
apiVersion: gateway.networking.k8s.io/v1 #1
kind: Gateway #1
metadata:
name: kiada #2
labels:
suite: kiada
spec:
gatewayClassName: istio #3
listeners: #4
- name: http #5
port: 80 #6
protocol: HTTP #7
hostname: '*.example.com' #8
This Gateway manifest selects the Istio class and accepts HTTP on port 80 for hostnames under example.com. Creating this listener alone does not specify a backend. section 13.2.2
Listing 13.2 Attaching an HTTP Service to a Gateway using an HTTPRoute object
apiVersion: gateway.networking.k8s.io/v1 #1
kind: HTTPRoute #1
metadata:
name: kiada #2
spec:
parentRefs: #3
- name: kiada #3
hostnames: #4
- kiada.example.com #4
rules: #5
- backendRefs: #5
- name: kiada #5
port: 80 #5
This HTTPRoute attaches to the Gateway and sends requests for kiada.example.com to the Service on port 80. Apply the Gateway and Route manifests with kubectl apply -f, then inspect the assigned Gateway address with kubectl get gtw. section 13.3.1 section 13.2.2
If traffic does not flow, inspect the HTTPRoute status. Accepted reports whether its parent accepted the route; ResolvedRefs reports whether its references could be resolved. A Gateway listener’s hostname and route permissions can prevent attachment. section 13.3.1
HTTPRoute rules can match requests, split traffic by backend weight, mirror requests, change headers, rewrite URLs, or redirect clients. For HTTPS, a Gateway can terminate TLS using a certificate Secret, allowing HTTPRoute to inspect the decrypted request, or pass TLS through to a backend without decrypting it. TCPRoute and UDPRoute instead link protocol-specific listeners to backends; TCP routing cannot inspect application content. section 13.8 section 13.4 section 13.5.1
The API needs Gateway API Custom Resource Definitions (CRDs) and a provider controller; Kubernetes does not supply a controller by default. Installations and providers differ: the standard release channel contains stable fields, while the experimental channel includes fields and route kinds that may change. Check provider support before relying on a route kind: in the illustrated Istio setup, a UDPRoute receives no controller status because Istio does not support it. section 13.1.2 section 13.1.3 section 13.5.2
