Demystifying the Kubernetes Gateway API: What the heck is it and why should you care?

When Gateway API debuted in October last year, this concluded a nearly four-year-long process that started in summer 2019. Gateway API is the successor of core Ingress definition, aiming towards various goals. This blog post will give a brief overview of its history, the whys, and how it's done today.

Brief history

I remember this as though it happened yesterday: Prior to KubeCon NA San Diego 2019, known folks within the SIG Network started discussing and pitching this "crazy" idea of a new concept for Ingress Management on Kubernetes. This time, vendors of Ingress Controllers were taken into discussion early on, to help craft a spec that would support everyone in reaching one of the many common goals; Remove Ingress annotation spread and allowed for better separation of concerns. During said KubeCon, the new idea was proposed to the public audience: Gateway API.

From then on, multiple vendors took part in that journey of designing this new standard, the successor of traditional Ingress eventually hitting v1alpha1 in April 2021 and finally hitting GA right in time for the last Kubecon NA. It is now ready for production use and intended to regulate the flow of traffic from external clients to services within the cluster, known as the ingress or north/south scenario. Nevertheless, the Gateway API is increasingly favored for handling inter-service (east/west) traffic, owing to GAMMA, an experimental project undergoing trials across various implementations.

Why

The Ingress API lacks numerous functionalities necessary for fulfilling common routing needs. It cannot match patterns based on query string parameters or define Layer 4 (protocol based, such as TCP, UDP or similar) routing. Similarly, it lacks capabilities for matching based on headers or HTTP methods. This deficiency in out-of-the-box API features has compelled API implementations to devise custom mechanisms atop the API, such as annotations and decorators.

Consequently, this situation has given rise to what is commonly referred to as "Ingress API annotation hell." While one may learn to navigate the Ingress API, it only covers roughly 20% of what is necessary for success. Transitioning from one provider to another without relearning everything becomes a daunting task.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.org/proxy-connect-timeout: "30s"
    nginx.org/proxy-read-timeout: "20s"
    nginx.org/client-max-body-size: "4m"
    ...
spec:
  ingressClassName: nginx-example
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: Prefix
        backend:
          service:
            name: test
            port:
              number: 80

Alternatively, ingress controllers such as Traefik, Gloo Edge or others introduced their own set of CRDs to overcome that issue.

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: testName
  namespace: default
spec:
  entryPoints:
    - web
  routes:
  - kind: Rule
    match: Host(`test.example.com`)
    middlewares:
    - name: middleware1
      namespace: default
    priority: 10
    services:
    - kind: Service
      name: foo
      namespace: default
      passHostHeader: true
      port: 80
      responseForwarding:
        flushInterval: 1ms
      scheme: https
      sticky:
        cookie:
          httpOnly: true
          name: cookie
          secure: true
      strategy: RoundRobin
      weight: 10
  tls:
    certResolver: foo
    domains:
    - main: example.net
      sans:
      - a.example.net
      - b.example.net
    options:
      name: opt
      namespace: default
    secretName: supersecret

While this works to enable users, it's by far not optimal. This not only entails some sort of vendor lock-in, but it also means dropping out of usability with various community-maintained tools within the ecosystem, since those tools do not necessarily understand vendor-specific resources.

The Gateway API addresses this issue effectively. Apart from fulfilling core routing requirements, the Ingress API's permission model proves inadequate for practical usage. The Gateway API significantly enhances the permission model by introducing a new API layer (Routes), which segregates tasks associated with different personas involved in managing the cluster's lifecycle. Also, the number of open-source projects supporting Kubernetes Gateway API is growing rapidly, creating a robust open ecosystem for features and capabilities for Gateway API users.

How

Since Gateway API by itself has more layers, the structure looks a little different:

This separation allows for a very role-oriented design allowing multiple personas to fulfill their relevant use cases.

Through the separation of Gateways and Routes, operators still have full control of very common settings such as TLS while individual development teams can fully focus on their routing needs.

In terms of routing, the Gateway API brought about significant enhancements to the Ingress API across various topics. One notable improvement is the introduction of separate APIs for Routes. By dissociating routes from the ingress, the Gateway API enabled the incorporation of multiple route types (Layer 4 and Layer 7 such as HTTP), paving the way for the future introduction of additional routes. As of now, the Gateway API supports the following route types (with varying levels of maturity, as denoted in parentheses):

• HTTPRoute (v1)
• GRPCRoute (v1alpha2)
• TLSRoute (v1alpha2)
• TCPRoute (v1alpha2)
• UDPRoute (v1alpha2)

In addition to these Routes, the Gateway API has added brand-new routing capabilities to enable users.

• HTTP Header Matching
• HTTP Method Matching
• HTTP Query Parameters matching

HTTP Route backend weights

The Weight attribute in a HTTPRoute backendRef determines the proportion of requests directed to the referenced backend. This is calculated as the weight divided by the amount of all weights in the BackendRefs list. For example, if Service A has a weight of 20 and Service B has a weight of 10, approximately two thirds of the requests will be routed to Service A. This is useful for scenarios such as canary deployments.

HTTP Route Filters

HTTP Route Filters are the new standard approach to configure additional behavior such as modifying request headers or enabling request mirroring. Different types of filters exist as of today, including the option to attach custom filters to the rule via an ExtensionRef field. This can be used by various Ingress Controllers to hook into their extended usage such as middlewares in Traefik or plugins in Kong.

Cross-namespace references

Unlike in the basic Ingress API, it is now possible to reference objects in another namespace. This enables common best-practices the community has asked for, such as a Gateway and Route in Namespace abc reference a service in Namespace cde or a Route in Namespace B configures a Gateway in Namespace C.

Extensions

Another huge differentiator is the official way to extend the Gateway API to add functionalities. Vendors can use the PolicyAttachment specification to directly attach policies to configure there own custom behaviour. Alternatively, there is a way to 'inherit' Policies from meta resources porting to routs.

Traction to know

The number of open-source projects supporting Kubernetes Gateway API is growing rapidly, ensuring an open ecosystem for features and capabilities for Gateway API users. As of today, multiple well-known projects such as external-dns, cert-manager, Argo Rollouts and more have already adopted Gateway API as a way to configure their respective features.

What's more, there are the 24 different implementations from vendors listed on the official docs as well.

Conclusion & next up

The Gateway API stands out as a very collaborative API in the history of Kubernetes. Multiple community members as well as vendors contributed tremendous efforts to this specification, ensuring its longevity as a standard for years to come. Since Gateway API is now Generally Available, it's officially deemed production-ready.

As a close follow up to this post, we will take the Gateway API for a hands-on spin, combining it with multiple other open-source solutions, thereby showcasing its great capabilities and ease of integration.