How Easegress Implements API Gateway Functionality Using the Kubernetes Gateway API

Easegress implements API gateway functionality by watching Kubernetes Gateway API resources and translating them into native Easegress pipeline and HTTP server specifications, which are then applied to the traffic plane via the TrafficController.

Easegress is a Cloud Native API gateway that provides high-performance traffic management for cloud-native applications. The platform implements its API gateway capabilities through deep integration with the Kubernetes Gateway API, converting declarative Gateway and HTTPRoute resources into executable Easegress configurations. This architecture allows Easegress to function as a Kubernetes-native API gateway while maintaining its high-performance pipeline-based traffic processing engine.

Core Architecture of the Easegress API Gateway

The Easegress API gateway implementation consists of four primary components that work together to translate Kubernetes Gateway API resources into runtime traffic management configurations.

GatewayController: The Orchestration Engine

The GatewayController serves as the primary orchestration component for the Easegress API gateway implementation. Located in pkg/object/gatewaycontroller/gatewaycontroller.go, this controller initializes the Kubernetes client, launches the watch loop, and coordinates the translation of Gateway API resources into Easegress native specifications. The controller's Init method creates the k8sClient and starts a goroutine running the main event loop that continuously reconciles the desired state with the runtime configuration.

Kubernetes Integration Layer

The Kubernetes integration is handled by the k8sClient in pkg/object/gatewaycontroller/k8s.go. This component enforces a minimum Kubernetes version of v1.23 required by the Gateway API through the checkKubernetesVersion function. The client creates informers for Gateway API resources including Gateways, HTTPRoutes, Services, Endpoints, Secrets, and the custom FilterSpec CRD. All events are funneled into a buffered eventCh channel, ensuring that every change triggers a complete re-translation of the configuration.

SpecTranslator: Gateway API to Easegress Native

The translation logic resides in pkg/object/gatewaycontroller/translator.go within the specTranslator struct. This component converts Kubernetes Gateway API objects into Easegress-specific configurations through three main stages:

• TLS Configuration: The getTLS function retrieves certificates from Kubernetes Secrets or custom FilterSpec resources.
• HTTP Server Generation: The httpServerSpecs method builds httpserver.Spec objects for each Gateway listener, attaching TLS configuration when present.
• Pipeline Construction: The pipelineSpecs method creates pipeline.Spec objects for each HTTPRoute rule, implementing hostname and path matching, backend service routing, and optional filter chain insertion.

TrafficController: Runtime Application

The TrafficController in pkg/object/trafficcontroller/trafficcontroller.go serves as the bridge between the translated specifications and the running Easegress data plane. The GatewayController invokes two critical methods:

_, err = gc.tc.ApplyPipelineForSpec(gc.namespace, spec)
_, err = gc.tc.ApplyTrafficGateForSpec(gc.namespace, spec)

ApplyPipelineForSpec registers the pipeline in the runtime, while ApplyTrafficGateForSpec creates a listening HTTP server bound to the ports defined in the Gateway listener.

Translation Workflow: From Kubernetes Gateway API to Easegress Pipelines

The Easegress API gateway processes Gateway API resources through a continuous reconciliation loop:

1. Initialization: The GatewayController.Init method establishes the Kubernetes client connection and launches the main processing goroutine.

2. Resource Watching: The k8sClient.watch method registers informers for all Gateway API resources. When any Gateway, HTTPRoute, Service, Endpoint, Secret, or FilterSpec changes, the handler pushes the event onto the eventCh channel.

3. Specification Translation: Upon receiving an event, GatewayController.translate instantiates a new specTranslator and calls translate(). This process retrieves the current set of Gateway API resources from the cluster and generates httpServerSpecs for each Gateway listener and pipelineSpecs for each HTTPRoute rule, wiring routes to backend services or filter chains while handling TLS via Secrets or FilterSpec objects.

4. Runtime Application: The translated specifications are applied via the TrafficController using ApplyPipelineForSpec and ApplyTrafficGateForSpec, creating HTTP servers and pipelines that implement the desired routing and traffic management rules.

5. Cleanup: The controller enumerates existing pipelines and HTTP servers under its namespace, removing any that no longer correspond to active Gateway resources. This ensures stale configurations are automatically purged.

Practical Implementation: Deploying a Gateway in Easegress

To utilize the Easegress API gateway functionality, deploy standard Kubernetes Gateway API resources. The controller automatically detects and translates these configurations.

Example Gateway Manifest:

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: demo-gw
  namespace: default
