HTTPRoute¶

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.

CR Parameters¶

The table below describes the supported HTTPRoute spec parameters.

Parameter	Description	Implementation Details
`parentRefs.name`	Specifies the name of the parent resources that is associated with HTTPRoute. For example, name of Gateway resource - http-gateway	As per the Gateway API community standard.
`parentRefs.namespace`	Specifies the namespace pf the parent resource that is associated with HTTPRoute. When unspecified, this refers to the local namespace of the Route.	As per the Gateway API community standard.
`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	As per the Gateway API community standard.
`parentRefs.sectionName`	Specifies the section name or category of the parent that is associated with HTTPRoute. For example, listener name of Gateway resource - http	As per the Gateway API community standard.
`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	As per the Gateway API community standard.
`rules.backendRefs.namespace`	Specifies the namespace in which backend service is deployed. When unspecified, this refers to the local namespace of the Route.	As per the Gateway API community standard.
`rules.backendRefs.port`	Specifies the port on which the backend service is listening. For example, 8080	As per the Gateway API community standard.
`rules.backendRefs.weight`	Specifies the weight for load balancing the traffic between multiple backends. For example, 30	As per the Gateway API community standard.
`rules.matches.headers.name`	Specifies the name of the HTTP Header to be matched. For example, version	As per the Gateway API community standard.
`rules.matches.headers.value`	Specifies the value of HTTP Header to be matched. For example, one	If each rule has multiple header matches provided then rules need to be ordered in such a way that a rule with largest number of header matches is placed at first index, and a rule with smallest number of header matches is placed at last index. Incoming traffic will always be matched against rules in the order in which they are specified in HTTPRoute CR.
`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	As per the Gateway API community standard.
`rules.matches.path.type`	Specifies how to match against path value. Supported types are Exact and PathPrefix	If specified type is PathPrefix then rules need to be ordered in such a way that a rule with longest prefix match value is placed at first index, and a rule with least prefix match value is placed at last index. Incoming traffic will always be matched against rules in the order in which they are specified in HTTPRoute CR.
`rules.matches.path.value`	Specifies the value of the HTTP path to match against. For example, /v1/chat/completions	As per the Gateway API community standard.

Note

You can refer to HTTPRoute for more details.
Hostnames, Filters, Timeouts, Retry, and SessionPersistence parameters in HTTPRoute CR are not supported.

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 only supports kubernetes.io/h2c for appProtocol. It does not support kubernetes.io/ws and 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	No Matching Parents by either Name, Port, or SectionName - Route not allowed by listeners - Route has no matching listener hostname

HTTPRoute condition - ResolvedRef

conditions.status	conditions.reason	description
True	ResolvedRefs	References Resolved
False	- InvalidKind - BackendNotFound - RefNotPermitted - UnsupportedProtocol	- BackendRef has invalid kind - UnsupportedProtocol - 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 GRPCRoute. You must apply GatewayClass CR in the cluster and F5BnkGateway in the namespace, only once.

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: f5-gateway-class
spec:
  controllerName: "f5.com/default-f5-cne-controller"
  description: "F5 BIG-IP Kubernetes Gateway"
---
apiVersion: k8s.f5net.com/v1
kind: F5BnkGateway
metadata:
  name: f5-bnkgateway
  namespace: default  #same namespace in which f5-cne-controller is deployed
spec:
  ingressConfig:
    defaultListenerNetworks:
      - ipv4BaseCidr: "11.11.11.0/24"
        name: "default_ipv4"
        startAddress: "11.11.11.1"
        endAddress: "11.11.11.255"

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.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: k8s.f5net.com
      kind: F5BnkGateway
      name: f5-bnkgateway
  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.networking.k8s.io/v1
kind: Gateway
metadata:
  name: f5-http-gateway
  namespace: gateway-infra
spec:
  infrastructure:
    parametersRef:
      group: k8s.f5net.com
      kind: F5BnkGateway
      name: f5-bnkgateway
  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¶

Note: Rules are placed in the order such that longest path prefix match is at first index.

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¶

Note: Rules are arranged such that maximum headers match is at first index.

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