Skip to content

Latest commit

 

History

History
266 lines (200 loc) · 15.7 KB

routes.mdx

File metadata and controls

266 lines (200 loc) · 15.7 KB
Raw
layout page_title description
docs
Consul API Gateway Routes
Consul API Gateway Routes

Route

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:

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

apiVersion: gateway.networking.k8s.io/v1alpha2
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.

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:

Parameter Description Type Required
group Specifies the Kubernetes API group of the Gateway to attach to. You can specify the following values:
  • gateway.networking.k8s.io
. Defaults to gateway.networking.k8s.io.		 String Optional
kind Specifies the Kubernetes kind of the Gateway to attach to. you can specify the following values:
  • Gateway
. Defaults to Gateway.		 String Optional
name Specifies the name of the Gateway the route is attached to. String Required
namespace Specifies the Kubernetes namespace containing the Gateway to attach to. If the Gateway is in a different Kubernetes namespace than the Route, then you must specify a value. Defaults to the Route namespace. String Optional
sectionName Specifies the name of a specific listener on the Gateway to attach to. The Route attempts to attach to all listeners on the Gateway. String Required

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:

Parameter Description Type Required
group Specifies the Kubernetes API Group of the referenced backend. You can specify the following values:
  • "": Specifies the core Kubernetes API group. This value must be used when kind is set to Service. This is the default value if unspecified.
  • api-gateway.consul.hashicorp.com: This value must be used when kind is set to MeshService.
 String Optional
kind Specifies the Kubernetes Kind of the referenced backend. You can specify the following values:
  • Service (default): Indicates that the backendRef references a Service in the Kubernetes cluster.
  • MeshService: Indicates that the backendRef references a service in the Consul mesh. Refer to the MeshService documentation for additional information.
 String Optional
name Specifies the name of the Kubernetes Service or Consul mesh service resource. String Required
namespace Specifies the Kubernetes namespace containing the Kubernetes Service or Consul mesh service resource. You must specify a value if the Service or Consul mesh service is defined in a different namespace from the Route. Defaults to the namespace of the Route.
To create a route for a backendRef in a different namespace, you must also create a ReferenceGrant. Refer to the example route configured to reference across namespaces.		 String Optional
port Specifies the port number for accessing the Kubernetes or Consul service. Integer Required
weight Specifies the proportion of requests sent to the backend. Computed as weight divided by the sum of all weights in this backendRefs list. Defaults to 1. A value of 0 indicates that no requests should be sent to the backend. Integer Optional

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.

apiVersion: gateway.networking.k8s.io/v1alpha2
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:

Parameter Description Type Required
set Configure this field to rewrite the HTTP request header. It specifies the name of an HTTP header to overwrite and the new value to set. Any existing values associated with the header name are overwritten. You can specify the following configurations:
  • name: Required string that specifies the name of the HTTP header to set.
  • value: Required string that specifies the value of the HTTP header to set.
 List of objects Optional
add Configure this field to append the request header with a new value. It specifies the name of an HTTP header to append and the value(s) to add. You can specify the following configurations:
  • name: Required string that specifies the name of the HTTP header to append.
  • value: Required string that specifies the value of the HTTP header to add.
 List of objects Optional
remove Configure this field to specify an array of header names to remove from the request header. Array of strings Optional

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:

Parameter Description Type Required
replacePrefixMatch Specifies a value that replaces the path prefix for incoming HTTP requests. The operation only affects the path prefix. The rest of the path is unchanged. String Required
type Specifies the type of replacement to use for the URL path. You can specify the following values:
  • ReplacePrefixMatch: Replaces the the matched prefix of the URL path (default).
String Optional

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:

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:

Parameter Description Type Required
type Specifies the type of comparison to use for matching the path value. You can specify the following types.
  • Exact: Returns a match only when the entire path matches the value field (default).
  • PathPrefix: Returns a match when the path has the prefix defined in the value field.
  • RegularExpression: Returns a match when the path matches the regex defined in the value field.
 String Required
value Specifies the value to match on. You can specify a specific string when type is Exact or PathPrefix. You can specify a regular expression if type is RegularExpression. String Required

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:

Parameter Description Type Required
type Specifies the type of comparison to use for matching the header value. You can specify the following types.
  • Exact: Returns a match only when the entire header matches the value field (default).
  • RegularExpression: Returns a match when the header matches the regex defined in the value field.
 String Required
name Specifies the name of the header to match on. String Required
value Specifies value to match on. You can specify a specific string or a regular expression. String Required

rules.matches.queryParams

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

Parameter Description Type Required
type Specifies the type of comparison to use for matching a query parameter value. You can specify the following types.
  • Exact: Returns a match only when the query parameter match the value field (default).
  • RegularExpression: Returns a match when the query parameter matches the regex defined in the value field.
 String Required
name Specifies the name of the query parameter to match on. String Required
value Specifies value to match on. You can specify a specific string or a regular expression. String Required

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