Kubernetes Gateway API

What is Gateway API?

Kubernetes Gateway API represents a major leap forward in how the platform handles network traffic routing. As the successor to traditional Kubernetes networking approaches, it provides a unified way to manage Layer 4 and Layer 7 routing while offering more flexibility than its predecessors.

Why Gateway API?

Gateway API addresses fundamental limitations in the original Kubernetes Ingress design, which was built around a single-user model. In real-world clusters, infrastructure is shared between different personas - infrastructure providers, cluster operators, and application developers - each with distinct needs and responsibilities.

Gateway API solves this through a role-oriented architecture that gives each persona appropriate control over their domain:

Layer 4 Routing Support

Traditionally, Kubernetes Ingress was designed for Layer 7 (HTTP) routing, but it lacked support for Layer 4 (TCP/UDP) traffic. With Gateway API, you can define both Layer 4 and Layer 7 routing rules.

Layer 4 routing opens up essential real-world capabilities, from load-balancing TCP connections to database instances like PostgreSQL to supporting custom (low-level) protocols.

Key Resources

GatewayClass

Similar to how Ingress uses IngressClass to define its implementation, Gateway API uses the cluster-scoped GatewayClass resource to specify which type of gateway controller to use.

Gateway

The Gateway resource is the primary resource that represents a load balancer or proxy that routes traffic to a set of backend services. It contains listeners (e.g. HTTP traffic on port 80), references a GatewayClass and a set of route resources to define its routing behavior.

HTTPRoute

An HTTPRoute defines rules for handling and routing HTTP traffic, working in conjunction with a referenced Gateway resource. The Gateway acts as the entry point, while the HTTPRoute determines how that traffic should be processed and directed.

Getting Started

Let’s start with setting up a Gateway API controller in your Kubernetes cluster, we’re using Envoy Gateway in this example:

helm install eg oci://docker.io/envoyproxy/gateway-helm --version v1.2.4 -n envoy-gateway-system --create-namespace
kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available

Next, create a GatewayClass resource to define the Envoy Gateway controller:

kind: GatewayClass
apiVersion: gateway.networking.k8s.io/v1
metadata:
  name: envoy
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller

We can now create a Gateway resource to define our load balancer:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
  namespace: default
spec:
  gatewayClassName: envoy # Name of the GatewayClass resource
  listeners:
    - name: http
      protocol: HTTP
      port: 80

And an HTTPRoute to define how to route traffic to our backend services:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: route
  namespace: default
spec:
  parentRefs:
    - name: gateway # Name of the Gateway resource
  hostnames:
    - test.example.com
  rules:
    - backendRefs:
        - name: example
          port: 8000

Migrate from Ingress

Custom TLS certificate

Custom certificates were defined in the Ingress resource using the tls field while in Gateway API, this can be configured in the listeners section of the Gateway resource.

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tls-example-ingress
spec:
  tls:
  - hosts:
      - https-example.foo.com
    secretName: testsecret-tls

Gateway API

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tls-example-ingress
spec:
  gatewayClassName: example
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      certificateRefs:
      - kind: Secret
        name: testsecret-tls

Name Based Virtual hosting

While Ingress requires separate routing blocks per hostname, HTTPRoute applies a single set of rules across all specified hostnames.

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: name-virtual-host-ingress
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: service1
            port:
              number: 80
  - host: bar.foo.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: service2
            port:
              number: 80

Gateway API

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: foo-virtual-host
spec:
  parentRefs:
    - name: name-virtual-host # Assuming the Gateway resource is named name-virtual-host
  hostnames:
    - foo.bar.com
  rules:
    - matches:
      - path:
        type: PathPrefix
        value: /
    - backendRefs:
      - kind: Service
        name: service1
        port: 80

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bar-virtual-host
spec:
  parentRefs:
    - name: name-virtual-host # Assuming the Gateway resource is named name-virtual-host
  hostnames:
    - bar.foo.com
  rules:
    - matches:
      - path:
        type: PathPrefix
        value: /
    - backendRefs:
      - kind: Service
        name: service2
        port: 80

Conclusion

Gateway API is a powerful new way to manage network traffic in Kubernetes, offering a more flexible and role-oriented approach. The Kubernetes clusters we manage at brainhive are already using Gateway API to provide a more robust and scalable networking solution for our customers.

For more information, check out the official Gateway API documentation.