Route Resource Configuration

This topic describes how to create and configure Route resources. Routes are independent configuration objects that are associated with specific listeners.

Create a Route

Declare a route with either kind: HTTPRoute or kind: TCPRoute and configure the route parameters in the spec block. Refer to the Kubernetes Gateway API documentation for each object type for details:

• HTTPRoute
• TCPRoute

The following example creates a route named example-route associated with a listener defined in example-gateway.

routes.yaml

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: example-route
spec:
  parentRefs:
  - name: example-gateway
  rules:
  - backendRefs:
    - kind: Service
      name: echo
      port: 8080

Configuration model

The following outline shows how to format the configurations for the Route object. The top-level spec field is the root for all configurations. Click on a property name to view details about the configuration.

• parentRefs: array of objects | optional
  • group: string | optional
  • kind: string | optional
  • name: string | required
  • namespace: string | optional
  • sectionName: string | optional
• rules: list of objects | optional
  • backendRefs: list of objects | optional
    • group: string | optional
    • kind: string | optional
    • name: string | required
    • namespace: string | optional
    • port: integer | required
    • weight: integer | optional
  • filters: list of objects | optional
    • type: string | required
    • requestHeaderModifier: object | optional
      • set: array of objects | optional
        • name: string | required
        • value: string | required
      • add: array of objects | optional
        • name: string | required
        • value: string | required
      • remove: array of strings | optional
    • urlRewrite: object | optional
      • path: object | required
        • replacePrefixMatch: string | required
        • type: string | required
  • matches: array of objects | optional
    • path: list of objects | optional
      • type: string | required
      • value: string | required
    • headers: list of objects | optional
      • type: string | required
      • name: string | required
      • value: string | required
    • queryParams: list of objects | optional
      • type: string | required
      • name: string | required
      • value: string | required
    • method: string | optional

Specification

This topic provides details about the configuration parameters.

parentRefs

This field contains the list of Gateways that the route should attach to. If not set, the route will not attach to a Gateway. The following table describes the objects you can configure in the parentRefs block:

rules

The rules field contains a list of objects that define behaviors for network traffic that goes through the route. The rule configuration contains the following objects:

• backendRefs: Specifies which backend services the Route references when processing traffic.
• filters: Specifies which operations Consul API Gateway performs when traffic goes through the Route.
• matches: Determines which requests Consul API Gateway processes.

Rules are optional.

rules.backendRefs

This field specifies backend services that the Route references. The following table describes the parameters for backendRefs:

Example cross-namespace backendRef

The following example creates a route named example-route in namespace gateway-namespace. This route has a backendRef in namespace service-namespace. Traffic is allowed because the ReferenceGrant, named reference-grant in namespace service-namespace, allows traffic from HTTPRoutes in gateway-namespace to Services in service-namespace.

route_with_referencegrant.yaml

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: example-route
  namespace: gateway-namespace
spec:
  parentRefs:
    - name: example-gateway
  rules:
    - backendRefs:
      - kind: Service
        name: echo
        namespace: service-namespace
        port: 8080
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: ReferenceGrant
metadata:
  name: reference-grant
  namespace: service-namespace
spec:
  from:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    namespace: gateway-namespace
    to:
      - group: ""
        kind: Service
        name: echo

rules.filters

The filters block defines steps for processing requests. You can configure filters to modify the properties of matching incoming requests and enable Consul API Gateway features, such as rewriting path prefixes (refer to Reroute HTTP requests for additional information).

• Type: Array of objects
• Required: Optional

rules.filters.type

Specifies the type of filter you want to apply to the route. The parameter is optional and takes a string value.

You can specify the following values:

• RequestHeaderModifier: The RequestHeaderModifier type modifies the HTTP headers on the incoming request. You must define the rules.filters.requestHeaderModifier configurations to use this filter type.

• URLRewrite: The URLRewrite type modifies the URL path on the incoming request. You must define the rules.filters.urlRewrite configurations to use this filter type.

rules.filters.requestHeaderModifier

Defines operations to perform on matching request headers when rules.filters.type is configured to RequestHeaderModifier. This field contains the following configuration objects:

rules.filters.urlRewrite

Specifies rules for rewriting the URL of incoming requests when rules.filters.type is configured to URLRewrite.

• Type: Object
• Required: Optional

rules.filters.urlRewrite.path

Specifies a list of objects that determine how Consul API Gateway rewrites URL paths (refer to Reroute HTTP requests for additional information).

The following table describes the parameters for path:

rules.matches

Specifies rules for matching incoming requests. You can apply filters to requests that match the defined rules. You can match incoming requests based on the following elements:

• paths
• headers
• query parameters
• request method

Each rule matches requests independently. As a result, a request matching any of the conditions is considered a match. You can configure several matching rules for each type to widen or narrow matches.

rules.matches.path

Specifies a list of objects that define matches based on URL path. The following table describes the parameters for the path field:

rules.matches.headers

Specifies a list of objects that define matches based HTTP request headers. The following table describes the parameters for the headers field:

rules.matches.queryParams

Specifies a list of objects that define matches based query parameters. The following table describes the parameters for the queryParams field:

rules.matches.method

Specifies a list of strings that define matches based on HTTP request method. You may specify the following values:

• HEAD
• POST
• PUT
• PATCH
• GET
• DELETE
• OPTIONS
• TRACE
• CONNECT