spring:
+ cloud:
+ gateway:
+ routes:
+ - id: after_route
+ uri: https://example.org
+ predicates:
+ - Cookie=mycookie,mycookievalueGatewayFilter Factories
+GatewayFilter Factories
AddRequestHeader GatewayFilter FactoryAddRequestParameter GatewayFilter FactoryAddResponseHeader GatewayFilter FactoryDedupeResponseHeader GatewayFilter FactoryFallbackHeaders GatewayFilter FactoryMapRequestHeader GatewayFilter FactoryPrefixPath GatewayFilter FactoryPreserveHostHeader GatewayFilter FactoryRequestRateLimiter GatewayFilter Factory
+AddRequestHeader GatewayFilter FactoryAddRequestParameter GatewayFilter FactoryAddResponseHeader GatewayFilter FactoryDedupeResponseHeader GatewayFilter FactoryFallbackHeaders GatewayFilter FactoryMapRequestHeader GatewayFilter FactoryPrefixPath GatewayFilter FactoryPreserveHostHeader GatewayFilter FactoryRequestRateLimiter GatewayFilter Factory
RedirectTo GatewayFilter FactoryRemoveHopByHopHeadersFilter GatewayFilter FactoryRemoveRequestHeader GatewayFilter FactoryRemoveResponseHeader GatewayFilter FactoryRemoveRequestParameter GatewayFilter FactoryRewritePath GatewayFilter FactoryRewriteLocationResponseHeader GatewayFilter FactoryRewriteResponseHeader GatewayFilter FactorySaveSession GatewayFilter FactorySecureHeaders GatewayFilter FactorySetPath GatewayFilter FactorySetRequestHeader GatewayFilter FactorySetResponseHeader GatewayFilter FactorySetStatus GatewayFilter FactoryStripPrefix GatewayFilter FactoryGatewayFilter FactoryRequestSize GatewayFilter FactoryGatewayFilter FactoryGatewayFilter FactoryRedirectTo GatewayFilter FactoryRemoveRequestHeader GatewayFilter FactoryRemoveResponseHeader GatewayFilter FactoryRemoveRequestParameter GatewayFilter FactoryRewritePath GatewayFilter FactoryRewriteLocationResponseHeader GatewayFilter FactoryRewriteResponseHeader GatewayFilter FactorySaveSession GatewayFilter FactorySecureHeaders GatewayFilter FactorySetPath GatewayFilter FactorySetRequestHeader GatewayFilter FactorySetResponseHeader GatewayFilter FactorySetStatus GatewayFilter FactoryStripPrefix GatewayFilter FactoryGatewayFilter FactoryRequestSize GatewayFilter FactoryGatewayFilter FactoryGatewayFilter FactoryGatewayFilter OrderingLoadBalancerClient FilterReactiveLoadBalancerClientFilterRouteToRequestUrl FilterGatewayFilter OrderingLoadBalancerClient FilterReactiveLoadBalancerClientFilterRouteToRequestUrl FilterThere are two ways to configure predicates and filters: shortcuts and fully expanded arguments. Most examples below use the shortcut way.
+The name and argument names will be listed as code in the first sentance or two of the each section. The arguments are typically listed in the order that would be needed for the shortcut configuration.
Shortcut configuration is recognized by the filter name, followed by an equals sign (=), followed by argument values separated by commas (,).
spring:
+ cloud:
+ gateway:
+ routes:
+ - id: after_route
+ uri: https://example.org
+ predicates:
+ - Cookie=mycookie,mycookievalueThe previous sample defines the Cookie Route Predicate Factory with two arguments, the cookie name, mycookie and the value to match mycookievalue.
Fully expanded arguments appear more like standard yaml configuration with name/value pairs. Typically, there will be a name key and an args key. The args key is a map of key value pairs to configure the predicate or filter.
spring:
+ cloud:
+ gateway:
+ routes:
+ - id: after_route
+ uri: https://example.org
+ predicates:
+ - name: Cookie
+ args:
+ name: mycookie
+ regexp: mycookievalueThis is the full configuration of the shortcut configuration of the Cookie predicate shown above.
Spring Cloud Gateway matches routes as part of the Spring WebFlux HandlerMapping infrastructure.
@@ -338,9 +407,9 @@ All of these predicates match on different attributes of the HTTP request.
You can combine multiple route predicate factories with logical and statements.
The after route predicate factory takes one parameter, a datetime. +
The After route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime).
This predicate matches requests that happen after the specified datetime.
The following example configures an after route predicate:
The before route predicate factory takes one parameter, a datetime.
+
The Before route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime).
This predicate matches requests that happen before the specified datetime.
The following example configures a before route predicate:
The between route predicate factory takes two parameters, datetime1 and datetime2.
+
The Between route predicate factory takes two parameters, datetime1 and datetime2
+which are java ZonedDateTime objects.
This predicate matches requests that happen after datetime1 and before datetime2.
The datetime2 parameter must be after datetime1.
The following example configures a between route predicate:
The cookie route predicate factory takes two parameters, the cookie name and a regular expression. +
The Cookie route predicate factory takes two parameters, the cookie name and a regexp (which is a Java regular expression).
This predicate matches cookies that have the given name and whose values match the regular expression.
The following example configures a cookie route predicate factory:
The header route predicate factory takes two parameters, the header name and a regular expression. +
The Header route predicate factory takes two parameters, the header name and a regexp (which is a Java regular expression).
This predicate matches with a header that has the given name whose value matches the regular expression.
The following example configures a header route predicate:
The host route predicate factory takes one parameter: a list of host name patterns. +
The Host route predicate factory takes one parameter: a list of host name patterns.
The pattern is an Ant-style pattern with . as the separator.
This predicates matches the Host header that matches the pattern.
The following example configures a host route predicate:
The Method Route Predicate Factory takes one or more parameters: the HTTP methods to match. +
The Method Route Predicate Factory takes a methods argument which is one or more parameters: the HTTP methods to match.
The following example configures a method route predicate:
The Path Route Predicate Factory takes two parameters: a list of Spring PathMatcher patterns and an optional flag called matchOptionalTrailingSeparator.
+
The Path Route Predicate Factory takes two parameters: a list of Spring PathMatcher patterns and an optional flag called matchOptionalTrailingSeparator.
The following example configures a path route predicate:
The query route predicate factory takes two parameters: a required param and an optional regexp.
+
The Query route predicate factory takes two parameters: a required param and an optional regexp (which is a Java regular expression).
The following example configures a query route predicate:
The RemoteAddr route predicate factory takes a list (min size 1) of CIDR-notation (IPv4 or IPv6) strings, such as 192.168.0.1/16 (where 192.168.0.1 is an IP address and 16 is a subnet mask).
+
The RemoteAddr route predicate factory takes a list (min size 1) of sources, which are CIDR-notation (IPv4 or IPv6) strings, such as 192.168.0.1/16 (where 192.168.0.1 is an IP address and 16 is a subnet mask).
The following example configures a RemoteAddr route predicate:
The weight route predicate factory takes two arguments: group and weight. The weights are calculated per group. +
The Weight route predicate factory takes two arguments: group and weight (an int). The weights are calculated per group.
The following example configures a weight route predicate:
This route would forward ~80% of traffic to weighthigh.org and ~20% of traffic to weighlow.org
By default, the RemoteAddr route predicate factory uses the remote address from the incoming request. This may not match the actual client IP address if Spring Cloud Gateway sits behind a proxy layer.
@@ -792,7 +862,7 @@ If two hops of trusted infrastructure are required before Spring Cloud Gateway iGatewayFilter FactoriesGatewayFilter FactoriesRoute filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. @@ -812,9 +882,9 @@ For more detailed examples of how to use any of the following filters, take a lo
AddRequestHeader GatewayFilter FactoryAddRequestHeader GatewayFilter FactoryThe AddRequestHeader GatewayFilter factory takes a name and value parameter.
+
The AddRequestHeader GatewayFilter factory takes a name and value parameter.
The following example configures an AddRequestHeader GatewayFilter:
AddRequestHeader GatewayF
AddRequestParameter GatewayFilter FactoryAddRequestParameter GatewayFilter FactoryThe AddRequestParameter GatewayFilter Factory takes a name and value parameter.
+
The AddRequestParameter GatewayFilter Factory takes a name and value parameter.
The following example configures an AddRequestParameter GatewayFilter:
AddRequestParameter Gatew
AddResponseHeader GatewayFilter FactoryAddResponseHeader GatewayFilter FactoryThe AddResponseHeader GatewayFilter Factory takes a name and value parameter.
+
The AddResponseHeader GatewayFilter Factory takes a name and value parameter.
The following example configures an AddResponseHeader GatewayFilter:
AddResponseHeader Gateway
DedupeResponseHeader GatewayFilter FactoryDedupeResponseHeader GatewayFilter FactoryThe DedupeResponseHeader GatewayFilter factory takes a name parameter and an optional strategy parameter. name can contain a space-separated list of header names.
The following example configures a DedupeResponseHeader GatewayFilter:
RETAIN_FIRST (default), RETAIN_LAST
The Spring Cloud CircuitBreaker GatewayFilter factory uses the Spring Cloud CircuitBreaker APIs to wrap Gateway routes in a circuit breaker. Spring Cloud CircuitBreaker supports two libraries that can be used with Spring Cloud Gateway, Hystrix @@ -1133,7 +1203,7 @@ You can find more information on doing so in the Fa
FallbackHeaders GatewayFilter FactoryFallbackHeaders GatewayFilter FactoryThe FallbackHeaders factory lets you add Hystrix or Spring Cloud CircuitBreaker execution exception details in the headers of a request forwarded to a fallbackUri in an external application, as in the following scenario:
MapRequestHeader GatewayFilter FactoryMapRequestHeader GatewayFilter FactoryThe MapRequestHeader GatewayFilter factory takes fromHeader and toHeader parameters.
It creates a new named header (toHeader), and the value is extracted out of an existing named header (fromHeader) from the incoming http request.
@@ -1225,7 +1295,7 @@ The following example configures a MapRequestHeader:
PrefixPath GatewayFilter FactoryPrefixPath GatewayFilter FactoryThe PrefixPath GatewayFilter factory takes a single prefix parameter.
The following example configures a PrefixPath GatewayFilter:
/hello would be sent to /mypath/hello.
PreserveHostHeader GatewayFilter FactoryPreserveHostHeader GatewayFilter FactoryThe PreserveHostHeader GatewayFilter factory has no parameters.
This filter sets a request attribute that the routing filter inspects to determine if the original host header should be sent, rather than the host header determined by the HTTP client.
@@ -1278,7 +1348,7 @@ The following example configures a PreserveHostHeader Gateway
RequestRateLimiter GatewayFilter FactoryRequestRateLimiter GatewayFilter FactoryThe RequestRateLimiter GatewayFilter factory uses a RateLimiter implementation to determine if the current request is allowed to proceed. If it is not, a status of HTTP 429 - Too Many Requests (by default) is returned.
RateLimiterRateLimiterThe 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.
KeyResolver
RedirectTo GatewayFilter FactoryRedirectTo GatewayFilter FactoryThe RedirectTo GatewayFilter factory takes two parameters, status and url.
The status parameter should be a 300 series redirect HTTP code, such as 301.
@@ -1463,46 +1533,7 @@ The following listing configures a RedirectTo GatewayFilter
RemoveHopByHopHeadersFilter GatewayFilter FactoryThe RemoveHopByHopHeadersFilter GatewayFilter Factory removes headers from forwarded requests.
-The default list of headers that is removed comes from the IETF.
Connection
Keep-Alive
Proxy-Authenticate
Proxy-Authorization
TE
Trailer
Transfer-Encoding
Upgrade
To change the removed headers, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers property to the list of header names to remove.
RemoveRequestHeader GatewayFilter FactoryRemoveRequestHeader GatewayFilter FactoryThe RemoveRequestHeader GatewayFilter factory takes a name parameter.
It is the name of the header to be removed.
@@ -1530,7 +1561,7 @@ The following listing configures a RemoveRequestHeader Gatewa
RemoveResponseHeader GatewayFilter FactoryRemoveResponseHeader GatewayFilter FactoryThe RemoveResponseHeader GatewayFilter factory takes a name parameter.
It is the name of the header to be removed.
@@ -1562,7 +1593,7 @@ In addition, you can configure this filter once by using spring.cloud.gate
RemoveRequestParameter GatewayFilter FactoryRemoveRequestParameter GatewayFilter FactoryThe RemoveRequestParameter GatewayFilter factory takes a name parameter.
It is the name of the query parameter to be removed.
@@ -1590,7 +1621,7 @@ The following example configures a RemoveRequestParameter Gat
RewritePath GatewayFilter FactoryRewritePath GatewayFilter FactoryThe 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.
@@ -1620,7 +1651,7 @@ The following listing configures a RewritePath GatewayFilter<
RewriteLocationResponseHeader GatewayFilter FactoryRewriteLocationResponseHeader GatewayFilter FactoryThe RewriteLocationResponseHeader GatewayFilter factory modifies the value of the Location response header, usually to get rid of backend-specific details.
It takes stripVersionMode, locationHeaderName, hostValue, and protocolsRegex parameters.
@@ -1673,7 +1704,7 @@ The default is http|https|ftp|ftps.
RewriteResponseHeader GatewayFilter FactoryRewriteResponseHeader GatewayFilter FactoryThe RewriteResponseHeader GatewayFilter factory takes name, regexp, and replacement parameters.
It uses Java regular expressions for a flexible way to rewrite the response header value.
@@ -1702,7 +1733,7 @@ You must use $\ to mean $ because of the YAML specific
SaveSession GatewayFilter FactorySaveSession GatewayFilter FactoryThe 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 you need to ensure the session state has been saved before making the forwarded call.
@@ -1732,7 +1763,7 @@ The following example configures a SaveSession GatewayFilter<
SecureHeaders GatewayFilter FactorySecureHeaders GatewayFilter FactoryThe SecureHeaders GatewayFilter factory adds a number of headers to the response, per the recommendation made in this blog post.
SetPath GatewayFilter FactorySetPath GatewayFilter FactoryThe 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.
@@ -1858,7 +1889,7 @@ The following example configures a SetPath GatewayFilter
SetRequestHeader GatewayFilter FactorySetRequestHeader GatewayFilter FactoryThe SetRequestHeader GatewayFilter factory takes name and value parameters.
The following listing configures a SetRequestHeader GatewayFilter:
SetRequestHeader GatewayF
SetResponseHeader GatewayFilter FactorySetResponseHeader GatewayFilter FactoryThe SetResponseHeader GatewayFilter factory takes name and value parameters.
The following listing configures a SetResponseHeader GatewayFilter:
SetResponseHeader Gateway
SetStatus GatewayFilter FactorySetStatus GatewayFilter FactoryThe SetStatus GatewayFilter factory takes a single parameter, status.
It must be a valid Spring HttpStatus.
@@ -2013,7 +2044,7 @@ The header is added to the response if configured with the following property:
StripPrefix GatewayFilter FactoryStripPrefix GatewayFilter FactoryThe StripPrefix GatewayFilter factory takes one parameter, parts.
The parts parameter indicates the number of parts in the path to strip from the request before sending it downstream.
@@ -2043,9 +2074,9 @@ The following listing configures a StripPrefix GatewayFilter<
GatewayFilter FactoryGatewayFilter FactoryThe Retry GatewayFilter factory supports the following parameters:
The Retry GatewayFilter factory supports the following parameters:
basedOnPreviousValue is true, the backoff is calculated byusing
args:
retries: 3
statuses: BAD_GATEWAY
+ methods: GET,POST
backoff:
firstBackoff: 10ms
maxBackoff: 50ms
@@ -2131,18 +2163,6 @@ If basedOnPreviousValue is true, the backoff is calculated byusing
| - - | -
When using the retry filter with a forward: prefixed URL, the target endpoint should be written carefully so that, in case of an error, it does not do anything that could result in a response being sent to the client and committed.
For example, if the target endpoint is an annotated controller, the target controller method should not return ResponseEntity with an error status code.
Instead, it should throw an Exception or signal an error (for example, through a Mono.error(ex) return value), which the retry filter can be configured to handle by retrying.
@@ -2150,12 +2170,25 @@ Instead, it should throw an Exception or signal an error (for examp
|
| + + | +
+When using the retry filter with any HTTP method with a body, the body will be cached and the gateway will become memory constrained. The body is cached in a request attribute defined by ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR. The type of the object is a org.springframework.core.io.buffer.DataBuffer.
+ |
+
RequestSize GatewayFilter FactoryRequestSize GatewayFilter FactoryWhen the request size is greater than the permissible limit, the RequestSize GatewayFilter factory can restrict a request from reaching the downstream service.
-The filter takes a RequestSize parameter.
+The filter takes a maxSize parameter.
+The maxSize is a `DataSize type, so values can be defined as a number followed by an optional DataUnit suffix such as 'KB' or 'MB'. The default is 'B' for bytes.
It is the permissible size limit of the request defined in bytes.
The following listing configures a RequestSize GatewayFilter:
GatewayFilter Factory| - - | --This filter is considered BETA, and the API may change in the future. - | -
GatewayFilter FactoryYou can use this filter to modify the request body before it is sent downstream by the gateway.
+You can use the ModifyRequestBody filter filter to modify the request body before it is sent downstream by the gateway.
| - - | --This filter is considered BETA and the API may change in the future. - | -
GatewayFilter FactoryYou can use this filter to modify the response body before it is sent back to the client.
+You can use the ModifyResponseBody filter to modify the response body before it is sent back to the client.
GatewayFilter OrderingGatewayFilter OrderingWhen a request matches a route, the filtering web handler adds all instances of GlobalFilter and all route-specific instances of GatewayFilter to a filter chain.
This combined filter chain is sorted by the org.springframework.core.Ordered interface, which you can set by implementing the getOrder() method.
The ForwardRoutingFilter looks for a URI in the exchange attribute ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR.
If the URL has a forward scheme (such as forward:///localendpoint), it uses the Spring DispatcherHandler to handle the request.
@@ -2417,7 +2426,7 @@ The unmodified original URL is appended to the list in the ServerWebExchan
LoadBalancerClient FilterLoadBalancerClient FilterThe LoadBalancerClientFilter looks for a URI in the exchange attribute named ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR.
If the URL has a scheme of lb (such as lb://myservice), it uses the Spring Cloud LoadBalancerClient to resolve the name (myservice in this case) to an actual host and port and replaces the URI in the same attribute.
@@ -2492,7 +2501,7 @@ You can switch to it by setting the value of the spring.cloud.loadbalancer
ReactiveLoadBalancerClientFilterReactiveLoadBalancerClientFilterThe ReactiveLoadBalancerClientFilter looks for a URI in the exchange attribute named ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR.
If the URL has a lb scheme (such as lb://myservice), it uses the Spring Cloud ReactorLoadBalancer to resolve the name (myservice in this example) to an actual host and port and replaces the URI in the same attribute.
@@ -2549,7 +2558,7 @@ However, if GATEWAY_SCHEME_PREFIX_ATTR is specified for the route i
The Netty routing filter runs if the URL located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a http or https scheme.
It uses the Netty HttpClient to make the downstream proxy request.
@@ -2558,7 +2567,7 @@ The response is put in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR
The NettyWriteResponseFilter runs if there is a Netty HttpClientResponse in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR exchange attribute.
It runs after all other filters have completed and writes the proxy response back to the gateway client response.
@@ -2566,7 +2575,7 @@ It runs after all other filters have completed and writes the proxy response bac
RouteToRequestUrl FilterRouteToRequestUrl FilterIf there is a Route object in the ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR exchange attribute, the RouteToRequestUrlFilter runs.
It creates a new URI, based off of the request URI but updated with the URI attribute of the Route object.
@@ -2577,7 +2586,7 @@ The new URI is placed in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_AT
If the URL located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a ws or wss scheme, the websocket routing rilter runs. It uses the Spring WebSocket infrastructure to forward the websocket request downstream.
To enable gateway metrics, add spring-boot-starter-actuator as a project dependency. Then, by default, the gateway metrics filter runs as long as the property spring.cloud.gateway.metrics.enabled is not set to false. This filter adds a timer metric named gateway.requests with the following tags:
micrometer-registry-prometheus
After the gateway has routed a ServerWebExchange, it marks that exchange as “routed” by adding gatewayAlreadyRouted
to the exchange attributes. Once a request has been marked as routed, other routing filters will not route the request again,
@@ -2688,7 +2697,109 @@ or check if an exchange has already been routed.
HttpHeadersFilters are applied to requests before sending them downstream, such as in the NettyRoutingFilter.
The Forwarded Headers Filter creates a Forwarded header to send to the downstream service. It adds the Host header, scheme and port of the current request to any existing Forwarded header.
The RemoveHopByHop Headers Filter removes headers from forwarded requests. The default list of headers that is removed comes from the IETF.
Connection
+Keep-Alive
+Proxy-Authenticate
+Proxy-Authorization
+TE
+Trailer
+Transfer-Encoding
+Upgrade
+To change this, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers property to the list of header names to remove.
The XForwarded Headers Filter creates various a X-Forwarded-* headers to send to the downstream service. It users the Host header, scheme, port and path of the current request to create the various headers.
Creating of individual headers can be controlled by the following boolean properties (defaults to true):
+spring.cloud.gateway.x-forwarded.for.enabled
spring.cloud.gateway.x-forwarded.host.enabled
spring.cloud.gateway.x-forwarded.port.enabled
spring.cloud.gateway.x-forwarded.proto.enabled
spring.cloud.gateway.x-forwarded.prefix.enabled
Appending multiple headers can be controlled by the following boolean properties (defaults to true):
+spring.cloud.gateway.x-forwarded.for.append
spring.cloud.gateway.x-forwarded.host.append
spring.cloud.gateway.x-forwarded.port.append
spring.cloud.gateway.x-forwarded.proto.append
spring.cloud.gateway.x-forwarded.prefix.append
The gateway can listen for requests on HTTPS by following the usual Spring server configuration. @@ -2754,7 +2865,7 @@ For a production deployment, you can configure the gateway with a set of known c
If the Spring Cloud Gateway is not provisioned with trusted certificates, the default trust store is used (which you can override by setting the javax.net.ssl.trustStore system property).
The gateway maintains a client pool that it uses to route to backends. When communicating over HTTPS, the client initiates a TLS handshake. @@ -2782,7 +2893,7 @@ You can configure these timeouts can be configured (defaults shown) as follows:<
Configuration for Spring Cloud Gateway is driven by a collection of RouteDefinitionLocator instances.
@@ -2836,7 +2947,7 @@ The following two examples are equivalent:
You can configure additional parameters for each route by using metadata, as follows:
@@ -2880,13 +2991,13 @@ route.getMetadata(someKey);Http timeouts (response and connect) can be configured for all routes and overridden for each specific route.
To configure Global http timeouts:
connect-timeout must be specified in milliseconds.
@@ -2905,7 +3016,7 @@ route.getMetadata(someKey);
To configure per-route timeouts:
connect-timeout must be specified in milliseconds.
@@ -2947,7 +3058,7 @@ import static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPO
To allow for simple configuration in Java, the RouteLocatorBuilder bean includes a fluent API.
The following listing shows how it works:
and(), or()
DiscoveryClient Route Definition LocatorDiscoveryClient Route Definition LocatorYou can configure the gateway to create routes based on services registered with a DiscoveryClient compatible service registry.
and(), or()To enable this, set spring.cloud.gateway.discovery.locator.enabled=true and make sure a DiscoveryClient implementation (such as Netflix Eureka, Consul, or Zookeeper) is on the classpath and enabled.
DiscoveryClient RoutesDiscoveryClient RoutesBy default, the fateway defines a single predicate and filter for routes created with a DiscoveryClient.
To enable Reactor Netty access logs, set -Dreactor.netty.http.server.accessLogEnabled=true.
You can configure the gateway to control CORS behavior. The “global” CORS configuration is a map of URL patterns to Spring Framework CorsConfiguration.
@@ -3121,7 +3232,7 @@ This is useful when you try to support CORS preflight requests and your route pr
The /gateway actuator endpoint lets you monitor and interact with a Spring Cloud Gateway application.
@@ -3140,7 +3251,7 @@ management.endpoints.web.exposure.include=gateway
A new, more verbose format has been added to Spring Cloud Gateway.
It adds more detail to each route, letting you view the predicates and filters associated with each route along with any configuration that is available.
@@ -3185,7 +3296,7 @@ The following example configures /actuator/gateway/routes:
This section details how to retrieve route filters, including:
/actuator/gateway/routes:
To retrieve the global filters applied to all routes, make a GET request to /actuator/gateway/globalfilters. The resulting response is similar to the following:
To retrieve the GatewayFilter factories applied to routes, make a GET request to /actuator/gateway/routefilters.
The resulting response is similar to the following:
null value is due to an incomplete implementation of
To clear the routes cache, make a POST request to /actuator/gateway/refresh.
The request returns a 200 without a response body.
To retrieve the routes defined in the gateway, make a GET request to /actuator/gateway/routes.
The resulting response is similar to the following:
To retrieve information about a single route, make a GET request to /actuator/gateway/routes/{id} (for example, /actuator/gateway/routes/first_route).
The resulting response is similar to the following:
To create a route, make a POST request to /gateway/routes/{id_route_to_create} with a JSON body that specifies the fields of the route (see Retrieving Information about a Particular Route).
The folloiwng table below summarizes the Spring Cloud Gateway actuator endpoints (note that each endpoint has /actuator/gateway as the base-path):
This section covers common problems that may arise when you use Spring Cloud Gateway.
The following loggers may contain valuable troubleshooting information at the DEBUG and TRACE levels:
The Reactor Netty HttpClient and HttpServer can have wiretap enabled.
When combined with setting the reactor.netty log level to DEBUG or TRACE, it enables the logging of information, such as headers and bodies sent and received across the wire.
@@ -3515,19 +3626,47 @@ To enable wiretap, set spring.cloud.gateway.httpserver.wiretap=true
TODO: overview of writing custom integrations
+These are basic guides to writing some custom components of the gateway.
TODO: document writing Custom Route Predicate Factories
+In order to write a Route Predicate you will need to implement RoutePredicateFactory. There is an abstract class called AbstractRoutePredicateFactory which you can extend.
public class MyRoutePredicateFactory extends AbstractRoutePredicateFactory<HeaderRoutePredicateFactory.Config> {
+
+ public MyRoutePredicateFactory() {
+ super(Config.class);
+ }
+
+ @Override
+ public Predicate<ServerWebExchange> apply(Config config) {
+ // grab configuration from Config object
+ return exchange -> {
+ //grab the request
+ ServerHttpRequest request = exchange.getRequest();
+ //take information from the request to see if it
+ //matches configuration.
+ return matches(config, request);
+ };
+ }
+
+ public static class Config {
+ //Put the configuration properties for your filter here
+ }
+
+}To write a GatewayFilter, you must implement GatewayFilterFactory.
You can extend an abstract class called AbstractGatewayFilterFactory.
@@ -3594,7 +3733,7 @@ The following examples show how to do so:
To write a custom global filter, you must implement GlobalFilter interface.
This applies the filter to all requests.
TODO: document writing Custom Route Locators and Writers
-| + + | ++The following describes an alternative style gateway. None of the prior documentation applies to what follows. + | +
Spring Cloud Gateway provides a utility object called ProxyExchange.
You can use it inside a regular Spring web handler as a method parameter.
@@ -3737,7 +3882,7 @@ The mapper is a Function that takes the incoming ResponseEnti
To see the list of all Spring Cloud Gateway related configuration properties, see the appendix.
diff --git a/reference/html/spring-cloud-gateway.html b/reference/html/spring-cloud-gateway.html index 8f14183e..a9484eb1 100644 --- a/reference/html/spring-cloud-gateway.html +++ b/reference/html/spring-cloud-gateway.html @@ -99,130 +99,141 @@ $(addBlockSwitches);GatewayFilter Factories
+GatewayFilter Factories
AddRequestHeader GatewayFilter FactoryAddRequestParameter GatewayFilter FactoryAddResponseHeader GatewayFilter FactoryDedupeResponseHeader GatewayFilter FactoryFallbackHeaders GatewayFilter FactoryMapRequestHeader GatewayFilter FactoryPrefixPath GatewayFilter FactoryPreserveHostHeader GatewayFilter FactoryRequestRateLimiter GatewayFilter Factory
+AddRequestHeader GatewayFilter FactoryAddRequestParameter GatewayFilter FactoryAddResponseHeader GatewayFilter FactoryDedupeResponseHeader GatewayFilter FactoryFallbackHeaders GatewayFilter FactoryMapRequestHeader GatewayFilter FactoryPrefixPath GatewayFilter FactoryPreserveHostHeader GatewayFilter FactoryRequestRateLimiter GatewayFilter Factory
RedirectTo GatewayFilter FactoryRemoveHopByHopHeadersFilter GatewayFilter FactoryRemoveRequestHeader GatewayFilter FactoryRemoveResponseHeader GatewayFilter FactoryRemoveRequestParameter GatewayFilter FactoryRewritePath GatewayFilter FactoryRewriteLocationResponseHeader GatewayFilter FactoryRewriteResponseHeader GatewayFilter FactorySaveSession GatewayFilter FactorySecureHeaders GatewayFilter FactorySetPath GatewayFilter FactorySetRequestHeader GatewayFilter FactorySetResponseHeader GatewayFilter FactorySetStatus GatewayFilter FactoryStripPrefix GatewayFilter FactoryGatewayFilter FactoryRequestSize GatewayFilter FactoryGatewayFilter FactoryGatewayFilter FactoryRedirectTo GatewayFilter FactoryRemoveRequestHeader GatewayFilter FactoryRemoveResponseHeader GatewayFilter FactoryRemoveRequestParameter GatewayFilter FactoryRewritePath GatewayFilter FactoryRewriteLocationResponseHeader GatewayFilter FactoryRewriteResponseHeader GatewayFilter FactorySaveSession GatewayFilter FactorySecureHeaders GatewayFilter FactorySetPath GatewayFilter FactorySetRequestHeader GatewayFilter FactorySetResponseHeader GatewayFilter FactorySetStatus GatewayFilter FactoryStripPrefix GatewayFilter FactoryGatewayFilter FactoryRequestSize GatewayFilter FactoryGatewayFilter FactoryGatewayFilter FactoryGatewayFilter OrderingLoadBalancerClient FilterReactiveLoadBalancerClientFilterRouteToRequestUrl FilterGatewayFilter OrderingLoadBalancerClient FilterReactiveLoadBalancerClientFilterRouteToRequestUrl FilterThere are two ways to configure predicates and filters: shortcuts and fully expanded arguments. Most examples below use the shortcut way.
+The name and argument names will be listed as code in the first sentance or two of the each section. The arguments are typically listed in the order that would be needed for the shortcut configuration.
Shortcut configuration is recognized by the filter name, followed by an equals sign (=), followed by argument values separated by commas (,).
spring:
+ cloud:
+ gateway:
+ routes:
+ - id: after_route
+ uri: https://example.org
+ predicates:
+ - Cookie=mycookie,mycookievalueThe previous sample defines the Cookie Route Predicate Factory with two arguments, the cookie name, mycookie and the value to match mycookievalue.
Fully expanded arguments appear more like standard yaml configuration with name/value pairs. Typically, there will be a name key and an args key. The args key is a map of key value pairs to configure the predicate or filter.
spring:
+ cloud:
+ gateway:
+ routes:
+ - id: after_route
+ uri: https://example.org
+ predicates:
+ - name: Cookie
+ args:
+ name: mycookie
+ regexp: mycookievalueThis is the full configuration of the shortcut configuration of the Cookie predicate shown above.
Spring Cloud Gateway matches routes as part of the Spring WebFlux HandlerMapping infrastructure.
@@ -338,9 +407,9 @@ All of these predicates match on different attributes of the HTTP request.
You can combine multiple route predicate factories with logical and statements.
The after route predicate factory takes one parameter, a datetime. +
The After route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime).
This predicate matches requests that happen after the specified datetime.
The following example configures an after route predicate:
The before route predicate factory takes one parameter, a datetime.
+
The Before route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime).
This predicate matches requests that happen before the specified datetime.
The following example configures a before route predicate:
The between route predicate factory takes two parameters, datetime1 and datetime2.
+
The Between route predicate factory takes two parameters, datetime1 and datetime2
+which are java ZonedDateTime objects.
This predicate matches requests that happen after datetime1 and before datetime2.
The datetime2 parameter must be after datetime1.
The following example configures a between route predicate:
The cookie route predicate factory takes two parameters, the cookie name and a regular expression. +
The Cookie route predicate factory takes two parameters, the cookie name and a regexp (which is a Java regular expression).
This predicate matches cookies that have the given name and whose values match the regular expression.
The following example configures a cookie route predicate factory:
The header route predicate factory takes two parameters, the header name and a regular expression. +
The Header route predicate factory takes two parameters, the header name and a regexp (which is a Java regular expression).
This predicate matches with a header that has the given name whose value matches the regular expression.
The following example configures a header route predicate:
The host route predicate factory takes one parameter: a list of host name patterns. +
The Host route predicate factory takes one parameter: a list of host name patterns.
The pattern is an Ant-style pattern with . as the separator.
This predicates matches the Host header that matches the pattern.
The following example configures a host route predicate:
The Method Route Predicate Factory takes one or more parameters: the HTTP methods to match. +
The Method Route Predicate Factory takes a methods argument which is one or more parameters: the HTTP methods to match.
The following example configures a method route predicate:
The Path Route Predicate Factory takes two parameters: a list of Spring PathMatcher patterns and an optional flag called matchOptionalTrailingSeparator.
+
The Path Route Predicate Factory takes two parameters: a list of Spring PathMatcher patterns and an optional flag called matchOptionalTrailingSeparator.
The following example configures a path route predicate:
The query route predicate factory takes two parameters: a required param and an optional regexp.
+
The Query route predicate factory takes two parameters: a required param and an optional regexp (which is a Java regular expression).
The following example configures a query route predicate:
The RemoteAddr route predicate factory takes a list (min size 1) of CIDR-notation (IPv4 or IPv6) strings, such as 192.168.0.1/16 (where 192.168.0.1 is an IP address and 16 is a subnet mask).
+
The RemoteAddr route predicate factory takes a list (min size 1) of sources, which are CIDR-notation (IPv4 or IPv6) strings, such as 192.168.0.1/16 (where 192.168.0.1 is an IP address and 16 is a subnet mask).
The following example configures a RemoteAddr route predicate:
The weight route predicate factory takes two arguments: group and weight. The weights are calculated per group. +
The Weight route predicate factory takes two arguments: group and weight (an int). The weights are calculated per group.
The following example configures a weight route predicate:
This route would forward ~80% of traffic to weighthigh.org and ~20% of traffic to weighlow.org
By default, the RemoteAddr route predicate factory uses the remote address from the incoming request. This may not match the actual client IP address if Spring Cloud Gateway sits behind a proxy layer.
@@ -792,7 +862,7 @@ If two hops of trusted infrastructure are required before Spring Cloud Gateway iGatewayFilter FactoriesGatewayFilter FactoriesRoute filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner. @@ -812,9 +882,9 @@ For more detailed examples of how to use any of the following filters, take a lo
AddRequestHeader GatewayFilter FactoryAddRequestHeader GatewayFilter FactoryThe AddRequestHeader GatewayFilter factory takes a name and value parameter.
+
The AddRequestHeader GatewayFilter factory takes a name and value parameter.
The following example configures an AddRequestHeader GatewayFilter:
AddRequestHeader GatewayF
AddRequestParameter GatewayFilter FactoryAddRequestParameter GatewayFilter FactoryThe AddRequestParameter GatewayFilter Factory takes a name and value parameter.
+
The AddRequestParameter GatewayFilter Factory takes a name and value parameter.
The following example configures an AddRequestParameter GatewayFilter:
AddRequestParameter Gatew
AddResponseHeader GatewayFilter FactoryAddResponseHeader GatewayFilter FactoryThe AddResponseHeader GatewayFilter Factory takes a name and value parameter.
+
The AddResponseHeader GatewayFilter Factory takes a name and value parameter.
The following example configures an AddResponseHeader GatewayFilter:
AddResponseHeader Gateway
DedupeResponseHeader GatewayFilter FactoryDedupeResponseHeader GatewayFilter FactoryThe DedupeResponseHeader GatewayFilter factory takes a name parameter and an optional strategy parameter. name can contain a space-separated list of header names.
The following example configures a DedupeResponseHeader GatewayFilter:
RETAIN_FIRST (default), RETAIN_LAST
The Spring Cloud CircuitBreaker GatewayFilter factory uses the Spring Cloud CircuitBreaker APIs to wrap Gateway routes in a circuit breaker. Spring Cloud CircuitBreaker supports two libraries that can be used with Spring Cloud Gateway, Hystrix @@ -1133,7 +1203,7 @@ You can find more information on doing so in the Fa
FallbackHeaders GatewayFilter FactoryFallbackHeaders GatewayFilter FactoryThe FallbackHeaders factory lets you add Hystrix or Spring Cloud CircuitBreaker execution exception details in the headers of a request forwarded to a fallbackUri in an external application, as in the following scenario:
MapRequestHeader GatewayFilter FactoryMapRequestHeader GatewayFilter FactoryThe MapRequestHeader GatewayFilter factory takes fromHeader and toHeader parameters.
It creates a new named header (toHeader), and the value is extracted out of an existing named header (fromHeader) from the incoming http request.
@@ -1225,7 +1295,7 @@ The following example configures a MapRequestHeader:
PrefixPath GatewayFilter FactoryPrefixPath GatewayFilter FactoryThe PrefixPath GatewayFilter factory takes a single prefix parameter.
The following example configures a PrefixPath GatewayFilter:
/hello would be sent to /mypath/hello.
PreserveHostHeader GatewayFilter FactoryPreserveHostHeader GatewayFilter FactoryThe PreserveHostHeader GatewayFilter factory has no parameters.
This filter sets a request attribute that the routing filter inspects to determine if the original host header should be sent, rather than the host header determined by the HTTP client.
@@ -1278,7 +1348,7 @@ The following example configures a PreserveHostHeader Gateway
RequestRateLimiter GatewayFilter FactoryRequestRateLimiter GatewayFilter FactoryThe RequestRateLimiter GatewayFilter factory uses a RateLimiter implementation to determine if the current request is allowed to proceed. If it is not, a status of HTTP 429 - Too Many Requests (by default) is returned.
RateLimiterRateLimiterThe 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.
KeyResolver
RedirectTo GatewayFilter FactoryRedirectTo GatewayFilter FactoryThe RedirectTo GatewayFilter factory takes two parameters, status and url.
The status parameter should be a 300 series redirect HTTP code, such as 301.
@@ -1463,46 +1533,7 @@ The following listing configures a RedirectTo GatewayFilter
RemoveHopByHopHeadersFilter GatewayFilter FactoryThe RemoveHopByHopHeadersFilter GatewayFilter Factory removes headers from forwarded requests.
-The default list of headers that is removed comes from the IETF.
Connection
Keep-Alive
Proxy-Authenticate
Proxy-Authorization
TE
Trailer
Transfer-Encoding
Upgrade
To change the removed headers, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers property to the list of header names to remove.
RemoveRequestHeader GatewayFilter FactoryRemoveRequestHeader GatewayFilter FactoryThe RemoveRequestHeader GatewayFilter factory takes a name parameter.
It is the name of the header to be removed.
@@ -1530,7 +1561,7 @@ The following listing configures a RemoveRequestHeader Gatewa
RemoveResponseHeader GatewayFilter FactoryRemoveResponseHeader GatewayFilter FactoryThe RemoveResponseHeader GatewayFilter factory takes a name parameter.
It is the name of the header to be removed.
@@ -1562,7 +1593,7 @@ In addition, you can configure this filter once by using spring.cloud.gate
RemoveRequestParameter GatewayFilter FactoryRemoveRequestParameter GatewayFilter FactoryThe RemoveRequestParameter GatewayFilter factory takes a name parameter.
It is the name of the query parameter to be removed.
@@ -1590,7 +1621,7 @@ The following example configures a RemoveRequestParameter Gat
RewritePath GatewayFilter FactoryRewritePath GatewayFilter FactoryThe 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.
@@ -1620,7 +1651,7 @@ The following listing configures a RewritePath GatewayFilter<
RewriteLocationResponseHeader GatewayFilter FactoryRewriteLocationResponseHeader GatewayFilter FactoryThe RewriteLocationResponseHeader GatewayFilter factory modifies the value of the Location response header, usually to get rid of backend-specific details.
It takes stripVersionMode, locationHeaderName, hostValue, and protocolsRegex parameters.
@@ -1673,7 +1704,7 @@ The default is http|https|ftp|ftps.
RewriteResponseHeader GatewayFilter FactoryRewriteResponseHeader GatewayFilter FactoryThe RewriteResponseHeader GatewayFilter factory takes name, regexp, and replacement parameters.
It uses Java regular expressions for a flexible way to rewrite the response header value.
@@ -1702,7 +1733,7 @@ You must use $\ to mean $ because of the YAML specific
SaveSession GatewayFilter FactorySaveSession GatewayFilter FactoryThe 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 you need to ensure the session state has been saved before making the forwarded call.
@@ -1732,7 +1763,7 @@ The following example configures a SaveSession GatewayFilter<
SecureHeaders GatewayFilter FactorySecureHeaders GatewayFilter FactoryThe SecureHeaders GatewayFilter factory adds a number of headers to the response, per the recommendation made in this blog post.
SetPath GatewayFilter FactorySetPath GatewayFilter FactoryThe 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.
@@ -1858,7 +1889,7 @@ The following example configures a SetPath GatewayFilter
SetRequestHeader GatewayFilter FactorySetRequestHeader GatewayFilter FactoryThe SetRequestHeader GatewayFilter factory takes name and value parameters.
The following listing configures a SetRequestHeader GatewayFilter:
SetRequestHeader GatewayF
SetResponseHeader GatewayFilter FactorySetResponseHeader GatewayFilter FactoryThe SetResponseHeader GatewayFilter factory takes name and value parameters.
The following listing configures a SetResponseHeader GatewayFilter:
SetResponseHeader Gateway
SetStatus GatewayFilter FactorySetStatus GatewayFilter FactoryThe SetStatus GatewayFilter factory takes a single parameter, status.
It must be a valid Spring HttpStatus.
@@ -2013,7 +2044,7 @@ The header is added to the response if configured with the following property:
StripPrefix GatewayFilter FactoryStripPrefix GatewayFilter FactoryThe StripPrefix GatewayFilter factory takes one parameter, parts.
The parts parameter indicates the number of parts in the path to strip from the request before sending it downstream.
@@ -2043,9 +2074,9 @@ The following listing configures a StripPrefix GatewayFilter<
GatewayFilter FactoryGatewayFilter FactoryThe Retry GatewayFilter factory supports the following parameters:
The Retry GatewayFilter factory supports the following parameters:
basedOnPreviousValue is true, the backoff is calculated byusing
args:
retries: 3
statuses: BAD_GATEWAY
+ methods: GET,POST
backoff:
firstBackoff: 10ms
maxBackoff: 50ms
@@ -2131,18 +2163,6 @@ If basedOnPreviousValue is true, the backoff is calculated byusing
| - - | -
When using the retry filter with a forward: prefixed URL, the target endpoint should be written carefully so that, in case of an error, it does not do anything that could result in a response being sent to the client and committed.
For example, if the target endpoint is an annotated controller, the target controller method should not return ResponseEntity with an error status code.
Instead, it should throw an Exception or signal an error (for example, through a Mono.error(ex) return value), which the retry filter can be configured to handle by retrying.
@@ -2150,12 +2170,25 @@ Instead, it should throw an Exception or signal an error (for examp
|
| + + | +
+When using the retry filter with any HTTP method with a body, the body will be cached and the gateway will become memory constrained. The body is cached in a request attribute defined by ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR. The type of the object is a org.springframework.core.io.buffer.DataBuffer.
+ |
+
RequestSize GatewayFilter FactoryRequestSize GatewayFilter FactoryWhen the request size is greater than the permissible limit, the RequestSize GatewayFilter factory can restrict a request from reaching the downstream service.
-The filter takes a RequestSize parameter.
+The filter takes a maxSize parameter.
+The maxSize is a `DataSize type, so values can be defined as a number followed by an optional DataUnit suffix such as 'KB' or 'MB'. The default is 'B' for bytes.
It is the permissible size limit of the request defined in bytes.
The following listing configures a RequestSize GatewayFilter:
GatewayFilter Factory| - - | --This filter is considered BETA, and the API may change in the future. - | -
GatewayFilter FactoryYou can use this filter to modify the request body before it is sent downstream by the gateway.
+You can use the ModifyRequestBody filter filter to modify the request body before it is sent downstream by the gateway.
| - - | --This filter is considered BETA and the API may change in the future. - | -
GatewayFilter FactoryYou can use this filter to modify the response body before it is sent back to the client.
+You can use the ModifyResponseBody filter to modify the response body before it is sent back to the client.
GatewayFilter OrderingGatewayFilter OrderingWhen a request matches a route, the filtering web handler adds all instances of GlobalFilter and all route-specific instances of GatewayFilter to a filter chain.
This combined filter chain is sorted by the org.springframework.core.Ordered interface, which you can set by implementing the getOrder() method.
The ForwardRoutingFilter looks for a URI in the exchange attribute ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR.
If the URL has a forward scheme (such as forward:///localendpoint), it uses the Spring DispatcherHandler to handle the request.
@@ -2417,7 +2426,7 @@ The unmodified original URL is appended to the list in the ServerWebExchan
LoadBalancerClient FilterLoadBalancerClient FilterThe LoadBalancerClientFilter looks for a URI in the exchange attribute named ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR.
If the URL has a scheme of lb (such as lb://myservice), it uses the Spring Cloud LoadBalancerClient to resolve the name (myservice in this case) to an actual host and port and replaces the URI in the same attribute.
@@ -2492,7 +2501,7 @@ You can switch to it by setting the value of the spring.cloud.loadbalancer
ReactiveLoadBalancerClientFilterReactiveLoadBalancerClientFilterThe ReactiveLoadBalancerClientFilter looks for a URI in the exchange attribute named ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR.
If the URL has a lb scheme (such as lb://myservice), it uses the Spring Cloud ReactorLoadBalancer to resolve the name (myservice in this example) to an actual host and port and replaces the URI in the same attribute.
@@ -2549,7 +2558,7 @@ However, if GATEWAY_SCHEME_PREFIX_ATTR is specified for the route i
The Netty routing filter runs if the URL located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a http or https scheme.
It uses the Netty HttpClient to make the downstream proxy request.
@@ -2558,7 +2567,7 @@ The response is put in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR
The NettyWriteResponseFilter runs if there is a Netty HttpClientResponse in the ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR exchange attribute.
It runs after all other filters have completed and writes the proxy response back to the gateway client response.
@@ -2566,7 +2575,7 @@ It runs after all other filters have completed and writes the proxy response bac
RouteToRequestUrl FilterRouteToRequestUrl FilterIf there is a Route object in the ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR exchange attribute, the RouteToRequestUrlFilter runs.
It creates a new URI, based off of the request URI but updated with the URI attribute of the Route object.
@@ -2577,7 +2586,7 @@ The new URI is placed in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_AT
If the URL located in the ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR exchange attribute has a ws or wss scheme, the websocket routing rilter runs. It uses the Spring WebSocket infrastructure to forward the websocket request downstream.
To enable gateway metrics, add spring-boot-starter-actuator as a project dependency. Then, by default, the gateway metrics filter runs as long as the property spring.cloud.gateway.metrics.enabled is not set to false. This filter adds a timer metric named gateway.requests with the following tags:
micrometer-registry-prometheus
After the gateway has routed a ServerWebExchange, it marks that exchange as “routed” by adding gatewayAlreadyRouted
to the exchange attributes. Once a request has been marked as routed, other routing filters will not route the request again,
@@ -2688,7 +2697,109 @@ or check if an exchange has already been routed.
HttpHeadersFilters are applied to requests before sending them downstream, such as in the NettyRoutingFilter.
The Forwarded Headers Filter creates a Forwarded header to send to the downstream service. It adds the Host header, scheme and port of the current request to any existing Forwarded header.
The RemoveHopByHop Headers Filter removes headers from forwarded requests. The default list of headers that is removed comes from the IETF.
Connection
+Keep-Alive
+Proxy-Authenticate
+Proxy-Authorization
+TE
+Trailer
+Transfer-Encoding
+Upgrade
+To change this, set the spring.cloud.gateway.filter.remove-non-proxy-headers.headers property to the list of header names to remove.
The XForwarded Headers Filter creates various a X-Forwarded-* headers to send to the downstream service. It users the Host header, scheme, port and path of the current request to create the various headers.
Creating of individual headers can be controlled by the following boolean properties (defaults to true):
+spring.cloud.gateway.x-forwarded.for.enabled
spring.cloud.gateway.x-forwarded.host.enabled
spring.cloud.gateway.x-forwarded.port.enabled
spring.cloud.gateway.x-forwarded.proto.enabled
spring.cloud.gateway.x-forwarded.prefix.enabled
Appending multiple headers can be controlled by the following boolean properties (defaults to true):
+spring.cloud.gateway.x-forwarded.for.append
spring.cloud.gateway.x-forwarded.host.append
spring.cloud.gateway.x-forwarded.port.append
spring.cloud.gateway.x-forwarded.proto.append
spring.cloud.gateway.x-forwarded.prefix.append
The gateway can listen for requests on HTTPS by following the usual Spring server configuration. @@ -2754,7 +2865,7 @@ For a production deployment, you can configure the gateway with a set of known c
If the Spring Cloud Gateway is not provisioned with trusted certificates, the default trust store is used (which you can override by setting the javax.net.ssl.trustStore system property).
The gateway maintains a client pool that it uses to route to backends. When communicating over HTTPS, the client initiates a TLS handshake. @@ -2782,7 +2893,7 @@ You can configure these timeouts can be configured (defaults shown) as follows:<
Configuration for Spring Cloud Gateway is driven by a collection of RouteDefinitionLocator instances.
@@ -2836,7 +2947,7 @@ The following two examples are equivalent:
You can configure additional parameters for each route by using metadata, as follows:
@@ -2880,13 +2991,13 @@ route.getMetadata(someKey);Http timeouts (response and connect) can be configured for all routes and overridden for each specific route.
To configure Global http timeouts:
connect-timeout must be specified in milliseconds.
@@ -2905,7 +3016,7 @@ route.getMetadata(someKey);
To configure per-route timeouts:
connect-timeout must be specified in milliseconds.
@@ -2947,7 +3058,7 @@ import static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPO
To allow for simple configuration in Java, the RouteLocatorBuilder bean includes a fluent API.
The following listing shows how it works:
and(), or()
DiscoveryClient Route Definition LocatorDiscoveryClient Route Definition LocatorYou can configure the gateway to create routes based on services registered with a DiscoveryClient compatible service registry.
and(), or()To enable this, set spring.cloud.gateway.discovery.locator.enabled=true and make sure a DiscoveryClient implementation (such as Netflix Eureka, Consul, or Zookeeper) is on the classpath and enabled.
DiscoveryClient RoutesDiscoveryClient RoutesBy default, the fateway defines a single predicate and filter for routes created with a DiscoveryClient.
To enable Reactor Netty access logs, set -Dreactor.netty.http.server.accessLogEnabled=true.
You can configure the gateway to control CORS behavior. The “global” CORS configuration is a map of URL patterns to Spring Framework CorsConfiguration.
@@ -3121,7 +3232,7 @@ This is useful when you try to support CORS preflight requests and your route pr
The /gateway actuator endpoint lets you monitor and interact with a Spring Cloud Gateway application.
@@ -3140,7 +3251,7 @@ management.endpoints.web.exposure.include=gateway
A new, more verbose format has been added to Spring Cloud Gateway.
It adds more detail to each route, letting you view the predicates and filters associated with each route along with any configuration that is available.
@@ -3185,7 +3296,7 @@ The following example configures /actuator/gateway/routes:
This section details how to retrieve route filters, including:
/actuator/gateway/routes:
To retrieve the global filters applied to all routes, make a GET request to /actuator/gateway/globalfilters. The resulting response is similar to the following:
To retrieve the GatewayFilter factories applied to routes, make a GET request to /actuator/gateway/routefilters.
The resulting response is similar to the following:
null value is due to an incomplete implementation of
To clear the routes cache, make a POST request to /actuator/gateway/refresh.
The request returns a 200 without a response body.
To retrieve the routes defined in the gateway, make a GET request to /actuator/gateway/routes.
The resulting response is similar to the following:
To retrieve information about a single route, make a GET request to /actuator/gateway/routes/{id} (for example, /actuator/gateway/routes/first_route).
The resulting response is similar to the following:
To create a route, make a POST request to /gateway/routes/{id_route_to_create} with a JSON body that specifies the fields of the route (see Retrieving Information about a Particular Route).
The folloiwng table below summarizes the Spring Cloud Gateway actuator endpoints (note that each endpoint has /actuator/gateway as the base-path):
This section covers common problems that may arise when you use Spring Cloud Gateway.
The following loggers may contain valuable troubleshooting information at the DEBUG and TRACE levels:
The Reactor Netty HttpClient and HttpServer can have wiretap enabled.
When combined with setting the reactor.netty log level to DEBUG or TRACE, it enables the logging of information, such as headers and bodies sent and received across the wire.
@@ -3515,19 +3626,47 @@ To enable wiretap, set spring.cloud.gateway.httpserver.wiretap=true
TODO: overview of writing custom integrations
+These are basic guides to writing some custom components of the gateway.
TODO: document writing Custom Route Predicate Factories
+In order to write a Route Predicate you will need to implement RoutePredicateFactory. There is an abstract class called AbstractRoutePredicateFactory which you can extend.
public class MyRoutePredicateFactory extends AbstractRoutePredicateFactory<HeaderRoutePredicateFactory.Config> {
+
+ public MyRoutePredicateFactory() {
+ super(Config.class);
+ }
+
+ @Override
+ public Predicate<ServerWebExchange> apply(Config config) {
+ // grab configuration from Config object
+ return exchange -> {
+ //grab the request
+ ServerHttpRequest request = exchange.getRequest();
+ //take information from the request to see if it
+ //matches configuration.
+ return matches(config, request);
+ };
+ }
+
+ public static class Config {
+ //Put the configuration properties for your filter here
+ }
+
+}To write a GatewayFilter, you must implement GatewayFilterFactory.
You can extend an abstract class called AbstractGatewayFilterFactory.
@@ -3594,7 +3733,7 @@ The following examples show how to do so:
To write a custom global filter, you must implement GlobalFilter interface.
This applies the filter to all requests.
TODO: document writing Custom Route Locators and Writers
-| + + | ++The following describes an alternative style gateway. None of the prior documentation applies to what follows. + | +
Spring Cloud Gateway provides a utility object called ProxyExchange.
You can use it inside a regular Spring web handler as a method parameter.
@@ -3737,7 +3882,7 @@ The mapper is a Function that takes the incoming ResponseEnti
To see the list of all Spring Cloud Gateway related configuration properties, see the appendix.