HTTPRoute¶

Overview¶

The HTTPRoute resource in the Kubernetes Gateway API is used to define and manage routing rules for HTTP traffic within a Kubernetes cluster. HTTPRoute is determined by the Gateway API community. It specifies how HTTP requests should be directed from a Gateway to various backend services based on criteria such as paths and headers.

Key aspects of the HTTPRoute¶

Routing Rules: Defines detailed routing rules for HTTP requests, such as routing based on URL paths, request headers, and query parameters.
Service Mapping: Allows configuring of different HTTP requests to be mapped to different backend services or endpoints within the cluster.
Advanced Features: Supports advanced routing features, including weight-based routing and header-based routing, which are useful for traffic management and canary deployments.

By using HTTPRoute, Kubernetes users can precisely control how HTTP traffic is distributed and handled across their services, enabling flexible and efficient traffic management.

Update service¶

When a backend service is edited, the configuration of the dataplane does not get automatically updated. You must perform these steps in sequence.

Delete the service.
Modify the yaml file of the service.
Reapply the service.

Note

Perform Custom Resource (CR) operations only when the controller is in a running state.

CR Parameters¶

The table below describes the supported HTTPRoute spec parameters.

Parameter	Description
`parentRefs.name`	Specifies the name of the parent resources that is associated with HTTPRoute. For example, name of Gateway resource - http-gateway
`parentRefs.namespace`	Specifies the namespace of the parent resource that is associated with HTTPRoute. When unspecified, this refers to the local namespace of the Route.
`parentRefs.port`	Specifies the network port that this HTTPRoute targets. For example, this targets all listeners listening to specified port from a Gateway resource - 8080
`parentRefs.sectionName`	Specifies the section name or category of the parent that is associated with HTTPRoute. For example, listener name of Gateway resource - http
`rules.backendRefs.name`	Specifies the name of the backend service to which the traffic must be sent. For example, spk-app-http-8000-f5ing-testapp
`rules.backendRefs.namespace`	Specifies the namespace in which backend service is deployed. When unspecified, this refers to the local namespace of the Route.
`rules.backendRefs.port`	Specifies the port on which the backend service is listening. For example, 8080
`rules.backendRefs.weight`	Specifies the weight for load balancing the traffic between multiple backends. For example, 30
`rules.matches.headers.name`	Specifies the name of the HTTP Header to be matched. For example, version
`rules.matches.headers.value`	Specifies the value of HTTP Header to be matched. For example, one
`rules.matches.method`	Specifies HTTP method matcher. When specified, this route will be matched only if the request has the specified method. For example, GET
`rules.matches.path.type`	Specifies how to match against path value. Supported types are Exact and PathPrefix
`rules.matches.path.value`	Specifies the value of the HTTP path to match against. For example, /v1/chat/completions
`rules.filter`	Specifies a filter that modifies requests by sending request details to an external authorization server.
`rules.matches.queryParams`	Specifies how to select a HTTP route by matching HTTP query parameters.

Note

You can refer to HTTPRoute for more details.

HTTPRoute with HTTP/2¶

To support HTTP/2, kubernetes service should be configured with appProtocol:kubernetes.io/h2c as shown below,

apiVersion: v1
kind: Service
metadata:
  name: store
spec:
  selector:
    app: store
  ports:
  - protocol: TCP
    appProtocol: kubernetes.io/h2c
    port: 8080
    targetPort: 8080

Note

If multiple HTTPRoutes are attached to same gateway listener, all the services referred by all the routes from their backendRefs must use same appProtocol. CNE controller will consider only 1st route and its service to get the appProtocol and based on that HTTP/2 will be enabled/disabled.
CNE controller supports kubernetes.io/h2c and kubernetes.io/ws for appProtocol. It does not support kubernetes.io/wss for appProtocol.

HTTPRoute CR Status¶

HTTPRoute condition - Accepted

conditions.status	conditions.reason	description
Unknown	Pending	Initial state. Waiting for the controller.
True	Accepted	Accepted
False	- NoMatchingParent - NotAllowedByListeners - NoMatchingListenerHostname - UnsupportedValue	No Matching Parents by either Name, Port, or SectionName - Route not allowed by listeners - Route has no matching listener hostname - Failed to compile internal traffic policy

HTTPRoute condition - ResolvedRef

conditions.status	conditions.reason	description
True	ResolvedRefs	References Resolved
False	- BackendRef has Invalid Kind - Referenced resource protocol is not supported - UnsupportedProtocol	- BackendRef has invalid kind - No Backend was found matching reference - No ReferenceGrant was found for BackendRef in another namespace - Referenced resource protocol is not supported

HTTPRoute condition - PartiallyInvalid

conditions.status	conditions.reason	description
True	UnsupportedValue	Found both valid and invalid rules

Note: The descriptions may not be the same in the status section of CR.

Sample CRs¶

