The open-source Spring Cloud Gateway project includes a number of built-in filters for use in Gateway routes. The following commercial filters provided by Spring Cloud Gateway for VMware Tanzu can be used in addition to those included in the OSS project.

AllowedRequestCookieCount

This filter controls the maximum number of cookies allowed on a request. The filter will respond with a 431 Request Header Fields Too Large error if the number of cookies on a request exceeds the configured integer maximum.

In this example, only requests with two or fewer cookies will be accepted:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["AllowedRequestCookieCount=2"] } ] }'

AllowedRequestHeadersCount

This filter controls the maximum number of headers allowed on a request. The filter will respond with a 431 Request Header Fields Too Large error if the number of headers on a request exceeds the configured integer maximum.

In this example, only requests with four or fewer headers will be accepted:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["AllowedRequestHeadersCount=4"] } ] }'

AllowedRequestQueryParamsCount

This filter controls the maximum number of query parameters allowed on a request. The filter will respond with a 414 URL Too Large error if the number of query parameters on a request exceeds the configured integer maximum.

In this example, only requests with three or fewer query parameters will be accepted:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["AllowedRequestQueryParamsCount=3"] } ] }'

CircuitBreaker

The CircuitBreaker filter reroutes requests to a fallback destination when the intended destination responds with an HTTP error code.

The circuit breaker pattern is a useful approach to bolstering resilience and preventing cascading failures in distributed systems. It works by preventing struggling services from becoming overloaded with failing requests, and thereby giving them the chance to recover.

In electrical systems, a circuit breaker is a switch that triggers on a detected fault, isolating the faulty circuit and preventing further damage. This act is known as opening the circuit breaker (breaking the circuit). When the fault is corrected, the circuit breaker is closed (completing the circuit), allowing current to flow again. The circuit breaker pattern borrows this highly useful technique and terminology and applies it to distributed software systems.

Because our systems must be able to recover autonomously, there is also a half-open state that allows the circuit breaker to detect recovery of the downstream system. Following a timeout after the original detected failure, the circuit breaker will allow trial requests through to the destination system. It will then either fully close, or it will fully open and restart the timeout, based on the response.

