A Deep Dive into Cilium Gateway API: The Future of Ingress Traffic Routing

Last updated: April 2023

Introduction

Most micro-services architecture will at some point require exposing some services to the outside of the cluster and securely routing traffic into it. And while the Kubernetes Ingress API has traditionally been how platform operators route traffic into their cluster, it also suffers from a number of limitations.

The Gateway API addresses these limitations and is now supported with Cilium.

---

If you ask a hundred people what a Service Mesh is, you’re likely to get a hundred different answers. Everyone has a different interpretation of what a Service Mesh does and the problems it solves. When asked “what features of a Service Mesh interest you the most” during the Cilium Service Mesh beta, visibility and traffic encryption were overwhelmingly considered key features.

But what’s also noticeable is that half the participants responded “Kubernetes Ingress”, despite the fact some may not consider it a key component of a Service Mesh. Regardless of whether you think Ingress is a Service Mesh feature or not, it remains an essential aspect of Kubernetes traffic engineering.

This blog will review the limitations of Ingress API before providing a detailed overview of Cilium Gateway API, its use-cases and how Gateway API addresses the Ingress constraints. It will also explain how to further your knowledge with this feature.

This blog post will focus on the “what” and the “why” of the Gateway API . If you’d like to learn more about the “how”, head over to this post.

What is the Cilium Gateway API?

As we explained in the Cilium 1.13 Release blog post, the development of the Gateway API stemmed from the realisation that the Kubernetes Ingress API had some limitations.

Limited support for advanced routing:

The Ingress API supports basic routing based on path and host rules, but it lacks native support for more advanced routing features such as traffic splitting, header modification, and URL rewriting.

Limited protocol support:

The Ingress API only supports HTTP and HTTPS traffic, and does not natively support other protocols such as TCP or UDP.

The specification of Ingress API was simply too limited and not extensible enough. To address these technical limitations, software vendors and developers created vendor-specific annotations to provide these specific capabilities. But using annotations ended up creating inconsistencies from one Ingress Controller to another. This means that, if you wanted to start using a different Ingress Controller over another, you would likely face some conversion issues as annotations tend to be vendor-specific.

Operational constraints:

Finally, the Ingress API suffers from operational constraints: it simply is not well-suited for multi-team clusters with shared load-balancing infrastructure.

Gateway API: Role-oriented, portable and extensible

The Gateway API was designed from the ground up to address the Ingress API limitations. The team behind the Gateway API is a Kubernetes SIG-Network project, with, amongst them, our own Nick Young.

On the technical front, the Gateway API provides a centralized mechanism for managing and enforcing policies for external traffic, including HTTP routing, TLS termination, traffic splitting/weighting, and header modification.

Native support for these features means annotations are no longer needed to provide support for features that are commonly required for ingress traffic patterns. This means that Gateway API resources are more portable from one Gateway API implementation to another.

When customization is required, Gateway API provides several flexible models, including specific extension points to enable diverse traffic patterns. As extensions are added, the Gateway API team will keep looking for common denominators and will promote features to the API conformance to avoid going back to some of the chaos seen with extending Ingress API resources.

Finally the Gateway API implementation was designed with role-based persona in mind. The Ingress model was based on a model where it was assumed that developers managed and created Ingress and Services resources themselves.

In many of the more complex deployments however, there are various personas involved:

• Infrastructure Provider – the cloud provider (AWS, Azure, GCP) for example
• Cluster Operator – responsible for the the administration of a cluster
• Application Developer – responsible for defining application configuration and service composition

By decomposing the Ingress API into several Gateway API objects, personas will be assigned the right access and privileges that their responsibilities require.

For example, application developers in a specific team would be allowed to create Route objects in a specified namespace but would not be able to modify the Gateway configuration or edit Route objects in namespaces other than theirs.

Reducing the tool sprawl

What we keep hearing from users is that they are facing a tool sprawl: when deploying complex micro-services architecture, operators have typically needed to deploy a CNI, a Network Policy engine, a Service Mesh for observability or for encryption, an Ingress or Gateway API controller, etc…

This can become an operational headache to upgrade and manage.

Cilium enables users to consolidate the number of cloud native networking and security tools they have – because Cilium natively supports not just Gateway API but the sidecar-less Service Mesh, Transparent Encryption, Network Policies, built-in observability with Hubble, etc…

It just makes life easier for cluster operators : they just need a single tool to manage and upgrade for many if not all their Kubernetes networking needs.

To learn more about the benefits of Cilium Service Mesh, check out this post and to get started with traffic encryption with Cilium, try out this lab or read this tutorial.

Use cases

There are several use cases already possible with the Cilium Gateway API. This section will be expanded over the coming months as additional features are added to Cilium.

HTTP Routing

HTTP routing is the process of directing incoming HTTP requests to the appropriate backend service. With the Gateway API, users can define routes based on the incoming request’s HTTP method, URL path, and headers. For example, you could route all GET requests to one backend service, while routing all POST requests to another.

To configure HTTP routing in Cilium, you first define a Gateway object, which represents the entry point for all incoming traffic. Then, you create a HTTPRoute object, which defines the routing rules for incoming HTTP requests. A HTTPRoute can include multiple route rules, each of which specifies a different backend service to send traffic to.

