HTTPRoute resource fields

The HTTPRoute resource contains traffic routing and redirection rules for Kubernetes service backends, i.e., Service resources. HTTPRoute receives incoming traffic from Gateway resources whose requirements it meets.

The HTTPRoute resource is designed for application developers. Cluster operators should use the Gateway resource.

HTTPRoute is a Kubernetes Gateway API project resource. Below, we describe its fields and annotations used by Application Load Balancer Gateway API. For configuration details, see the Kubernetes Gateway API reference.

HTTPRouteHTTPRoute

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: <string>
  namespace: <string>
spec: <HTTPRouteSpec>

Where:

• apiVersion: gateway.networking.k8s.io/v1alpha2

• kind: HTTPRoute

• metadata (ObjectMeta, required)

  Resource metadata.

  • name (string, required)

    Resource name. For more information about the name format, see the relevant Kubernetes guides.

    Do not mistake this name for the Application Load Balancer route name.

  • namespace (string)

    Resource namespace. The default value is default.

• spec (HTTPRouteSpec, required)

  Resource specification. For more information, see below.

HTTPRouteSpecHTTPRouteSpec

parentRefs:
  - group: <string>
    kind: <string>
    namespace: <string>
    name: <string>
    sectionName: <string>
  - ...
hostnames:
  - <string>
  - ...
rules:
  - matches:
      - path:
          type: <string>
          value: <string>
        method: <string>
      - ...
    filters:
      - <HTTPRouteFilter>
      - ...
    backendRefs:
      - group: <string>
        kind: <string>
        name: <string>
        namespace: <string>
        port: <int32>
        weight: <int32>
        filters:
          - <HTTPRouteFilter>
          - ...
      - ...
  - ...

Where:

• parentRefs ([]ParentReference, required)

  Gateway resources or their listeners specified in the spec.listeners field associated with HTTPRoute. For more information, see this reference.

  Routes must also comply with the Gateway configuration rules specified in the spec.listeners.allowedRoutes field.

  • namespace (string)

    Gateway namespace specified in its metadata.namespace field.

    By default, it matches the HTTPRoute namespace specified in its metadata.namespace field.

  • name (string, required)

    Gateway name specified in its metadata.name field.

  • sectionName (string)

    Gateway listener specified in its spec.listeners.name field.

• hostnames ([]string)

  HTTP/1.1 Host (HTTP/2 :authority) header domains for this route. The system will create HTTP router virtual hosts for each specified domain.

  To match all subdomains at any level, use a wildcard * in place of the first-level domain name. Wildcard domain values must be quoted.

  For example, "*.example.com" matches foo.example.com, foo-bar.example.com, foo.bar.example.com, and foo.bar.baz.example.com, but not example.com.

  Wildcards must replace complete domain levels; for example, *foo.example.com is invalid.

• rules ([]HTTPRouteRule)

  Request routing and redirection rules.

  • matches ([]HTTPRouteMatch)

    List of conditions, where the request must meet at least one, for the rule to apply.

    For example, the conditions below allow POST requests to the /foo endpoint and any requests to the /bar endpoint:

    matches:
      - path:
          value: /foo
        method: POST
      - path:
          value: /bar
    

    You can only use fields listed below. Other fields described in the Gateway API reference, e.g.,headers and queryParams, are not supported.

    • path (HTTPPathMatch)

      Request URI path.

      • type (string)

        Request URI path type:

        • Exact: Path must match rules.matches.path.value.
        • PathPrefix: Path must begin with rules.matches.path.value.

        The selected path type will affect traffic distribution and the path replacement mechanism for redirects. For more information, see below.

      • value (string)

        Incoming request URI full path or its prefix, depending on whether the Exact or PathPrefix option is selected, respectively.

    • method (HTTPMethod)

      Request HTTP method.

  • filters ([]HTTPRouteFilter)

    Filters specifying request header modifications for backend routing and redirection. For more information, see below.

    You can specify either the RequestHeaderModifier or the RequestRedirect filter, but not both at the same time.

  • backendRefs ([]HTTPBackendRef)

    Kubernetes service backends for processing requests.

    The referred Service resource must be described per the standard configuration.

    • name (string)

      Kubernetes service name.

    • namespace (string)

      Service namespace.

    • port (int32)

      Service port number.

      The port number must match one of the Service resource spec.ports.port field values. For more information, see the resource configuration.

      This field is designed for the Gateway API and has no equivalents in Application Load Balancer.

    • weight (int32)

      Backend weight. Backends in a group receive traffic in proportion to their weights.

      You should either specify weights for all backends in a group, or not specify them at all. If weights are not specified, traffic will be equally distributed across backends.

      A backend with zero or negative weight will not be receiving traffic.

    • filters ([]HTTPRouteFilter)

      Request header modification settings for backend routing. For more information, see this example.

      You can only specify the RequestHeaderModifier filter.

HTTPRouteFilterHTTPRouteFilter

type: <string>
requestHeaderModifier:
  set:
    - name: <string>
      value: <string>
    - ...
  add:
    - name: <string>
      value: <string>
    - ...
  remove:
    - <string>
    - ...
requestRedirect:
  scheme: <string>
  hostname: <string>
  path:
    type: <string>
    replaceFullPath: <string>
    replacePrefixMatch: <string>
  port: <int32>
  statusCode: <int>

Where:

• type (string)

  Filter type:

  • RequestHeaderModifier: Request header modification. Specify the required settings in the requestHeaderModifier field.
  • RequestRedirect: Request redirection. Specify the required settings in the requestRedirect field.

• requestHeaderModifier (HTTPRequestHeaderFilter)

  Request header modification settings for the RequestHeaderModifier filter type.

  • set ([]HTTPHeader)

    Headers that will be overwritten.

    • name (string)

      Header name.

    • value (string)

      Header new value.

  • add ([]HTTPHeader)

    Headers that will be added to requests.

    • name (string)

      Header name.

    • value (string)

      Header value.

  • remove ([]string)

    Headers to be removed from requests.

• requestRedirect (HTTPRequestRedirectFilter)

  Request redirect settings for the RequestRedirect filter type.

  • scheme (string)

    New request URI scheme, e.g., http or https. By default, the scheme remains unchanged.

  • hostname (string)

    New request URI hostname. By default, the hostname remains unchanged.

  • path (HTTPPathModifier)

    Request URI path replacement settings.

    • type (string)

      Path replacement type:

      • ReplaceFullPath: Full path replacement. Specify the new path in the replaceFullPath field.
      • ReplacePrefixMatch: Full path or prefix replacement based on the HTTPRoute spec.rules.matches.path value: Exact or PathPrefix, respectively. Specify the new path or its prefix in the replacePrefixMatch field.

    • replaceFullPath (string)

      New path for the ReplaceFullPath replacement type.

    • replacePrefixMatch (string)

      New path or its prefix for the ReplacePrefixMatch replacement type.

  • port (int32)

    New request URI port.

  • statusCode (int)

    Redirect HTTP status code.