Revolutionize Your Kubernetes Experience with Easegress: Kubernetes Gateway API


This article aims to briefly present to the readers the core concepts, usage methods, and prospects of the next standard for traffic entry in the Kubernetes community, the Gateway API [1]. In this process, we will also show how Easegress, as a modern gateway, implements the Gateway API, and provide the current best practices. We will focus on the core concepts and their usage, rather than comprehensively introducing various abstract concepts, we will provide links at appropriate places for reference.

Quick Understanding

On the 1st of November, the official Kubernetes released the Kubernetes Gateway API version v1.0.0, setting it to GA. So, what exactly is this Gateway API? In a nutshell: It addresses the shortcomings of Ingress. In August 2020 with the release of Kubernetes v1.19, Ingress officially became GA, establishing itself as the standard for Kubernetes traffic entry (primarily for the HTTP protocol). It supports basic HTTP routing rules, but HTTP, being the core protocol of the internet, has very diverse and complex cases. The simple design and lack of scalability of Ingress are unable to meet the increasing traffic needs of various services running on Kubernetes. For example, the Gateway API supports multiple protocols, among which HTTPRoute can be used to compare with the Ingress definition. Let’s look at a simple example to see what differences they have:

kind: Ingress
  name: basic-ingress
  - host:
      - path: /serviceA
        pathType: Prefix
            name: service-a
              number: 80

kind: HTTPRoute
  name: header-based-routing
  - matches:
    - headers:
      - name: Custom-Header
        value: "HeaderValue"
    - serviceName: special-service
      port: 80
  - matches:
    - path:
        type: PathPrefix
        value: /serviceA
    - serviceName: service-a
      port: 80

As we can see, what Ingress can accomplish through path prefix matching, HTTPRoute can also achieve. However, the matching of HTTP Headers, which HTTPRoute can accomplish, is not defined in the standard of Ingress.

Shortcomings of Ingress and Enhancements of Gateway API

We have listed the corresponding features and enhancement strategies of Ingress and Gateway API in the table below:

Capability/FeatureIngress CapabilityGateway API Capability
Routing ComplexitySupport basic HTTP routing based on path and hostnameSupport advanced routing strategies, such as routing based on headers, query parameters, and weighted routing
Routing ExtensibilitySupport through specific Annotations of Ingress Controllers (configuration is key-value pairs)Extended by developing Filters (configuration is a custom YAML structure)
StandardizationImplementation differences exist among different Ingress ControllersProvides a common specification, supported across various implementations
Role-Based Access ControlNatively does not support different teams to manage different parts of the configurationAllows each team to manage their traffic, while cluster operators set policies
Implementation ConsistencyImplementation may vary with different Ingress controllers, leading to consistency issuesProvides more standardized specifications, reducing differences between implementations and enhancing consistency
Traffic ControlBasic traffic control capabilities, such as load balancing and basic routingIncludes advanced traffic control features, like request redirects and rewrites, header modifications, traffic splitting, etc.
Configuration ManagementConfiguration is simpler but can become cumbersome in complex scenariosProvides clearer configuration management, supporting better abstraction and separation of responsibilities
Protocol SupportThe standard only supports HTTP/HTTPSNatively supports more protocols, such as HTTP/HTTPS, gRPC, TLS, TCP/UDP
Adaptability in Large-Scale EnvironmentsManaging and scaling in large systems can be challengingDesigned to handle large-scale, complex environments, offering better flexibility and scalability

HTTPRoute Detailed Explanation

Below, we will present all the main parts of HTTPRoute using a complete YAML file.

kind: HTTPRoute
  name: comprehensive-httproute
  # Specify the domain names to which this HTTPRoute applies
    - ""

  # Define the routing rules.
    # Any one of the sub rules matches counts as a successful match
    - matches:
        # Route based on Path prefix
        - path:
            type: PathPrefix
            value: /serviceA
        # Route based on Headers
        - headers:
            - name: Custom-Header
              value: "HeaderValue"
      # Weighted traffic split: Split traffic between two services.
        - serviceName: service-a
          port: 80
          weight: 50
        - serviceName: service-a-alt
          port: 80
          weight: 50
      # Filters for modifying requests and mirroring traffic
        # Modify request headers by setting custom headers.
        - type: RequestHeaderModifier
              - name: My-Custom-Header
                value: MyValue
        # Mirror traffic to an additional service for test or debugging.
        - type: RequestMirror
            serviceName: mirror-service
            port: 8080

    # Second rule starts here
    - matches:
        # Route based on precise Path
        - path:
            type: Exact
            value: /serviceB
        - queryParams:
            - name: mode
              value: strict
      # Route all matching traffic to service-b.
        - name: service-b
          port: 80
      # Filter for URL rewriting.
        # Rewrite the request's Hostname.
        - type: URLRewrite
            hostname: elsewhere.example