spec:
  gatewayClassName: megaease.com/gateway-controller
  listeners:
  - name: http
    protocol: HTTP
    port: 80
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      certificateRefs:
      - name: demo-tls-secret
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: demo-route
  namespace: default
spec:
  parentRefs:
  - name: demo-gw
  hostnames: ["demo.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api
    forwardTo:
    - serviceName: backend-svc
      port: 8080

When applied, the Easegress API gateway creates an HTTP server listening on ports 80 and 443 (with TLS sourced from demo-tls-secret), and a pipeline routing demo.example.com/api/* to the Kubernetes Service backend-svc:8080.

Verifying the Generated Configuration:

Use egctl to inspect the translated Easegress configurations:

# List pipelines created by the gateway controller

egctl get pipelines --namespace default/gatewaycontroller

# List HTTP servers (traffic gates) created by the gateway controller

egctl get httpservers --namespace default/gatewaycontroller

The output displays pipeline names derived from HTTPRoute resources (e.g., demo-route-pipeline) and HTTP-server specs named after listeners (e.g., demo-gw-http, demo-gw-https).

Key Source Files and Implementation Details

The Easegress API gateway implementation spans several critical source files:

File	Purpose
pkg/object/gatewaycontroller/gatewaycontroller.go	Main controller lifecycle including initialization, translation orchestration, and cleanup logic.
pkg/object/gatewaycontroller/k8s.go	Kubernetes client wrapper, version checking (minimum v1.23), informer registration, and event channel management.
pkg/object/gatewaycontroller/translator.go	Core translation logic converting Gateway API resources to Easegress pipeline.Spec and httpserver.Spec objects.
pkg/object/trafficcontroller/trafficcontroller.go	Runtime interface for applying pipeline and HTTP server specifications to the active data plane.

These files collectively implement the complete API gateway stack, from Kubernetes resource observation through specification translation to runtime traffic management.

Summary

• Easegress implements API gateway functionality by integrating with the Kubernetes Gateway API, translating declarative Gateway and HTTPRoute resources into native Easegress configurations.
• The GatewayController orchestrates the process by watching Kubernetes resources via the k8sClient and triggering re-translation on every change.
• The specTranslator converts Gateway API objects into httpserver.Spec (listeners) and pipeline.Spec (routing rules), handling TLS termination, path matching, and backend service resolution.
• The TrafficController applies these specifications to the runtime data plane, creating HTTP servers and pipelines while automatically cleaning up stale configurations.
• Minimum Kubernetes version v1.23 is required to support the Gateway API specifications used by Easegress.

Frequently Asked Questions

How does Easegress differ from other Kubernetes API gateways?

Easegress distinguishes itself by translating Gateway API resources into its high-performance pipeline architecture rather than using traditional reverse proxy configurations. According to the Easegress source code in pkg/object/gatewaycontroller/translator.go, the platform converts HTTPRoute rules into native pipeline specifications that leverage Easegress's built-in filter chain system. This approach provides more flexible traffic manipulation and processing capabilities compared to standard ingress controllers that typically rely on static configuration files.

What Kubernetes versions are supported by the Easegress API gateway?

The Easegress API gateway requires Kubernetes v1.23 or higher. This requirement is enforced in pkg/object/gatewaycontroller/k8s.go through the checkKubernetesVersion function, which validates the cluster version before initializing the Gateway API informers. This minimum version ensures compatibility with the Gateway API v1 specification used by the controller, particularly for the resource types and field definitions required by the translation logic.

How does Easegress handle TLS termination for Gateway API resources?

Easegress handles TLS termination by translating Gateway certificateRefs into Easegress HTTPS server configurations. In pkg/object/gatewaycontroller/translator.go, the getTLS function retrieves certificates from Kubernetes Secrets or custom FilterSpec resources. These certificates are then attached to the httpserver.Spec objects created for HTTPS listeners during the httpServerSpecs generation phase. The TrafficController subsequently configures TLS termination at the entry point when applying the traffic gate specifications.

Can I observe the translated Easegress configurations generated from Gateway API resources?

Yes, you can inspect the generated configurations using the egctl command-line tool. After applying Gateway API manifests, run egctl get pipelines --namespace default/gatewaycontroller to view the translated pipeline specifications, and egctl get httpservers --namespace default/gatewaycontroller to see the HTTP server configurations. These commands reveal how HTTPRoutes become pipelines (e.g., demo-route-pipeline) and how Gateway listeners become HTTPS server instances (e.g., demo-gw-https), providing full visibility into the translation process managed by the GatewayController.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}