Gateway API for Layer 7 (ALB) Implementation¶

This section details the AWS Load Balancer Controller's (LBC) architecture and operational flow when processing Gateway API resources for Layer 7 traffic utilizing an AWS ALB.

Gateway API Resources and Controller Architecture¶

The LBC implements Gateway API support through a dual architecture, using distinct controller instances for Layer 4 (L4) and Layer 7 (L7) routing. This design allows for specialized and optimized reconciliation aligned with the underlying AWS Load Balancer capabilities.

The LBC instance dedicated to L7 routing monitors the following Gateway API resources:

GatewayClass: For L7 routing, the LBC specifically manages GatewayClass resources with the controllerName set to gateway.k8s.aws/alb.
Gateway: For every gateway that references a GatewayClass with the controllerName set to gateway.k8s.aws/alb, the LBC provisions an AWS ALB.
HTTPRoute: Defines HTTP-specific routing rules, enabling HTTP communication between the load balancer and backend targets. These routes are handled by an AWS ALB.
GRPCRoute: Defines GRPC-specific routing rules, enabling GRPC communication between the load balancer and backend targets. These routes are handled by an AWS ALB.
ReferenceGrant: Defines cross-namespace access. For more information, see
LoadBalancerConfiguration (LBC CRD): A Custom Resource Definition utilized for fine-grained customization of the provisioned ALB. This CRD can be attached to a Gateway or its GatewayClass. For more information, please refer to How customization works.
TargetGroupConfiguration (LBC CRD): A Custom Resource Definition used for service-specific customizations of AWS Target Groups. This CRD is associated with a Kubernetes Service. For more information, please refer to How customization works.
ListenerRuleConfiguration (LBC CRD): A Custom Resource Definition used for rule-specific customizations of AWS Listener Rules. This CRD is associated with one or more HTTPRoute or GRPCRoute to provide functionality supported by AWS ALB, but not natively available within the Gateway API. For more information, please refer to Advanced Configuration.

The Reconciliation Loop¶

The LBC operates on a continuous reconciliation loop within your cluster to maintain the desired state of AWS Load Balancer resources:

Event Watching: The L7-specific controller instance constantly monitors the Kubernetes API for changes to the resources mentioned above related to ALB provisioning.
Queueing: Upon detecting any modification, creation, or deletion of these resources, the respective object is added to an internal processing queue.
Processing:
- The controller retrieves the resource from the queue.
- It validates the resource's configuration and determines if it falls under its management (e.g., by checking the GatewayClass's controllerName). If it does, it enqueues the relevant gateway for processing.
- The Kubernetes Gateway API definitions are then translated into an equivalent desired state within AWS (e.g., specific ALB, Listeners, Listener Rules, Target Groups, Addons, etc).
- This desired state is compared against the actual state of AWS resources.
- Necessary AWS API calls are executed to reconcile any identified discrepancies, ensuring the cloud infrastructure matches the Kubernetes declaration.
Status Updates: After reconciliation, the LBC updates the status field of the Gateway API resources in Kubernetes. This provides real-time feedback on the provisioned AWS resources, such as the ALB's DNS name and ARN, and whether the gateways are accepted.

Step-by-Step L7 Gateway API Resource Implementation with an Example¶

This section illustrates the step-by-step process of configuring the Gateway API resources, demonstrating provisioning and configuration for an ALB.

Consider a scenario where an application exposes an HTTP and HTTPS endpoint.

# alb-gatewayclass.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: aws-alb-gateway-class
spec:
  controllerName: gateway.k8s.aws/alb
---
# my-alb-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: my-alb-gateway
  namespace: example-ns
spec:
  gatewayClassName: aws-alb-gateway-class
  infrastructure:
    parametersRef:
      kind: LoadBalancerConfiguration
      name: test-gw-lbconfig-1
      group: gateway.k8s.aws
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Same
  - name: https
    protocol: HTTPS
    port: 443
    allowedRoutes:
      namespaces:
        from: Same
---
# lbconfig.yaml
apiVersion: gateway.k8s.aws/v1beta1
kind: LoadBalancerConfiguration
metadata:
  name: test-gw-lbconfig-1
  namespace: example-ns