Here’s a short video of how Cilium helps with HTTP routing into a Kubernetes cluster:

TLS Termination

TLS termination is the process of decrypting incoming TLS traffic at the gateway and forwarding it to the appropriate backend service over an unencrypted connection. The Cilium Gateway API includes built-in support for TLS termination, allowing users to easily secure incoming traffic into their Kubernetes clusters.

To configure TLS termination in Cilium, you define a Gateway object with a TLS configuration. The TLS configuration includes the certificate and private key used to encrypt and decrypt the incoming traffic. You can then configure your HTTPRoute objects to use the TLS-enabled Gateway object to secure incoming traffic.

Here is a short demo of how Cilium implements TLS Termination for inbound traffic:

HTTP Traffic Splitting / Weighting

HTTP traffic splitting is the process of sending incoming traffic to multiple backend services, based on predefined weights or other criteria. The Cilium Gateway API includes built-in support for traffic splitting, allowing users to easily distribute incoming traffic across multiple backend services. This is very useful for canary testing or A/B scenarios.

To configure traffic splitting in Cilium, you define a Gateway object with multiple backend services, each with its own weight. You can then set up various weights in your HTTPRoute objects, specifying the percentage of traffic to send to each backend service.

Here’s a short video of how Cilium provides HTTP Traffic Splitting:

HTTP Request Header Modification

HTTP header modification is the process of adding, removing, or modifying HTTP headers in incoming requests. The Cilium Gateway API lets users easily customize incoming traffic to meet their specific needs.

To configure HTTP header modification in Cilium, you define a Gateway object with one or more HTTP filters. Each filter specifies a specific modification to make to incoming requests, such as adding a custom header or modifying an existing header.

Here’s a short video showing how Cilium can add a header to a HTTP packet:

HTTP Response Header Modification

Just like editing request headers can be useful, the same goes for response headers. For example, it allows teams to add/remove cookies for only a certain backend, which can help in identifying certain users that were redirected to that backend previously.

Another potential use case could be when you have a frontend that needs to know whether it’s talking to a stable or a beta version of the backend server, in order to render different UI or adapt its response parsing accordingly.

Here’s a short video showing how Cilium can add a header to a HTTP response:

Cross Namespace Routing Support

The Gateway API has core support for cross Namespace routing. This is useful when more than one user or team is sharing the underlying networking infrastructure, yet control and configuration must be segmented to minimize access and fault domains.

Gateways and Routes can be deployed into different Namespaces and Routes can attach to Gateways across Namespace boundaries. Gateway and Route attachment is bidirectional – attachment can only succeed if the Gateway owner and Route owner owner both agree to the relationship.

This effectively creates a handshake between the infra owners and application owners that enables them to independently define how applications are exposed through Gateways.

It results in creating a policy that reduces administrative overhead. App owners can specify which Gateways their apps should use and infra owners can constrain the Namespaces and types of Routes that a Gateway accepts. An example cross-namespace architecture using a Shared Gateway API is represented below (you can test this specific scenario in the Advanced Gateway API lab).

Here is a short video that walks through the benefits of Cross-Namespace Routing with the Gateway API, followed by a demo:

Migrating to the Gateway API

For users interested in migrating from Ingress API to Gateway API, we have tested the experimental Ingress2Gateway tool that helps users migrate their Ingress configuration to Gateway API configuration. While still a prototype, the tool accurately converted simple Ingress Resources to Gateway API Resources.

Watch this brief video to learn more:

Getting Started

You have several options at your disposal to get started with the Cilium Gateway API:

Official Docs

Find the official docs on Gateway API here.

Tutorial

Read our walkthrough of Gateway API in this detailed post.

Labs

The Cilium Gateway API lab is a hands-on experience for users to learn how to deploy and use Cilium Gateway API. The lab covers topics such as deploying Cilium, deploying the Gateway API, and configuring HTTP routing and TLS termination.

On completion, you will receive a Silver Badge – feel free to share your achievement with your peers on social media!

Once you’ve completed this first lab, you now can take a follow-up lab: the Cilium Advanced Gateway API Use Cases lets you explore HTTP Header Request and Response modifications, Traffic Splitting and Cross-Namespace Routing. On completion of this lab, you will receive a Gold Badge:

The Future of the Gateway API

In conclusion, the Cilium Gateway API provides a consistent, flexible and role-oriented model to bring traffic into your Kubernetes cluster. But there’s much more to come.

While the Cilium Gateway API is already fully conformant with Gateway API v0.5.1, there are several features we are working towards:

• UDP Route (to route UDP traffic into your cluster)
• TCP Route (to route TCP traffic into your cluster, for non-HTTP traffic)
• gRPC Route (to route gRPC traffic into your cluster)

The Gateway API team is not resting on their laurels either: the Gateway API has now moved to v0.6.0 (note the main Cilium branch has already moved to said API version (PR)), v0.7.0 is due for May 2023 and v1.0 is expected before October 2023.

We are also particularly looking forward to the Gateway API team’s initiative around East-West micro-services connectivity (GAMMA) and will stay closely involved as GAMMA evolves and matures.

Thanks for reading.