Route filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. Route filters are scoped to a particular route. Spring Cloud Gateway includes many built-in GatewayFilter Factories.
The AddRequestHeader GatewayFilter Factory takes a name and value parameter.
application.yml.
spring: cloud: gateway: routes: - id: add_request_header_route uri: https://example.org filters: - AddRequestHeader=X-Request-Foo, Bar
This will add X-Request-Foo:Bar
header to the downstream request’s headers for all matching requests.
The AddRequestParameter GatewayFilter Factory takes a name and value parameter.
application.yml.
spring: cloud: gateway: routes: - id: add_request_parameter_route uri: https://example.org filters: - AddRequestParameter=foo, bar
This will add foo=bar
to the downstream request’s query string for all matching requests.
The AddResponseHeader GatewayFilter Factory takes a name and value parameter.
application.yml.
spring: cloud: gateway: routes: - id: add_request_header_route uri: https://example.org filters: - AddResponseHeader=X-Response-Foo, Bar
This will add X-Response-Foo:Bar
header to the downstream response’s headers for all matching requests.
The Hystrix GatewayFilter Factory requires a single name
parameter, which is the name of the HystrixCommand
.
application.yml.
spring: cloud: gateway: routes: - id: hystrix_route uri: https://example.org filters: - Hystrix=myCommandName
This wraps the remaining filters in a HystrixCommand
with command name myCommandName
.
The Hystrix filter can also accept an optional fallbackUri
parameter. Currently, only forward:
schemed URIs are supported. If the fallback is called, the request will be forwarded to the controller matched by the URI.
application.yml.
spring: cloud: gateway: routes: - id: hystrix_route uri: lb://backing-service:8088 predicates: - Path=/consumingserviceendpoint filters: - name: Hystrix args: name: fallbackcmd fallbackUri: forward:/incaseoffailureusethis - RewritePath=/consumingserviceendpoint, /backingserviceendpoint
This will forward to the /incaseoffailureusethis
URI when the Hystrix fallback is called. Note that this example also demonstrates (optional) Spring Cloud Netflix Ribbon load-balancing via the lb
prefix on the destination URI.
The PrefixPath GatewayFilter Factory takes a single prefix
parameter.
application.yml.
spring: cloud: gateway: routes: - id: prefixpath_route uri: https://example.org filters: - PrefixPath=/mypath
This will prefix /mypath
to the path of all matching requests. So a request to /hello
, would be sent to /mypath/hello
.
The PreserveHostHeader GatewayFilter Factory has not parameters. This filter, sets a request attribute that the routing filter will inspect to determine if the original host header should be sent, rather than the host header determined by the http client.
application.yml.
spring: cloud: gateway: routes: - id: preserve_host_route uri: https://example.org filters: - PreserveHostHeader
This will prefix /mypath
to the path of all matching requests. So a request to /hello
, would be sent to /mypath/hello
.
The RequestRateLimiter GatewayFilter Factory takes three parameters: replenishRate
, burstCapacity
& keyResolverName
.
replenishRate
is how many requests per second do you want a user to be allowed to do.
burstCapacity
TODO: document burst capacity
keyResolver
is a bean that implements the KeyResolver
interface. In configuration, reference the bean by name using SpEL. #{@myKeyResolver}
is a SpEL expression referencing a bean with the name myKeyResolver
.
KeyResolver.java.
public interface KeyResolver { Mono<String> resolve(ServerWebExchange exchange); }
The KeyResolver
interface allows pluggable strategies to derive the key for limiting requests. In future milestones, there will be some KeyResolver
implementations.
The redis implementation is based off of work done at Stripe. It requires the use of the spring-boot-starter-data-redis-reactive
Spring Boot starter.
application.yml.
spring: cloud: gateway: routes: - id: requestratelimiter_route uri: https://example.org filters: - RequestRateLimiter=10, 20, #{@userKeyResolver}
Config.java.
@Bean KeyResolver userKeyResolver() { return exchange -> Mono.just(exchange.getRequest().getQueryParams().getFirst("user")); }
This defines a request rate limit of 10 per user. The KeyResolver
is a simple one that gets the user
request parameter (note: this is not recommended for production).
The RedirectTo GatewayFilter Factory takes a status
and a url
parameter. The status should be a 300 series redirect http code, such as 301. The url should be a valid url. This will be the value of the Location
header.
application.yml.
spring: cloud: gateway: routes: - id: prefixpath_route uri: https://example.org filters: - RedirectTo=302, https://acme.org
This will send a status 302 with a Location:https://acme.org
header to perform a redirect.
The RemoveNonProxyHeaders GatewayFilter Factory removes headers from forwarded requests. The default list of headers that is removed comes from the IETF.
The default removed headers are:
To change this, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers
property to the list of header names to remove.
The RemoveRequestHeader GatewayFilter Factory takes a name
parameter. It is the name of the header to be removed.
application.yml.
spring: cloud: gateway: routes: - id: removerequestheader_route uri: https://example.org filters: - RemoveRequestHeader=X-Request-Foo
This will remove the X-Request-Foo
header before it is sent downstream.
The RemoveResponseHeader GatewayFilter Factory takes a name
parameter. It is the name of the header to be removed.
application.yml.
spring: cloud: gateway: routes: - id: removeresponseheader_route uri: https://example.org filters: - RemoveResponseHeader=X-Response-Foo
This will remove the X-Response-Foo
header from the response before it is returned to the gateway client.
The RewritePath GatewayFilter Factory takes a path regexp
parameter and a replacement
parameter. This uses Java regular expressions for a flexible way to rewrite the request path.
application.yml.
spring: cloud: gateway: routes: - id: rewritepath_route uri: https://example.org predicates: - Path=/foo/** filters: - RewritePath=/foo/(?<segment>.*), /$\{segment}
For a request path of /foo/bar
, this will set the path to /bar
before making the downstream request. Notice the $\
which is replaced with $
because of the YAML spec.
The SaveSession GatewayFilter Factory forces a WebSession::save
operation before forwarding the call downstream. This is of particular use when
using something like Spring Session with a lazy data store and need to ensure the session state has been saved before making the forwarded call.
application.yml.
spring: cloud: gateway: routes: - id: save_session uri: https://example.org predicates: - Path=/foo/** filters: - SaveSession
If you are integrating Spring Security with Spring Session, and want to ensure security details have been forwarded to the remote process, this is critical.
The SecureHeaders GatewayFilter Factory adds a number of headers to the response at the reccomendation from this blog post.
The following headers are added (allong with default values):
X-Xss-Protection:1; mode=block
Strict-Transport-Security:max-age=631138519
X-Frame-Options:DENY
X-Content-Type-Options:nosniff
Referrer-Policy:no-referrer
Content-Security-Policy:default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline'
X-Download-Options:noopen
X-Permitted-Cross-Domain-Policies:none
To change the default values set the appropriate property in the spring.cloud.gateway.filter.secure-headers
namespace:
Property to change:
xss-protection-header
strict-transport-security
frame-options
content-type-options
referrer-policy
content-security-policy
download-options
permitted-cross-domain-policies
The SetPath GatewayFilter Factory takes a path template
parameter. It offers a simple way to manipulate the request path by allowing templated segments of the path. This uses the uri templates from Spring Framework. Multiple matching segments are allowed.
application.yml.
spring: cloud: gateway: routes: - id: setpath_route uri: https://example.org predicates: - Path=/foo/{segment} filters: - SetPath=/{segment}
For a request path of /foo/bar
, this will set the path to /bar
before making the downstream request.
The SetResponseHeader GatewayFilter Factory takes name
and value
parameters.
application.yml.
spring: cloud: gateway: routes: - id: setresponseheader_route uri: https://example.org filters: - SetResponseHeader=X-Response-Foo, Bar
This GatewayFilter replaces all headers with the given name, rather than adding. So if the downstream server responded with a X-Response-Foo:1234
, this would be replaced with X-Response-Foo:Bar
, which is what the gateway client would receive.
The SetStatus GatewayFilter Factory takes a single status
parameter. It must be a valid Spring HttpStatus
. It may be the integer value 404
or the string representation of the enumeration NOT_FOUND
.
application.yml.
spring: cloud: gateway: routes: - id: setstatusstring_route uri: https://example.org filters: - SetStatus=BAD_REQUEST - id: setstatusint_route uri: https://example.org filters: - SetStatus=401
In either case, the HTTP status of the response will be set to 401.
The StripPrefix GatewayFilter Factory takes one paramter, parts
. The parts
parameter indicated the number of parts in the path to strip from the request before sending it downstream.
application.yml.
spring: cloud: gateway: routes: - id: nameRoot uri: http://nameservice predicates: - Path=/name/** filters: - StripPrefix=2
When a request is made through the gateway to /name/bar/foo
the request made to nameservice
will look like http://nameservice/foo
.