In the following example, the CircuitBreaker filter is used to cause requests to /cook/** to fall back to /inCaseOfFailureUseThis, should the service respond with an error code:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters":["CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis"] } ] }'

The CircuitBreaker filter supports several further options that can be appended to its configuration to fine tune its behavior:

  • A colon-separated list of HTTP status codes that will trigger the fallback behavior. These can be expressed in either numerical or text format:

    CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500

  • The percentage failure rate threshold above which the circuit breaker will be opened (default 50%, expressed as a float value):

    CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10

  • The period of time in seconds to wait for downstream service recovery before entering the "half-open" state and attempting to close the circuit breaker again (default 60s).

    CircuitBreaker=myCircuitBreaker,forward:/inCaseOfFailureUseThis,401:NOT_FOUND:500,10,30

Circuit breaker status

By querying for the circuit breaker metrics, you can monitor the status of the circuit breaker:

actuator/metrics/resilience4j.circuitbreaker.state?tag=state:{circuit-breaker-state}&tag=name:{circuit-breaker-name}

Where:

  • {circuit-breaker-state} is one of closed, disabled, half_open, forced_open, open, metrics_only
  • {circuit-breaker-name} is the name of your circuit breaker, e.g. myCircuitBreaker

The metrics endpoint will return a value of 1 in the $.measurements[].value JSON path if the circuit breaker is in this state.

For more more information and other metrics, see Resilience4j CircuitBreaker Metrics.

ClientCertificateHeader

The ClientCertificateHeader filter validates the client SSL certificate used to make a request to an app through the Gateway. You can also use this filter to validate the client certificate's fingerprint.

When adding a route to a Gateway service instance, you can add the ClientCertificateHeader filter by including it in the list of filters for the applicable route.

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["ClientCertificateHeader=*.example.com"] } ] }'

To validate the client SSL certificate's fingerprint, add the name of the hash used for the fingerprint, and the fingerprint value, after the CN, using the following format:

[CN],[HASH]:[FINGERPRINT]

Where:

  • [CN] is the Common Name
  • [HASH] is the hash used for the fingerprint, either sha-1 or sha-256
  • [FINGERPRINT] is the fingerprint value

The following example uses the ClientCertificateHeader filter to ensure that a client certificate uses a CN of *.example.com and a SHA-1 fingerprint of aa:bb:00:99:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["ClientCertificateHeader=*.example.com,sha-1:aa:bb:00:99"] } ] }'

The fingerprint value is not case-sensitive, and the colon character : is not required to separate hexadecimal digits in a fingerprint. The following example works too:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["ClientCertificateHeader=*.example.com,sha-1:AABB0099"] } ] }'

FallbackHeaders

When a circuit breaker "opens" and redirects a request to a fallback destination because the intended destination has returned an exception, it is sometimes useful for the fallback destination to receive information about the failure that just occurred. To facilitate this, the FallbackHeaders filter can be used to write the details of the exception into the headers of any requests forwarded to a fallback route.

The default header names added by the filter, and their values, are:

  • Execution-Exception-Type

    The type (Java class) of the exception that tripped the circuit breaker

  • Execution-Exception-Message

    The message attached to the exception that tripped the circuit breaker

  • Root-Cause-Exception-Type

    The type (Java class) of the root cause exception, if available

  • Root-Cause-Exception-Message

    The message attached to the root cause exception, if available

The example FallbackHeaders filter configuration below adds the exception information from failures in the /cook/** route to the fallback requests made to the /inCaseOfFailureUseThis route:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters":["CircuitBreaker=myCircuitBreaker,forward:/fallback"] }, { "path": "/fallback", "filters": ["FallbackHeaders"]} ] }'

You can optionally configure the names of the headers used by the filter, by appending a comma-separated list to the configuration. The alternative header names must be given in the same order as the default names listed above. So, the following configuration would update the Execution-Exception-Type header name to My-Execution-Exception-Type:

      "FallbackHeaders=My-Execution-Exception-Type, My-Execution-Exception-Message, My-Root-Cause-Exception-Type, My-Root-Cause-Exception-Message"

LocalResponseCache

This filter allows to define a cache that can be applied at route-level. Some considerations must be taken into account when activating this feature:

  • It only handles bodyless GET requests.
  • It only caches the response as long has one of the following status codes: HTTP 200 (OK), HTTP 206 (Partial Content) and HTTP 301 (Moved Permanently).
  • Response data will not be cached if Cache-Control header doesn't allow it (no-store in the request, no-store or private in the response).
  • If response is already cached and a new request is performed with no-cache value in Cache-Control header, it will return a bodiless response with 304 (Not Modified).

It accepts two configuration parameters:

  • the timeToLive parameter sets the time to expire a cache entry (expressed in s for seconds, m for minutes, and h for hours)
  • the size parameter that sets the maximum size of the cache to evict entries for this route (in KB, MB and GB)

If none of these are specified, the default configuration is used. See Configure HTTP response cache.

To add a local response cache of 1 MB with a time to live of 50 s to the /cached/** route, set:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cached/**", "filters": ["LocalResponseCache=50s,1MB"] } ] }'

This filter also implements the automatic calculation of the max-age value in the HTTP Cache-Control header. If max-age is present on the original response, the value will be rewritten with the number of seconds set in the timeToLive configuration parameter. In consecutive calls, this value will be recalculated with the number of seconds remaining until the response expires.

RateLimit

The RateLimit filter limits the number of requests allowed per route during a time window. It can apply rate limits to all requests to a route, or optionally per user, or per source IP address.

By default, Session Management and Rate Limiting use Hazelcast as the default cache implementation. If the operator makes Redis available, developers can opt in to Redis by setting cache to redis. When activated, a Redis service instance is automatically created and bound to the gateway.

Caution Activating Redis for the RateLimit filter implicitly activates the use of Redis for session storage. When updating a running instance, any request count or user session data previously held in Hazelcast will not be migrated.

Rate limiting is activated for a route by adding RateLimit to its list of filters. The RateLimit filter configuration accepts four parameters in the following order:

  1. The maximum number of requests to be accepted during the window.
  2. The duration of the window. By default this is specified in milliseconds, but you can use the s, m, or h suffixes to specify it in seconds, minutes, or hours respectively.
  3. (Optional) User partition key. This allows different rate limits to be specified for different users, based on a user identifier to be found in the request. Set whether the key is to be found in a JWT claim or HTTP header with the {claim:CLAIM_NAME} or {header:HEADER_NAME} syntax.
  4. (Optional) Add the Source IP address if the rate limit should be applied only to requests from a certain source. This cannot be combined with per user rate limits.

Basic rate limiting

The rate limit configuration shown below performs basic limiting of the number of requests allowed during a time window. In this example, a maximum of 1 request to the /cook/** route will be allowed every 10 seconds:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["RateLimit=1,10s"] } ] }'

When requests are made at a rate allowed by the configured limit, the responses will succeed and report the remaining number of requests that can be made within the limit in the X-Remaining HTTP header. When the limit is exceeded, responses will fail with the 429 Too Many Requests error. The remaining time until requests will be allowed again is returned in the X-Retry-In HTTP header (specified in milliseconds).

Per-user rate limiting, partitioned by HTTP header

Here is an example configuration illustrating per-user rate limiting; The user is identified from the contents of an HTTP header. In this example, an API key identifies the user; it is retrieved from the the X-API-Key header:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["RateLimit=1,10s,{header:X-API-Key}"] } ] }'

An individual rate limit of one request per ten seconds will be applied for each group of users sharing the same API key.

When requests for a given X-API-Key header exceed the defined limit in a time window, access will be rejected with a simple 429 Too Many Requests response, with no additional headers.

Per-user rate limiting, partitioned by JWT claim

Similarly, the example configuration shown in this section illustrates per-user rate limiting again, this time with the user being identified by the value of the client-id claim of the JWT authorization token associated with the request:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["RateLimit=1,10s,{claim:client-id}"] } ] }'

When requests for a given client-id value exceed the defined limit in a time window, access will be rejected with a simple 429 Too Many Requests response, with no additional headers.

Limiting by IP address

To limit by IP address, the RateLimit filter configuration accepts a semi-colon separated list of source IP addresses from which to accept requests.

The filter checks the X-Forwarded-For header, if present, for the source IP address of the request. Since multiple IP addresses may have been added to the X-Forwarded-For header by multiple trusted or untrusted proxies, you can optionally set the maximum trusted index of the IP to read from the header by prepending an integer value to the IP address list. The default value of 1 will read the last IP from the header, while a value of 2 will read up to the second from last IP, and so on. The index value must be greater than zero.

Here is an example configuration to rate limit by IP address:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["RateLimit=1,10s,{IPs:2;127.0.0.1;192.168.0.1}"] } ] }'

In this example, a maximum of 1 request is allowed in a 10s window, as long as it originates from any of the configured IPs: 127.0.0.1 and 192.168.0.1.

The maximum trusted index to read from the X-Forwarded-For header is set to 2. If, for example, the X-Forwarded-For header had a value of 4.4.4.4, 8.8.8.8, 127.0.0.1, the gateway would return 403 Forbidden because the second-last IP, 8.8.8.8, is not in the allowed list. However, if the header was instead set to 4.4.4.4, 127.0.0.1, 8.8.8.8, then the gateway would return successfully, because the second-last IP would then be 127.0.0.1, and this is in the allowed list.

RestrictRequestHeaders

This filter controls the HTTP headers that are allowed on a request. If there are any HTTP headers that are not in the header list configuration (case insensitive), then a response of 403 Forbidden error will be returned to the client.

In this example, only requests with "Content-Type" and "X-Request-Temp" headers will be accepted:

$ cf bind-service cook my-gateway -c '{ "routes": [ { "path": "/cook/**", "filters": ["RestrictRequestHeaders=Content-Type,x-request-temp] } ] }'

The gateway filter will automatically allow the following case insensitive headers that are added by the CF Gorouter:

  • b3
  • x-b3-spanid
  • x-b3-traceid
  • x-cf-app-instance
  • x-cf-applicationid
  • x-cf-instanceid
  • x-cf-instanceindex
  • x-forwarded-for
  • x-forwarded-proto
  • x-request-start
  • x-vcap-request-id
  • x-vcap-trace
check-circle-line exclamation-circle-line close-line
Scroll to top icon