As we can see, its core is divided into three parts:

  • matches (traffic entrance): includes Hostname, Path, Headers, Query parameters
  • Filters (traffic control):
    • RequestHeaderModifier: Modify HTTP request headers. Can add, remove, or update HTTP request headers
    • ResponseHeaderModifier: Similar to RequestHeaderModifier, but for HTTP response headers. This filter can add, remove, or update HTTP response headers.
    • RequestMirror: Mirrors/copies incoming requests to a specified backend (service), mirrored traffic is often used for logging, testing, or debugging
    • URLRewrite: Rewrite the incoming request’s URL, can modify the domain and path of the request URL
    • RequestRedirect: incoming requests to a specified URL. Used for HTTP to HTTPS redirects, or redirects to a different domain or path
    • ExtensionRef: Reference a custom Filter, this Filter allows you to implement behaviors that may not be covered by the standard filter collection
  • forwardTo/backendRefs (traffic exit): Choose the corresponding Kubernetes Service as needed

Gateway API from Administrator Perspective

After familiarizing ourselves with the core entity HTTPRoute, let’s look at why the Gateway API is different from Ingress from the perspective of an administrator/deployer[2].

It can be seen that the Gateway API has an additional layer of entity, the GatewayClass, compared to Ingress’s flat design. The Gateway is the actual running instance equivalent to the Ingress Controller, but it can have different types of instances, offering more flexibility and extensibility. We can see this from their definitions:

  • GatewayClass
    • Defines a set of gateways: GatewayClass is a cluster-scope resource that defines a set of gateways with common configuration and behavior. It is akin to a “type” or “class” of gateway.
    • Allows for broader customization and extensibility than Ingress, as different GatewayClass resources can be defined for different types of gateways.
  • Gateway
    • Represents an actual gateway instance.
    • Administrators can create multiple Gateway resources based on the same GatewayClass, each with specific settings such as listeners, ports, and protocols. Entities like HTTPRoute can then select the corresponding Gateway instance.
    • Multi-tenancy: Different teams can use different Gateway instances for their applications, achieving multi-tenancy and isolation.

Clearly, this is a role-based resource design: Gateway allows for more fine-grained control and separation, distinguishing who manages the infrastructure (GatewayClass) and who manages application-level routing (Gateway and routing resources).

The combination of GatewayClass and Gateway in the Gateway API makes the management of ingress and egress traffic in Kubernetes more scalable, flexible, and efficient. This approach is particularly beneficial in complex, large-scale, and multi-tenant environments, where the requirements exceed the capabilities of traditional Ingress."

Easegress Adaptation and High Extensibility

After the release of the v1 version of the Gateway API, Easegress quickly adapted to the latest version [3]. As one of the fastest gateways to reach GA [4], Easegress was able to rapidly implement the standards of the Gateway API during the adaptation process. This is because the standards of the Gateway API and the design of Easegress coincide in many ways, and conceptually, they mostly correspond to each other:

  • Gateway entity: Corresponds to Easegress’s TrafficGate (HTTPServer, GRPCServer).
  • HTTPRoute entity: Corresponds to Easegress’s Pipeline, where the Filters in it have almost a one-to-one correspondence with Filters in Easegress to implement their functionalities.

Thus, in the development of adapting to the Gateway API, our core task was simply to translate the configuration of the Gateway API into corresponding Easegress configurations. Additionally, as Easegress is a cloud-native gateway product that centralizes traffic orchestration as a core feature, we provide extensive infrastructure for the development of Filters [5]. Therefore, if developers need to implement custom functionalities within the standards of the Gateway API, they can directly develop an Easegress Filter. Then, add the translation code in the Gateway Controller’s Object and finally reference the Filter in ExtensionRef.

Activating the Superpowers of Kubernetes Gateway: One-Click Integration with Easegress for Rate Limiting, Circuit Breaking, and Retries

Easegress, as a cloud-native gateway solution, not only supports the core functionalities of the Kubernetes Gateway API but also offers a range of advanced features such as rate limiting, circuit breaking, and retries. Now, through the extensionRef feature in the Kubernetes Gateway API, you can easily integrate all of Easegress’s filters and resilience policies (like circuit breaking and retry strategies) into your Kubernetes environment without writing any code. This means that with just a few simple configurations, you can leverage the advanced capabilities of Easegress to optimize and strengthen your Kubernetes network management. In “Enhancing K8s Gateway API with Easegress Without Changing a Single Line of Code”, we will show you in detail how to efficiently implement all these features!

The Future of Easegress with the Gateway API Standard

Clearly, the Gateway API is the next standard for traffic on Kubernetes, and as Easegress is a cloud-native modern gateway with traffic orchestration at its core, we will keep up with the standards of the Gateway API and also improve and expand the standards based on our experiences in production practices.

The release of Gateway API v1 is just the beginning; many other features are still in the discussion and experimental stages (such as timeouts, specific backend protocols, etc.). Easegress will also gradually implement other features like GRPCRoute in the future.