Gateway API – Part 1 – An Introduction

This is the first article of a series about the Kubernetes Gateway API.

In case you missed it, Gateway API has reached v1.0 GA Release in October of 2023, while around the same time, the well-established Ingress API Object was frozen. We can infer from this that Gateway API is officially replacing Ingress. But don’t panic — Ingress will still be available, it just won’t be further developed.

A Review of Ingress

To better understand the Gateway API, it’s useful to first review some basic Ingress concepts.

Recall that an Ingress describes the desired state of how external traffic should be routed to services within the cluster. Kubernetes, however, has no native Ingress implementation. In other words, Kubernetes itself does not handle the network routing or load balancing described by Ingress.

To actually make an Ingress do something, you need to select and install an external component known as an Ingress controller. Popular Ingress controllers include the AWS Load Balancer Controller, Nginx-Ingress Controller, Kong and many others. This is why they say Ingress is “portable” — anyone can write software that implements the Ingress API standard.

Using an Ingress, you can define rules for routing traffic to services using hosts and paths (layer 7 routing):

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

When you create an Ingress object, the Ingress controller will detect it and begin setting up the desired network routing. Depending on the Ingress controller used, this could mean different things — such as provisioning an AWS loadbalancer or dynamically updating routes on an instance of nginx-ingress.

So what’s the problem with Ingress? A few problems have emerged over time:

1. Ingress describes a limited set of rules for routing traffic. Vendors often need to extend functionality with annotations, which breaks portability.
2. As a namespaced object, an Ingress was designed to only route traffic for services in the same namespace as the Ingress.
3. An Ingress is a single object, which does not promote sharing responsibilities for different parts of the network routing. We can also say Ingress is not “role-oriented”.

Ingress is also lacks some features commonly used today, such as:

• Timeouts
• Whitelisting/blacklisting IPs
• Path rewriting
• Header manipulation
• Authentication configuration
• Weighted routing
• Rate limiting

Last but not least, popular Kubernetes networking solutions such as Istio can not only provide more advanced Ingress features, but also route traffic between services inside a Kubernetes cluster — via a service mesh. Istio’s Ingress does not rely on the Kubernetes Ingress API object.

Say Hello To Gateway API

The Gateway API is the brainchild of the SIG-NETWORK community (SIG = special interest group). They are responsible for the components, interfaces, and APIs which expose networking capabilities to Kubernetes users and workloads.

The new Gateway API takes the learnings from various Kubernetes ingress implementations, including Istio, to build a standardized vendor neutral API. In fact, you could say the Gateway API was heavily inspired by Istio, with many common concepts and objects.

This Istio article describes the similarities and differences between Istio and the Gateway API in more detail. Istio also plans on implementing the Gateway API as the default API for traffic management in the future.

Another key design principle of the Gateway API is its “role-based” architecture. One drawback of the Ingress API object is that the Ingress definition is confined to a single object, meaning a single configuration manifest.

In many organizations, however, different roles are responsible for the different components involved in managing traffic into Kubernetes. For example:

• a security team might be responsible for provisioning the TLS certificates
• cluster administrators handle network policies and management of the load balancer
• application developers know best how to configure routes to their services

To improve the ability of these different roles to manage different components independently, Gateway API is divided into different resources:

Another improvement of Gateway API over Ingress is that it was designed to handle not only traffic from outside the cluster to inside the cluster (north/south), but also traffic between services (mesh) and between Kubernetes clusters (east/west).

Furthermore, to address the problem of vendors needing to extend Ingress configuration using annotations, Gateway API was designed to be extensible at various layers of the API, using cluster-scoped or namespace-scoped custom resources.

Some commonly used configuration attributes that were missing from Ingress have been added to the Gateway API. For example, Ingress does not have a way to configure timeouts and are often implemented as annotations:

kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-config
  namespace: nginx-ingress
data:
  proxy-connect-timeout: "10s"
  proxy-read-timeout: "10s"
  client-max-body-size: "2m"

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: timeout-example
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /timeout
    timeouts:
      request: 10s
      backendRequest: 2s
    backendRefs:
    - name: timeout-svc
      port: 8080

Whereas the Gateway API’s HTTPRoute resource allows the configuration of different HTTPRouteTimeouts for incoming requests and backend requests. The expanded configuration fields in the Gateway API spec will enhance its portability and simplify users’ lives, as there will no longer be a need to consult vendor documentation to find the correct annotation — if one is even provided.

Similarities between Gateway API and Ingress

Similar to the Ingress API object, Gateway API objects only describes how traffic is handled. Kubernetes does not natively implement any resources when the objects are created. Instead, you will also need to select and install a Gateway API controller or other software that implements the Gateway API resources. There are already many implementations available now and the list is growing.

Gateway API can also be used to expose Kubernetes services with simple routing based on hostnames and paths (layer 7), but offers many more options and can easily be extended as your routing needs grow.

This wraps up the first article of this series. If this article was helpful, please let me know or give me a “like”.