HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Consul Home

RouteUpstreamLimitsFilter resource configuration reference

This topic provides configuration reference information for the RouteUpstreamLimitsFilter resource. The resource defines upstream circuit-breaker limits and passive health checks for a backend service that an HTTPRoute attached to an API gateway routes traffic to.

Introduction

Passive health checks configure Envoy outlier detection on the API gateway. When an instance of the backend service returns consecutive errors, the gateway removes the instance from its load balancing pool and sends requests to the remaining healthy instances. Circuit-breaker limits restrict the number of connections and requests that the gateway sends to the backend service.

To apply the filter to a backend service, add an ExtensionRef filter to the backend in the rules.backendRefs.filters field of an HTTPRoute. Set extensionRef.group to consul.hashicorp.com, extensionRef.kind to RouteUpstreamLimitsFilter, 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 translates the filter into the Limits field of the corresponding service in the http-route configuration entry. Refer to Rules[].Services[].Limits in the HTTP route configuration entry reference for additional information.

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

Gateway-wide defaults

To configure limits and passive health checks for every backend service behind a gateway, add api-gateway.consul.hashicorp.com/default-* annotations to the Gateway resource. Refer to Gateway annotations for additional information.

Values in a RouteUpstreamLimitsFilter override the gateway-wide defaults for the backend service in the following ways:

  • Circuit-breaker limits: Each limit that you set in the filter overrides the corresponding gateway default. Limits that you do not set in the filter inherit the gateway default.
  • Passive health check: When you set spec.passiveHealthCheck in the filter, it replaces the gateway default passive health check for the backend service. Consul does not merge individual passive health check fields.

Configuration model

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

Complete configuration

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

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteUpstreamLimitsFilter
metadata:
  name: <name of the filter>
  namespace: <namespace of the HTTPRoute>
spec:
  maxConnections: <number>
  maxPendingRequests: <number>
  maxConcurrentRequests: <number>
  passiveHealthCheck:
    interval: <time between ejection analysis sweeps>
    maxFailures: <number>
    enforcingConsecutive5xx: <percentage>
    maxEjectionPercent: <percentage>
    baseEjectionTime: <base ejection duration>

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 RouteUpstreamLimitsFilter.

Values

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

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 backend 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 upstream limits and passive health check settings. The apiVersion, kind, and metadata fields are siblings of the spec field. All other configurations are children.

spec.maxConnections

Specifies the maximum number of connections that the gateway can establish to the backend service.

Values

  • Default: None. If unspecified, Consul uses the gateway-wide default when available. Otherwise, Envoy uses 1024.
  • Data type: Integer greater than or equal to 0

spec.maxPendingRequests

Specifies the maximum number of requests that can queue while waiting for a connection to the backend service.

Values

  • Default: None. If unspecified, Consul uses the gateway-wide default when available. Otherwise, Envoy uses 1024.
  • Data type: Integer greater than or equal to 0

spec.maxConcurrentRequests

Specifies the maximum number of concurrent requests that the gateway can send to the backend service.

Values

  • Default: None. If unspecified, Consul uses the gateway-wide default when available. Otherwise, Envoy uses 1024.
  • Data type: Integer greater than or equal to 0

spec.passiveHealthCheck

Specifies the passive health check for the backend service. The passive health check configures Envoy outlier detection on the gateway cluster for the backend service.

When set, this value replaces the gateway-wide default passive health check for the backend service.

Values

  • Default: None. If unspecified, Consul uses the gateway-wide default when available. Otherwise, Envoy uses its default outlier detection settings.
  • Data type: Map

spec.passiveHealthCheck.interval

Specifies the time between outlier detection analysis sweeps. Each sweep can eject hosts from the load balancing pool or return them to the pool.

Values

  • Default: None. Envoy uses 10s.
  • Data type: String duration, such as 10s

spec.passiveHealthCheck.maxFailures

Specifies the number of consecutive 5xx errors that cause Envoy to eject a host from the load balancing pool.

Values

  • Default: None. Envoy uses 5.
  • Data type: Integer

spec.passiveHealthCheck.enforcingConsecutive5xx

Specifies the percent chance that Envoy ejects a host when it detects an outlier status through consecutive 5xx errors. Use this setting to turn off ejection or ramp it up gradually.

Values

  • Default: None. Envoy uses 100.
  • Data type: Integer from 0 to 100

spec.passiveHealthCheck.maxEjectionPercent

Specifies the maximum percentage of hosts for the backend service that Envoy can eject at the same time. Envoy ejects at least one host regardless of the value.

Values

  • Default: None. Envoy uses 10.
  • Data type: Integer from 0 to 100

spec.passiveHealthCheck.baseEjectionTime

Specifies the base amount of time that an ejected host stays out of the load balancing pool. The actual ejection time equals the base ejection time multiplied by the number of times Envoy has ejected the host, up to a maximum of 300s.

Values

  • Default: None. Envoy uses 30s.
  • Data type: String duration, such as 30s

Example

The following example limits the gateway to 25 connections to the static-server service. The gateway ejects a static-server instance after three consecutive 5xx errors and can eject up to half of the instances at the same time:

apiVersion: consul.hashicorp.com/v1alpha1
kind: RouteUpstreamLimitsFilter
metadata:
  name: static-server-limits
  namespace: default
spec:
  maxConnections: 25
  maxPendingRequests: 50
  maxConcurrentRequests: 100
  passiveHealthCheck:
    interval: 10s
    maxFailures: 3
    enforcingConsecutive5xx: 100
    maxEjectionPercent: 50
    baseEjectionTime: 30s
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: limits-route
  namespace: default
spec:
  parentRefs:
    - name: my-gateway
  rules:
    - backendRefs:
        - name: static-server
          port: 80
          filters:
            - type: ExtensionRef
              extensionRef:
                group: consul.hashicorp.com
                kind: RouteUpstreamLimitsFilter
                name: static-server-limits
Edit this page on GitHub