HTTPRoute API Reference¶

Introduction¶

With integration of the Gateway API, AWS Gateway API Controller supports HTTPRoute. This allows you to define and manage the routing of HTTP and HTTPS traffic within your Kubernetes cluster.

HTTPRoute Key Features & Limitations¶

Features:

Routing Traffic: Enables routing HTTP traffic to servers within your Kubernetes cluster.
Path and Method Matching: The HTTPRoute allows for matching by:
- An exact path.
- Any path with a specified prefix.
- A specific HTTP Method.
Header Matching: Enables matching based on specific headers in the HTTP request.

Limitations:

Listener Protocol: The HTTPRoute sectionName must refer to an HTTP or HTTPS listener in the parent Gateway.
Method Matches: One method match is allowed within a single rule.
QueryParam Matches: Matching by QueryParameters is not supported.
Header Matches Limit: A maximum of 5 header matches per rule is supported.
Case Insensitivity: All path matches are currently case-insensitive.

Annotations¶

application-networking.k8s.aws/lattice-assigned-domain-name
Represents a VPC Lattice generated domain name for the resource. This annotation will automatically set when a HTTPRoute is programmed and ready.
application-networking.k8s.aws/dns-endpoint
Set to disabled to stop the controller from managing a DNSEndpoint for this route. Use it when DNS records for the route's hostname are managed outside the controller. If a DNSEndpoint created by the controller for this route already exists, it is deleted. A DNSEndpoint with the same name that is not owned by the route is left untouched. Removing the annotation makes the controller create the DNSEndpoint again. See Managing DNS records using ExternalDNS.

Note

Deleting the DNSEndpoint removes the DNS record only if ExternalDNS runs with --policy=sync. With upsert-only or create-only, delete the record from your DNS provider manually.
application-networking.k8s.aws/idle-timeout-seconds
Sets the idle connection timeout, in seconds, for the VPC Lattice Service that this route maps to. The idle timeout is the amount of time a connection can remain idle (no data sent) before VPC Lattice closes it. Valid range is 60–600. If the annotation has never been set, VPC Lattice applies its default of 60 seconds. The value must be quoted, e.g. "120". An out-of-range or non-integer value is ignored (left unset) and logged as a warning.

Note

The idle timeout is distinct from the fixed maximum connection duration (10 minutes) enforced by VPC Lattice, which is not configurable. Raising the idle timeout only affects connections that are idle, not long-lived active connections.

Note

The controller manages this value only while the annotation is present. Removing the annotation leaves the last applied value on the VPC Lattice Service rather than reverting it, so a value set out-of-band is preserved. To change it back, set the annotation to the desired value (e.g. "60").

Example:
```
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: inventory
  annotations:
    application-networking.k8s.aws/idle-timeout-seconds: "120"
spec:
  parentRefs:
    - name: my-hotel
      sectionName: http
  rules:
    - backendRefs:
        - name: inventory-ver1
          kind: Service
          port: 80
```

Example Configuration¶

Example 1¶

Here is a sample configuration that demonstrates how to set up an HTTPRoute that forwards HTTP traffic to a Service and ServiceImport, using rules to determine which backendRef to route traffic to.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: inventory
spec:
  parentRefs:
    - name: my-hotel
      sectionName: http
  rules:
    - backendRefs:
        - name: inventory-ver1
          kind: Service
          port: 80
      matches:
        - path:
            type: PathPrefix
            value: /ver1
    - backendRefs:
        - name: inventory-ver2
          kind: ServiceImport
          port: 80
      matches:
        - path:
            type: PathPrefix
            value: /ver2

In this example:

The HTTPRoute is named inventory and is associated with a parent gateway named my-hotel that has a section named http.
The first routing rule forwards traffic to a backend Service named inventory-ver1 on port 80. The rule also specifies a path match condition, where traffic must have a path starting with /ver1 for the routing rule to apply.
The second routing rule forwards traffic to a backend ServiceImport named inventory-ver2 on port 80. The rule also specifies a path match condition, where traffic must have a path starting with /ver2 for the routing rule to apply.

Example 2¶

Here is a sample configuration that demonstrates how to set up a HTTPRoute that forwards HTTP and HTTPS traffic to a Service and ServiceImport, using weighted rules to route more traffic to one backendRef than the other. Weighted rules simplify the process of creating blue/green deployments by shifting rule weight from one backendRef to another.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: inventory
spec:
  parentRefs:
    - name: my-hotel
      sectionName: http
    - name: my-hotel
      sectionName: https
  rules:
    - backendRefs:
        - name: inventory-ver1
          kind: Service
          port: 80
          weight: 10
        - name: inventory-ver2
          kind: ServiceImport
          port: 80
          weight: 90

In this example:

The HTTPRoute is named inventory and is associated with a parent gateway named my-hotel that has two sections, named http and https.
The first routing rule forwards traffic to a backend Service named inventory-ver1 on port 80. The rule also specifies a weight of 10.
The second routing rule forwards traffic to a backend ServiceImport named inventory-ver2 on port 80. The rule also specifies a weight of 90.
The amount of traffic forwarded to a backendRef is (rule weight / total weight) * 100%. Thus, 10% of the traffic is forwarded to inventory-ver1 at port 80 and 90% of the traffic is forwarded to inventory-ver2 at the default port.

This HTTPRoute documentation provides a detailed introduction, feature set, and a basic example of how to configure and use the resource within AWS Gateway API Controller project. For in-depth details and specifications, you can refer to the official Gateway API documentation.