spec:
  listenerConfigurations:
    - protocolPort: HTTPS:443
      defaultCertificate: <my cert arn>
---
# httproute.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: my-http-app-route
  namespace: example-ns
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: my-alb-gateway
    sectionName: http
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: my-alb-gateway
    sectionName: https
  rules:
  - backendRefs:
    - name: <your service>
      port: <your service port>

API Event Detection: The LBC's L7 controller continuously monitors the Kubernetes API server. Upon detecting the aws-alb-gateway-class (with controllerName: gateway.k8s.aws/alb), the my-alb-gateway (referencing this GatewayClass), and my-http-app-route (referencing my-alb-gateway's listener) resources, it recognizes its responsibility to manage these objects and initiates the provisioning of AWS resources.
ALB Provisioning: An AWS Application Load Balancer (ALB) is provisioned in AWS for the my-alb-gateway resource with default settings. At this stage, the ALB is active but does not yet have any configured listeners. As soon as the ALB becomes active, the status of the gateway is updated.
L7 Listener Materialization: The controller processes the my-http-app-route resource. Given that the HTTPRoute validly references the my-alb-gateway and its http and https listeners, two Listeners are materialized on the ALB. The listeners accept HTTP traffic on port 80 and HTTPS traffic on port 443 and forward them to the service hosted on the HTTPRoute.
Target Group Creation: An AWS Target Group is created that contains the cluster nodes with the configured NodePort of the service.

Feature Comparison: ALB Gateways vs. Standard Gateway API¶

The AWS ALB Gateway implementation does not fully implement all Core functionality as mandated by the Gateway API. This is due to feature limitations of AWS ALB, this table should be helpful in navigating the features available within the ALB Gateway. For more information see the Gateway API Conformance Page

GatewayClass¶

Field	Conformance Level	ALB Gateway Support
ControllerName	Core	✅
ParametersRef	Core	✅
Description	Core	✅
Status	Core	✅

Gateway¶

Field	Conformance Level	ALB Gateway Support
Listeners	Core	✅
Addresses	Core	✅
Infrastructure	Core	✅ -- Used to attach LB Config
Status	Core	✅ -- Find the ALB ARN here
AllowedListeners	Experimental	❌
GatewayTLSConfig	Extended	❌
GatewayDefaultScope	Core	❌

Listener¶

Field	Conformance Level	ALB Gateway Support
Protocol Specification	Core	✅
Port Specification	Core	✅
Section Specification	Core	✅
Hostname Specification	Core	✅
Allowed Routes Specification	Core	✅
ListenerTLSConfig - TLSModeType	Core	✅
ListenerTLSConfig - CertificateRefs	Core	❌ -- Use LB Config
ListenerTLSConfig - Options	Core	❌ -- Use LB Config

GRPCRoute¶

Field	Conformance Level	ALB Gateway Support
ParentRefs	Core	✅
UseDefaultGateways	Core	❌
Hostnames	Core	✅
GRPCRouteRule - Section Name	Core	✅
GRPCRouteRule - GRPCRouteMatch - GRPCMethodMatch	Core	✅
GRPCRouteRule - GRPCRouteMatch - GRPCHeaderMatch	Core	✅
GRPCRouteRule - GRPCRouteFilter - Type	Core	❌-- Partial support
GRPCRouteRule - GRPCRouteFilter - RequestHeaderModifier	Core	❌-- Limited Support
GRPCRouteRule - GRPCRouteFilter - ResponseHeaderModifier	Core	❌
GRPCRouteRule - GRPCRouteFilter - RequestMirror	Core	❌
GRPCRouteRule - GRPCRouteFilter - ExtensionRef	Core	✅-- Use to attach ListenerRuleConfigurations
GRPCRouteRule - SessionPersistence	Extended	❌ -- Use ListenerRuleConfiguration

HTTPRoute¶

