RouteHeaderMatchInvertFilter resource configuration reference

This topic provides configuration reference information for the RouteHeaderMatchInvertFilter resource. The resource negates the HTTP header match conditions in an HTTPRoute rule so that the rule matches requests that do not meet the header conditions.

Introduction

The Kubernetes Gateway API HTTPHeaderMatch field does not provide a way to negate a header match. Use a RouteHeaderMatchInvertFilter to list the names of the headers whose match conditions you want to negate in an HTTPRoute rule. For example, you can route requests to a service when the x-version header value is not v1.

To apply the filter, add an ExtensionRef filter to the rule in the rules.filters field of an HTTPRoute. Set extensionRef.group to consul.hashicorp.com, extensionRef.kind to RouteHeaderMatchInvertFilter, and extensionRef.name to the name of the filter. The filter must be in the same namespace as the HTTPRoute. Refer to Route resource configuration reference for additional information.

Consul on Kubernetes sets the Invert field to true on every header match in the rule whose name appears in spec.headerNames. The filter applies to header matches in all matches entries of the rule. Header matches for headers that are not listed in the filter are not affected. When a rule references more than one RouteHeaderMatchInvertFilter, Consul on Kubernetes uses the first filter.

The following table describes how the filter affects each Kubernetes Gateway API header match type:

An inverted condition does not match requests that do not include the header.

When you remove the filter from the rule, Consul on Kubernetes sets Invert to false on the header matches.

The RouteHeaderMatchInvertFilter resource is supported for HTTPRoute resources in the gateway.networking.k8s.io API group.

Configuration model

The following list outlines field hierarchy, data types, and requirements in a RouteHeaderMatchInvertFilter resource. Click on a property name to view additional details, including default values.

• apiVersion: string | required | must be set to consul.hashicorp.com/v1alpha1
• kind: string | required | must be set to RouteHeaderMatchInvertFilter
• metadata: map | required
  • name: string | required
  • namespace: string | default
• spec: map | required
  • headerNames: list of strings | required

Complete configuration

When every field is defined, this resource has the following form:

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteHeaderMatchInvertFilter
metadata:
  name: <name of the filter>
  namespace: <namespace of the HTTPRoute>
spec:
  headerNames:
    - <name of header whose match to negate>

Specification

This section provides details about the fields you can configure in the resource.

apiVersion

Specifies the version of the Consul API for integrating with Kubernetes. The value must be consul.hashicorp.com/v1alpha1.

Values

• Default: None
• This field is required.
• String value that must be set to consul.hashicorp.com/v1alpha1.

kind

Specifies the type of resource to implement. Must be set to RouteHeaderMatchInvertFilter.

Values

• Default: None
• This field is required.
• Data type: String value that must be set to RouteHeaderMatchInvertFilter.

metadata

Map that contains an arbitrary name for the resource and the namespace it applies to.

Values

• Default: None
• Data type: Map

metadata.name

Specifies a name for the resource. Specify this name in the extensionRef.name field of the HTTPRoute rule filter.

Values

• Default: None
• This field is required.
• Data type: String

metadata.namespace

Specifies the Kubernetes namespace of the resource. The namespace must match the namespace of the HTTPRoute that references the filter.

Values

• Default: default
• Data type: String

spec

Map that contains the filter configuration. The apiVersion, kind, and metadata fields are siblings of the spec field. All other configurations are children.

spec.headerNames

Specifies the names of the headers whose match conditions to negate in the rule that references the filter. Header names are not case sensitive.

Values

• Default: None
• This field is required.
• Data type: List of strings that contains at least one header name

Example

In the following example, requests that include the x-version header with a value other than v1 route to the service-v2 service:

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteHeaderMatchInvertFilter
metadata:
  name: invert-version
  namespace: default
spec:
  headerNames:
    - x-version
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: version-route
  namespace: default
spec:
  parentRefs:
  - name: my-gateway
  rules:
  - matches:
    - headers:
      - type: Exact
        name: x-version
        value: v1
    filters:
    - type: ExtensionRef
      extensionRef:
        group: consul.hashicorp.com
        kind: RouteHeaderMatchInvertFilter
        name: invert-version
    backendRefs:
    - name: service-v2
      port: 80