RouteExtProc resource configuration reference

Enterprise

This feature requires Consul Enterprise. Refer to the enterprise feature matrix for additional information.

This topic provides reference information for the RouteExtProc custom resource, which controls how the ext-proc Envoy extension behaves for specific API gateway routes on Kubernetes. Attach the resource to an HTTPRoute with an ExtensionRef filter to disable or override an ext-proc instance for requests that match that route.

Refer to Intercept and process HTTP traffic with the ext-proc Envoy extension for usage information.

Configuration model

The following list outlines the field hierarchy, data types, and requirements for the RouteExtProc resource. Click 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 RouteExtProc
metadata: map | required
- name: string | required
- namespace: string | default
spec: map | required
- statPrefix: string
- mode: string | required
- overrides: map
  - processing: map
    - request: map
      - headersMode: string | SEND
      - bodyMode: string | SKIP
      - trailersMode: string | SKIP
      - maxBodyBytes: integer
    - response: map
      - headersMode: string | SKIP
      - bodyMode: string | SKIP
      - trailersMode: string | SKIP
      - maxBodyBytes: integer

Complete configuration

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

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteExtProc
metadata:
  name: <name for this resource>
  namespace: <namespace>
spec:
  statPrefix: <StatPrefix of the ext-proc instance to target>
  mode: <disabled | override>
  overrides:
    processing:
      request:
        headersMode: <SEND | SKIP>
        bodyMode: <SKIP | BUFFERED | BUFFERED_PARTIAL | STREAMED>
        trailersMode: <SEND | SKIP>
        maxBodyBytes: <integer>
      response:
        headersMode: <SEND | SKIP>
        bodyMode: <SKIP | BUFFERED | BUFFERED_PARTIAL | STREAMED>
        trailersMode: <SEND | SKIP>
        maxBodyBytes: <integer>

Specification

This section describes the fields you can configure in the RouteExtProc 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.
Data type: String value that must be set to consul.hashicorp.com/v1alpha1.

`kind`

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

Values

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

`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. Use this name in the rules.filters.extensionRef.name field of an HTTPRoute to attach the filter to a route.

Values

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

`metadata.namespace`

Specifies the Kubernetes namespace that the resource applies to. Refer to Namespaces for more information.

Values

Default: default
Data type: String

`spec`

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

Values

Default: None
This field is required.
Data type: Map

`spec.statPrefix`

Identifies the ext-proc instance to target by matching the value of the StatPrefix field set in the EnvoyExtensions configuration. When you omit this field, the resource targets the default instance whose Envoy filter name is envoy.filters.http.ext_proc (no suffix).

Values

Default: None (targets the default unsuffixed instance)
Data type: String

`spec.mode`

Specifies how the targeted ext-proc instance behaves for requests that match the attached route.

disabled: Skips the targeted instance entirely for requests that match the route. The processing service is not called and no headers, bodies, or trailers are forwarded.
override: Keeps the targeted instance active on the route and applies the per-route processing settings defined in the spec.overrides field.

Values

Default: None
This field is required.
Data type: String value set to one of the following:
- disabled
- override

`spec.overrides`

Contains per-route processing settings that override the instance-level configuration when spec.mode is set to override. This field has no effect when mode is disabled.

Values

Default: None
Data type: Map

`spec.overrides.processing`

Specifies which phases of the request and response lifecycle Envoy forwards to the processing service for requests that match this route.

Values

Default: None
Data type: Map

`spec.overrides.processing.request`

Specifies the per-route processing modes that Envoy applies to the request direction.

Values

Default: None
Data type: Map

The following table describes the parameters you can configure in the request field:

Parameter	Description	Data type	Default
`headersMode`	Controls whether Envoy sends request headers to the processing service. Set to `SEND` or `SKIP`.	String	`SEND`
`bodyMode`	Controls whether and how Envoy sends the request body to the processing service. Set to `SKIP`, `BUFFERED`, `BUFFERED_PARTIAL`, or `STREAMED`.	String	`SKIP`
`trailersMode`	Controls whether Envoy sends request trailers to the processing service. Set to `SEND` or `SKIP`.	String	`SKIP`
`maxBodyBytes`	Specifies the maximum number of body bytes Envoy buffers when `bodyMode` is `BUFFERED` or `BUFFERED_PARTIAL`.	Integer	None

`spec.overrides.processing.response`

Specifies the per-route processing modes that Envoy applies to the response direction.

Values

Default: None
Data type: Map

The following table describes the parameters you can configure in the response field:

Parameter	Description	Data type	Default
`headersMode`	Controls whether Envoy sends response headers to the processing service. Set to `SEND` or `SKIP`.	String	`SKIP`
`bodyMode`	Controls whether and how Envoy sends the response body to the processing service. Set to `SKIP`, `BUFFERED`, `BUFFERED_PARTIAL`, or `STREAMED`.	String	`SKIP`
`trailersMode`	Controls whether Envoy sends response trailers to the processing service. Set to `SEND` or `SKIP`.	String	`SKIP`
`maxBodyBytes`	Specifies the maximum number of body bytes Envoy buffers when `bodyMode` is `BUFFERED` or `BUFFERED_PARTIAL`.	Integer	None

Examples

Disable ext-proc for a specific route

The following example disables the ext-proc instance identified by the route-decider stat prefix for requests that match the /static path prefix. All other routes continue to use the instance as configured.

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteExtProc
metadata:
  name: disable-route-decider
  namespace: default
spec:
  statPrefix: route-decider
  mode: disabled
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: static-route
  namespace: default
spec:
  parentRefs:
    - name: api-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /static
      filters:
        - type: ExtensionRef
          extensionRef:
            group: consul.hashicorp.com
            kind: RouteExtProc
            name: disable-route-decider
      backendRefs:
        - kind: Service
          name: service-a
          namespace: default
          port: 8080

Override processing modes for a specific route

The following example uses override mode to keep the route-decider instance active while changing the processing settings for matched requests — sending both request headers and the full buffered request body to the processing service instead of headers only.

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteExtProc
metadata:
  name: override-route-decider
  namespace: default
spec:
  statPrefix: route-decider
  mode: override
  overrides:
    processing:
      request:
        headersMode: SEND
        bodyMode: BUFFERED