Field	Conformance Level	ALB Gateway Support
ParentRefs	Core	✅
UseDefaultGateways	Core	❌
Hostnames	Core	✅
HTTPRouteRule - Section Name	Core	✅
HTTPRouteRule - HTTPRouteMatch - HTTPPathMatch	Core	✅
HTTPRouteRule - HTTPRouteMatch - HTTPHeaderMatch	Core	✅
HTTPRouteRule - HTTPRouteMatch - HTTPQueryParamMatch	Core	✅
HTTPRouteRule - HTTPRouteMatch - HTTPMethod	Core	✅
HTTPRouteRule - HTTPRouteFilter - Type	Core	❌ -- Partial support
HTTPRouteRule - HTTPRouteFilter - RequestHeaderModifier	Core	❌-- Limited Support
HTTPRouteRule - HTTPRouteFilter - ResponseHeaderModifier	Core	❌
HTTPRouteRule - HTTPRouteFilter - RequestMirror	Extended	❌
HTTPRouteRule - HTTPRouteFilter - RequestRedirect	Core	✅
HTTPRouteRule - HTTPRouteFilter - UrlRewrite	Extended	❌
HTTPRouteRule - HTTPRouteFilter - CORS	Extended	❌
HTTPRouteRule - HTTPRouteFilter - ExternalAuth	Extended	❌ -- Use ListenerRuleConfigurations
HTTPRouteRule - HTTPRouteFilter - ExtensionRef	Core	✅ -- Use to attach ListenerRuleConfigurations
HTTPRouteRule - HTTPBackendRef	Core	✅
HTTPRouteRule - HTTPRouteTimeouts	Extended	❌
HTTPRouteRule - HTTPRouteRetry	Extended	❌
HTTPRouteRule - SessionPersistence	Extended	❌ -- Use ListenerRuleConfiguration

Backend TLS Policy¶

Backend TLS is not supported by AWS ALB Gateway. For more information on how AWS ALB communicates with targets using encryption, please see the AWS documentation.

Examples¶

Modifying Request Headers¶

AWS ALB only allows specific request headers to be modified.

** Request header modification must be done using the LoadBalancerConfiguration, using Listener Attributes **

apiVersion: gateway.k8s.aws/v1beta1
kind: LoadBalancerConfiguration
metadata:
  name: example-config
  namespace: example-ns
spec:
  listenerConfigurations:
    - protocolPort: HTTPS:443
      defaultCertificate: my-cert
      listenerAttributes:
        - key: routing.http.response.access_control_allow_origin.header_value
          value: example.com
---
# my-alb-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: my-alb-gateway
  namespace: example-ns
spec:
  gatewayClassName: aws-alb-gateway-class
  infrastructure:
    parametersRef:
      kind: LoadBalancerConfiguration
      name: test-gw-lbconfig-1
      group: gateway.k8s.aws
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-http-app-route
  namespace: example-ns
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: my-http-gateway
      sectionName: https
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: echoserver
          port: 80
          weight: 1
      matches:
        - path:
            type: PathPrefix
            value: /

HTTP Header Matching¶

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-http-app-route
  namespace: example-ns
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: my-http-gateway
      sectionName: https
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: echoserver
          port: 80
          weight: 1
      matches:
        - path:
            type: PathPrefix
            value: /
        - headers:
            - name: "oneHeaderSpecial"
              type: Exact
              value: "bar\\,bat"
            - name: "multiHeader"
              type: Exact
              value: "value1,value2"
            - name: "oneHeader"
              type: Exact
              value: "cat"

In this example will only be forwarded to the echoserver backend when the HTTP Request has these headers: oneHeaderSpecial=bar,bat AND multiHeader=value1 OR multiHeader=value2 AND oneHeader=cat

Source IP Condition¶

apiVersion: gateway.k8s.aws/v1beta1
kind: ListenerRuleConfiguration
metadata:
  name: custom-rule-config-source-ip
  namespace: example-ns
spec:
  conditions:
    - field: source-ip
      sourceIPConfig:
        values:
          - 10.0.0.0/5
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-http-app-route
  namespace: example-ns
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: my-http-gateway
      sectionName: https
  rules:
    - backendRefs:
        - group: ""
          kind: Service
          name: echoserver
          port: 80
          weight: 1
      filters:
        - extensionRef:
            group: gateway.k8s.aws
            kind: ListenerRuleConfiguration
            name: custom-rule-config-source-ip
          type: ExtensionRef
      matches:
        - path:
            type: PathPrefix
            value: /