This section lists the sample CRs of use cases available to apply HTTPRoute. You must apply GatewayClass CR in the cluster and GatewaySettings in the namespace, only once.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: f5-gateway-class
spec:
  controllerName: "f5.com/f5-bnk-instance-f5-cne-controller"
  description: "F5 BIG-IP Kubernetes Gateway"

Basic HTTPRoute and Gateway API CRs
Client-side SSL configs
HTTPRoute for Exact URL path matching
HTTPRoute for Prefix URL path matching
HTTPRoute for header matching
HTTPRoute for method matching
HTTPRoute with method or path or header matching
HTTPRoute with weighted traffic distribution

Basic HTTPRoute and Gateway API CRs¶

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
   infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1 
  gatewayClassName: f5-gateway-class
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: HTTPRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: app-ns
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: http
    namespace: gateway-infra
  rules:
  - backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns

Client-side SSL configs¶

apiVersion: gateway.k8s.f5.com/v1alpha1
kind: GatewaySettings
metadata:
  name: gw-settings-app-1
  namespace: gateway-infra
spec:
  ingressConfig:
    defaultListenerNetwork:
      ipamRefs:
        - name: vip-listener-ipam
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
   infrastructure:
    parametersRef:
      group: gateway.k8s.f5.com
      kind: GatewaySettings
      name: gw-settings-app-1 
  gatewayClassName: f5-gateway-class
  listeners:
  - name: https
    protocol: HTTPS
    port: 443
    tls:
      certificateRefs:
      - kind: Secret
        group: ""
        name: tls-secret
        namespace: gateway-infra
    allowedRoutes:
      namespaces:
        from: "All"
      kinds:
      - kind: HTTPRoute
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: app-ns
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: https
    namespace: gateway-infra
  rules:
  - backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns

HTTPRoute for Exact URL path matching¶

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: http
    namespace: gateway-infra
  rules:
  - matches:
    - path:
        type: Exact
        value: /match
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  - matches:
    - path:
        type: Exact
        value: /match/exact
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns
  - matches:
    - path:
        type: Exact
        value: /match/exact/one
    backendRefs:
    - name: infra-backend-v3
      port: 8080
      namespace: app-ns

HTTPRoute for Prefix URL path matching¶

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: http
    namespace: gateway-infra
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /match/prefix/one
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns
  - matches:
    - path:
        type: PathPrefix
        value: /match/prefix/
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  - matches:
    - path:
        type: PathPrefix
        value: /match/
    backendRefs:
    - name: infra-backend-v3
      port: 8080
      namespace: app-ns

HTTPRoute for header matching¶

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: http
    namespace: gateway-infra
  rules:
  # Matches "version: two" AND "color: orange"
  - matches:
    - headers:
      - name: version
        value: two
      - name: color
        value: orange
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  # Matches "color: blue" OR "color: green"
  - matches:
    - headers:
      - name: color
        value: blue
    - headers:
      - name: color
        value: green
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  # Matches "color: red" OR "color: yellow"
  - matches:
    - headers:
      - name: color
        value: red
    - headers:
      - name: color
        value: yellow
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns
  # Matches "version: one"
  - matches:
    - headers:
      - name: version
        value: one
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  # Matches "version: two"
  - matches:
    - headers:
      - name: version
        value: two
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns

HTTPRoute for method matching¶

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: http
    namespace: gateway-infra
  rules:
  - matches:
    - method: POST
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  - matches:
    - method: GET
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns

HTTPRoute with method or path or header matching¶

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: http
    namespace: gateway-infra
  rules:
  # Combinations with core match types.
  - matches:
    - path:
        type: PathPrefix
        value: /path1
      method: GET
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  - matches:
    - headers:
      - name: version
        value: one
      method: PUT
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns
  - matches:
    - path:
        type: PathPrefix
        value: /path2
      headers:
      - name: version
        value: two
      method: POST
    backendRefs:
    - name: infra-backend-v3
      port: 8080
      namespace: app-ns
 
  # Match of the form (cond1 AND cond2) OR (cond3 AND cond4 AND cond5)
  - matches:
    - path:
        type: PathPrefix
        value: /path3
      method: PATCH
    - path:
        type: PathPrefix
        value: /path4
      headers:
      - name: version
        value: three
      method: DELETE
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
 
  # Matches for checking precedence.
  - matches:
    - path:
        type: PathPrefix
        value: /path5
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  - matches:
    - method: PATCH
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns
  - matches:
    - headers:
      - name: version
        value: four
    backendRefs:
    - name: infra-backend-v3
      port: 8080
      namespace: app-ns
   
  - matches:
    - method: POST
    backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
  - matches:
    - method: GET
    backendRefs:
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns

HTTPRoute with weighted traffic distribution¶

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-httproute
  namespace: gateway-infra
spec:
  parentRefs:
  - name: f5-http-gateway
    sectionName: http
    namespace: gateway-infra
  rules:
  - backendRefs:
    - name: infra-backend-v1
      port: 8080
      namespace: app-ns
      weight: 70
    - name: infra-backend-v2
      port: 8080
      namespace: app-ns
      weight: 30