From f22708c8421fbb7ca814338e2d25c0e4b2cefe42 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Fri, 31 Jan 2020 17:12:15 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- reference/html/index.html | 695 ++++++++++++++--------- reference/html/spring-cloud-gateway.html | 695 ++++++++++++++--------- 2 files changed, 840 insertions(+), 550 deletions(-) diff --git a/reference/html/index.html b/reference/html/index.html index 8f14183e..a9484eb1 100644 --- a/reference/html/index.html +++ b/reference/html/index.html @@ -99,130 +99,141 @@ $(addBlockSwitches);
  • 1. How to Include Spring Cloud Gateway
  • 2. Glossary
  • 3. How It Works
    • -
  • 4. Route Predicate Factories +
  • 4. Configuring Route Predicate Factories and Gateway Filter Factories +
    • +
  • 5. Route Predicate Factories +
    • -
  • 5. GatewayFilter Factories +
  • 6. GatewayFilter Factories
    • -
  • 6. Global Filters +
  • 7. Global Filters
    • -
  • 7. TLS and SSL +
  • 8. HttpHeadersFilters
    • -
  • 8. Configuration
    • -
  • 9. Route Metadata Configuration
    • -
  • 10. Http timeouts configuration +
  • 9. TLS and SSL +
    • +
  • 10. Configuration
    • +
  • 11. Route Metadata Configuration
    • +
  • 12. Http timeouts configuration +
    • -
  • 11. Reactor Netty Access Logs
    • -
  • 12. CORS Configuration
    • -
  • 13. Actuator API +
  • 13. Reactor Netty Access Logs
    • +
  • 14. CORS Configuration
    • +
  • 15. Actuator API
    • -
  • 14. Troubleshooting +
  • 16. Troubleshooting
    • -
  • 15. Developer Guide +
  • 17. Developer Guide
    • -
  • 16. Building a Simple Gateway by Using Spring MVC or Webflux
    • -
  • 17. Configuration properties
    • +
  • 18. Building a Simple Gateway by Using Spring MVC or Webflux
    • +
  • 19. Configuration properties
    • @@ -329,7 +340,65 @@ URIs defined in routes without a port get default port values of 80 and 443 for
    -

    4. Route Predicate Factories

    +

    4. Configuring Route Predicate Factories and Gateway Filter Factories

    +
    +
    +

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

    +
    +
    +

    4.1. Shortcut Configuration

    +
    +

    Shortcut configuration is recognized by the filter name, followed by an equals sign (=), followed by argument values separated by commas (,).

    +
    +
    +
    application.yml
    +
    +
    spring:
+  cloud:
+    gateway:
+      routes:
+      - id: after_route
+        uri: https://example.org
+        predicates:
+        - Cookie=mycookie,mycookievalue
    +
    +
    +
    +

    The previous sample defines the Cookie Route Predicate Factory with two arguments, the cookie name, mycookie and the value to match mycookievalue.

    +
    +
    +
    +

    4.2. Fully Expanded Arguments

    +
    +

    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.

    +
    +
    +
    application.yml
    +
    +
    spring:
+  cloud:
+    gateway:
+      routes:
+      - id: after_route
+        uri: https://example.org
+        predicates:
+        - name: Cookie
+          args:
+            name: mycookie
+            regexp: mycookievalue
    +
    +
    +
    +

    This is the full configuration of the shortcut configuration of the Cookie predicate shown above.

    +
    +
    +
    +
    +
    +

    5. Route Predicate Factories

    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.

    -

    4.1. The After Route Predicate Factory

    +

    5.1. The After Route Predicate Factory

    -

    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:

    @@ -366,9 +435,9 @@ The following example configures an after route predicate:

    -

    4.2. The Before Route Predicate Factory

    +

    5.2. The Before Route Predicate Factory

    -

    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:

    @@ -394,9 +463,10 @@ The following example configures a before route predicate:

    -

    4.3. The Between Route Predicate Factory

    +

    5.3. The Between Route Predicate Factory

    -

    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:

    @@ -424,9 +494,9 @@ This could be useful for maintenance windows.

    - +
    -

    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:

    @@ -452,9 +522,9 @@ The following example configures a cookie route predicate factory:

    -

    4.5. The Header Route Predicate Factory

    +

    5.5. The Header 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:

    @@ -480,9 +550,9 @@ The following example configures a header route predicate:

    -

    4.6. The Host Route Predicate Factory

    +

    5.6. The Host Route Predicate Factory

    -

    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:

    @@ -516,9 +586,9 @@ Those values are then available for use by
    -

    4.7. The Method Route Predicate Factory

    +

    5.7. The Method Route Predicate Factory

    -

    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:

    @@ -543,9 +613,9 @@ The following example configures a method route predicate:

    -

    4.8. The Path Route Predicate Factory

    +

    5.8. The Path Route Predicate Factory

    -

    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:

    @@ -589,9 +659,9 @@ String segment = uriVariables.get("segment");
    -

    4.9. The Query Route Predicate Factory

    +

    5.9. The Query Route Predicate Factory

    -

    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:

    @@ -632,9 +702,9 @@ The following example configures a query route predicate:

    -

    4.10. The RemoteAddr Route Predicate Factory

    +

    5.10. The RemoteAddr Route Predicate Factory

    -

    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:

    @@ -659,9 +729,9 @@ The following example configures a RemoteAddr route predicate:

    -

    4.11. The Weight Route Predicate Factory

    +

    5.11. The Weight Route Predicate Factory

    -

    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:

    @@ -689,7 +759,7 @@ 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

    -

    4.11.1. Modifying the Way Remote Addresses Are Resolved

    +

    5.11.1. Modifying the Way Remote Addresses Are Resolved

    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 i
    -

    5. GatewayFilter Factories

    +

    6. GatewayFilter Factories

    Route 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

    -

    5.1. The AddRequestHeader GatewayFilter Factory

    +

    6.1. The AddRequestHeader GatewayFilter Factory

    -

    The 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:

    @@ -863,9 +933,9 @@ The following example configures an AddRequestHeader GatewayF
    -

    5.2. The AddRequestParameter GatewayFilter Factory

    +

    6.2. The AddRequestParameter GatewayFilter Factory

    -

    The 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:

    @@ -914,9 +984,9 @@ The following example configures an AddRequestParameter Gatew
    -

    5.3. The AddResponseHeader GatewayFilter Factory

    +

    6.3. The AddResponseHeader GatewayFilter Factory

    -

    The 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:

    @@ -965,7 +1035,7 @@ The following example configures an AddResponseHeader Gateway
    -

    5.4. The DedupeResponseHeader GatewayFilter Factory

    +

    6.4. The DedupeResponseHeader GatewayFilter Factory

    The 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:

    @@ -996,7 +1066,7 @@ The accepted values are RETAIN_FIRST (default), RETAIN_LAST
    -

    5.5. Spring Cloud CircuitBreaker GatewayFilter Factory

    +

    6.5. Spring Cloud CircuitBreaker GatewayFilter Factory

    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

    -

    5.6. The FallbackHeaders GatewayFilter Factory

    +

    6.6. The FallbackHeaders GatewayFilter Factory

    The 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:

    @@ -1195,7 +1265,7 @@ The headers with the exception type, message and (if available) root cause excep
    -

    5.7. The MapRequestHeader GatewayFilter Factory

    +

    6.7. The MapRequestHeader GatewayFilter Factory

    The 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:

    -

    5.8. The PrefixPath GatewayFilter Factory

    +

    6.8. The PrefixPath GatewayFilter Factory

    The PrefixPath GatewayFilter factory takes a single prefix parameter. The following example configures a PrefixPath GatewayFilter:

    @@ -1253,7 +1323,7 @@ So a request to /hello would be sent to /mypath/hello.
    -

    5.9. The PreserveHostHeader GatewayFilter Factory

    +

    6.9. The PreserveHostHeader GatewayFilter Factory

    The 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

    -

    5.10. The RequestRateLimiter GatewayFilter Factory

    +

    6.10. The RequestRateLimiter GatewayFilter Factory

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

    @@ -1340,7 +1410,7 @@ spring.cloud.gateway.routes[0].filters[0]=RequestRateLimiter=2, 2, #{@userkeyres
    -

    5.10.1. The Redis RateLimiter

    +

    6.10.1. The Redis RateLimiter

    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.

    @@ -1432,7 +1502,7 @@ The following listing defines a rate limiter that uses the KeyResolver
    -

    5.11. The RedirectTo GatewayFilter Factory

    +

    6.11. The RedirectTo GatewayFilter Factory

    The 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

    -

    5.12. The RemoveHopByHopHeadersFilter GatewayFilter Factory

    -
    -

    The RemoveHopByHopHeadersFilter GatewayFilter Factory removes headers from forwarded requests. -The default list of headers that is removed comes from the IETF.

    -
    -
    -
    The default removed headers are:
    -
      -
    • -

      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.

    -
    -
    -
    -

    5.13. The RemoveRequestHeader GatewayFilter Factory

    +

    6.12. The RemoveRequestHeader GatewayFilter Factory

    The 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

    -

    5.14. RemoveResponseHeader GatewayFilter Factory

    +

    6.13. RemoveResponseHeader GatewayFilter Factory

    The 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

    -

    5.15. The RemoveRequestParameter GatewayFilter Factory

    +

    6.14. The RemoveRequestParameter GatewayFilter Factory

    The 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

    -

    5.16. The RewritePath GatewayFilter Factory

    +

    6.15. The RewritePath GatewayFilter Factory

    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. @@ -1620,7 +1651,7 @@ The following listing configures a RewritePath GatewayFilter<

    -

    5.17. RewriteLocationResponseHeader GatewayFilter Factory

    +

    6.16. RewriteLocationResponseHeader GatewayFilter Factory

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

    -

    5.18. The RewriteResponseHeader GatewayFilter Factory

    +

    6.17. The RewriteResponseHeader GatewayFilter Factory

    The 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

    -

    5.19. The SaveSession GatewayFilter Factory

    +

    6.18. The SaveSession GatewayFilter Factory

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

    -

    5.20. The SecureHeaders GatewayFilter Factory

    +

    6.19. The SecureHeaders GatewayFilter Factory

    The SecureHeaders GatewayFilter factory adds a number of headers to the response, per the recommendation made in this blog post.

    @@ -1826,7 +1857,7 @@ The lowercase full name of the secure header needs to be used to disable it..
    -

    5.21. The SetPath GatewayFilter Factory

    +

    6.20. The SetPath GatewayFilter Factory

    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. @@ -1858,7 +1889,7 @@ The following example configures a SetPath GatewayFilter

    -

    5.22. The SetRequestHeader GatewayFilter Factory

    +

    6.21. The SetRequestHeader GatewayFilter Factory

    The SetRequestHeader GatewayFilter factory takes name and value parameters. The following listing configures a SetRequestHeader GatewayFilter:

    @@ -1910,7 +1941,7 @@ The following example configures an SetRequestHeader GatewayF
    -

    5.23. The SetResponseHeader GatewayFilter Factory

    +

    6.22. The SetResponseHeader GatewayFilter Factory

    The SetResponseHeader GatewayFilter factory takes name and value parameters. The following listing configures a SetResponseHeader GatewayFilter:

    @@ -1962,7 +1993,7 @@ The following example configures an SetResponseHeader Gateway
    -

    5.24. The SetStatus GatewayFilter Factory

    +

    6.23. The SetStatus GatewayFilter Factory

    The 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:

    -

    5.25. The StripPrefix GatewayFilter Factory

    +

    6.24. The StripPrefix GatewayFilter Factory

    The 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<

    -

    5.26. The Retry GatewayFilter Factory

    +

    6.25. The Retry GatewayFilter Factory

    -

    The Retry GatewayFilter factory supports the following parameters:

    +

    The Retry GatewayFilter factory supports the following parameters:

      @@ -2115,6 +2146,7 @@ If 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 -The retry filter does not currently support retrying with a body (for example, for POST or PUT requests with a body). - - - -
    -
    - - - -
    - - 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. +
    +
    -

    5.27. The RequestSize GatewayFilter Factory

    +

    6.26. The RequestSize GatewayFilter Factory

    When 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:

    @@ -2206,21 +2239,9 @@ The default request size is set to five MB if not provided as a filter argument
    -

    5.28. Modify a Request Body GatewayFilter Factory

    -
    - - - - - -
    - - -This filter is considered BETA, and the API may change in the future. -
    -
    +

    6.27. Modify a Request Body GatewayFilter Factory

    -

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

    @@ -2274,21 +2295,9 @@ static class Hello {
    -

    5.29. Modify a Response Body GatewayFilter Factory

    -
    -
    - - - - -
    - - -This filter is considered BETA and the API may change in the future. -
    -
    +

    6.28. Modify a Response Body GatewayFilter Factory

    -

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

    @@ -2324,7 +2333,7 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
    -

    5.30. Default Filters

    +

    6.29. Default Filters

    To add a filter and apply it to all routes, you can use spring.cloud.gateway.default-filters. This property takes a list of filters. @@ -2349,7 +2358,7 @@ The following listing defines a set of default filters:

    -

    6. Global Filters

    +

    7. Global Filters

    The GlobalFilter interface has the same signature as GatewayFilter. @@ -2368,7 +2377,7 @@ This interface and its usage are subject to change in future milestone releases.

    -

    6.1. Combined Global Filter and GatewayFilter Ordering

    +

    7.1. Combined Global Filter and GatewayFilter Ordering

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

    @@ -2408,7 +2417,7 @@ public class CustomGlobalFilter implements GlobalFilter, Ordered {
    -

    6.2. Forward Routing Filter

    +

    7.2. Forward Routing Filter

    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

    -

    6.3. The LoadBalancerClient Filter

    +

    7.3. The LoadBalancerClient Filter

    The 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

    -

    6.4. The ReactiveLoadBalancerClientFilter

    +

    7.4. The ReactiveLoadBalancerClientFilter

    The 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

    -

    6.5. The Netty Routing Filter

    +

    7.5. The Netty Routing Filter

    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

    -

    6.6. The Netty Write Response Filter

    +

    7.6. The Netty Write Response Filter

    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

    -

    6.7. The RouteToRequestUrl Filter

    +

    7.7. The RouteToRequestUrl Filter

    If 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

    -

    6.8. The Websocket Routing Filter

    +

    7.8. The Websocket Routing Filter

    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.

    @@ -2624,7 +2633,7 @@ If you use SockJS as a fallback over nor
    -

    6.9. The Gateway Metrics Filter

    +

    7.9. The Gateway Metrics Filter

    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:

    @@ -2667,7 +2676,7 @@ To enable the prometheus endpoint, add micrometer-registry-prometheus
    -

    6.10. Marking An Exchange As Routed

    +

    7.10. Marking An Exchange As Routed

    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.

    -

    7. TLS and SSL

    +

    8. HttpHeadersFilters

    +
    +
    +

    HttpHeadersFilters are applied to requests before sending them downstream, such as in the NettyRoutingFilter.

    +
    +
    +

    8.1. Forwarded Headers Filter

    +
    +

    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.

    +
    +
    +
    +

    8.2. RemoveHopByHop Headers Filter

    +
    +

    The RemoveHopByHop Headers Filter removes headers from forwarded requests. The default list of headers that is removed comes from the IETF.

    +
    +
    +
    The default removed headers are:
    +
      +
    • +

      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.

    +
    +
    +
    +

    8.3. XForwarded Headers Filter

    +
    +

    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

      +
      • +
    +
    +
    +
    +
    +
    +

    9. TLS and SSL

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

    -

    7.1. TLS Handshake

    +

    9.1. TLS Handshake

    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:<

    -

    8. Configuration

    +

    10. Configuration

    Configuration for Spring Cloud Gateway is driven by a collection of RouteDefinitionLocator instances. @@ -2836,7 +2947,7 @@ The following two examples are equivalent:

    -

    9. Route Metadata Configuration

    +

    11. Route Metadata Configuration

    You can configure additional parameters for each route by using metadata, as follows:

    @@ -2880,13 +2991,13 @@ route.getMetadata(someKey);
    -

    10. Http timeouts configuration

    +

    12. Http timeouts configuration

    Http timeouts (response and connect) can be configured for all routes and overridden for each specific route.

    -

    10.1. Global timeouts

    +

    12.1. Global timeouts

    To configure Global http timeouts:
    connect-timeout must be specified in milliseconds.
    @@ -2905,7 +3016,7 @@ route.getMetadata(someKey);

    -

    10.2. Per-route timeouts

    +

    12.2. Per-route timeouts

    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

    -

    10.3. Fluent Java Routes API

    +

    12.3. Fluent Java Routes API

    To allow for simple configuration in Java, the RouteLocatorBuilder bean includes a fluent API. The following listing shows how it works:

    @@ -2994,7 +3105,7 @@ By using the fluent Java API, you can use the and(), or()
    -

    10.4. The DiscoveryClient Route Definition Locator

    +

    12.4. The DiscoveryClient Route Definition Locator

    You can configure the gateway to create routes based on services registered with a DiscoveryClient compatible service registry.

    @@ -3002,7 +3113,7 @@ By using the fluent Java API, you can use the 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.

    -

    10.4.1. Configuring Predicates and Filters For DiscoveryClient Routes

    +

    12.4.1. Configuring Predicates and Filters For DiscoveryClient Routes

    By default, the fateway defines a single predicate and filter for routes created with a DiscoveryClient.

    @@ -3042,7 +3153,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    11. Reactor Netty Access Logs

    +

    13. Reactor Netty Access Logs

    To enable Reactor Netty access logs, set -Dreactor.netty.http.server.accessLogEnabled=true.

    @@ -3087,7 +3198,7 @@ It must be a Java System Property, not a Spring Boot property.
    -

    12. CORS Configuration

    +

    14. CORS Configuration

    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

    -

    13. Actuator API

    +

    15. Actuator API

    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

    -

    13.1. Verbose Actuator Format

    +

    15.1. Verbose Actuator Format

    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:

    -

    13.2. Retrieving Route Filters

    +

    15.2. Retrieving Route Filters

    This section details how to retrieve route filters, including:

    @@ -3200,7 +3311,7 @@ The following example configures /actuator/gateway/routes:

    -

    13.2.1. Global Filters

    +

    15.2.1. Global Filters

    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:

    @@ -3228,7 +3339,7 @@ For each global filter, there is a string representation of the filter object (f
    -

    13.2.2. Route Filters

    +

    15.2.2. Route Filters

    To retrieve the GatewayFilter factories applied to routes, make a GET request to /actuator/gateway/routefilters. The resulting response is similar to the following:

    @@ -3254,14 +3365,14 @@ Note that the null value is due to an incomplete implementation of
    -

    13.3. Refreshing the Route Cache

    +

    15.3. Refreshing the Route Cache

    To clear the routes cache, make a POST request to /actuator/gateway/refresh. The request returns a 200 without a response body.

    -

    13.4. Retrieving the Routes Defined in the Gateway

    +

    15.4. Retrieving the Routes Defined in the Gateway

    To retrieve the routes defined in the gateway, make a GET request to /actuator/gateway/routes. The resulting response is similar to the following:

    @@ -3334,7 +3445,7 @@ The following table describes the structure of each element (each is a route) of
    -

    13.5. Retrieving Information about a Particular Route

    +

    15.5. Retrieving Information about a Particular Route

    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:

    @@ -3403,7 +3514,7 @@ The resulting response is similar to the following:

    -

    13.6. Creating and Deleting a Particular Route

    +

    15.6. Creating and Deleting a Particular Route

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

    @@ -3412,7 +3523,7 @@ The resulting response is similar to the following:

    -

    13.7. Recap: The List of All endpoints

    +

    15.7. Recap: The List of All endpoints

    The folloiwng table below summarizes the Spring Cloud Gateway actuator endpoints (note that each endpoint has /actuator/gateway as the base-path):

    @@ -3471,13 +3582,13 @@ The resulting response is similar to the following:

    -

    14. Troubleshooting

    +

    16. Troubleshooting

    This section covers common problems that may arise when you use Spring Cloud Gateway.

    -

    14.1. Log Levels

    +

    16.1. Log Levels

    The following loggers may contain valuable troubleshooting information at the DEBUG and TRACE levels:

    @@ -3505,7 +3616,7 @@ The resulting response is similar to the following:

    -

    14.2. Wiretap

    +

    16.2. Wiretap

    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

    -

    15. Developer Guide

    +

    17. Developer Guide

    -

    TODO: overview of writing custom integrations

    +

    These are basic guides to writing some custom components of the gateway.

    -

    15.1. Writing Custom Route Predicate Factories

    +

    17.1. Writing Custom Route Predicate Factories

    -

    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.

    +
    +
    +
    MyRoutePredicateFactory.java
    +
    +
    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
+    }
+
+}
    +
    -

    15.2. Writing Custom GatewayFilter Factories

    +

    17.2. Writing Custom GatewayFilter Factories

    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:

    -

    15.3. Writing Custom Global Filters

    +

    17.3. Writing Custom Global Filters

    To write a custom global filter, you must implement GlobalFilter interface. This applies the filter to all requests.

    @@ -3636,17 +3775,23 @@ public GlobalFilter customGlobalPostFilter() {
    -
    -

    15.4. Writing Custom Route Locators and Writers

    -
    -

    TODO: document writing Custom Route Locators and Writers

    -
    -
    -

    16. Building a Simple Gateway by Using Spring MVC or Webflux

    +

    18. Building a Simple Gateway by Using Spring MVC or Webflux

    +
    + + + + + +
    + + +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

    -

    17. Configuration properties

    +

    19. Configuration properties

    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);
  • 1. How to Include Spring Cloud Gateway
  • 2. Glossary
  • 3. How It Works
    • -
  • 4. Route Predicate Factories +
  • 4. Configuring Route Predicate Factories and Gateway Filter Factories +
    • +
  • 5. Route Predicate Factories +
    • -
  • 5. GatewayFilter Factories +
  • 6. GatewayFilter Factories
    • -
  • 6. Global Filters +
  • 7. Global Filters
    • -
  • 7. TLS and SSL +
  • 8. HttpHeadersFilters
    • -
  • 8. Configuration
    • -
  • 9. Route Metadata Configuration
    • -
  • 10. Http timeouts configuration +
  • 9. TLS and SSL +
    • +
  • 10. Configuration
    • +
  • 11. Route Metadata Configuration
    • +
  • 12. Http timeouts configuration +
    • -
  • 11. Reactor Netty Access Logs
    • -
  • 12. CORS Configuration
    • -
  • 13. Actuator API +
  • 13. Reactor Netty Access Logs
    • +
  • 14. CORS Configuration
    • +
  • 15. Actuator API
    • -
  • 14. Troubleshooting +
  • 16. Troubleshooting
    • -
  • 15. Developer Guide +
  • 17. Developer Guide
    • -
  • 16. Building a Simple Gateway by Using Spring MVC or Webflux
    • -
  • 17. Configuration properties
    • +
  • 18. Building a Simple Gateway by Using Spring MVC or Webflux
    • +
  • 19. Configuration properties
    • @@ -329,7 +340,65 @@ URIs defined in routes without a port get default port values of 80 and 443 for
    -

    4. Route Predicate Factories

    +

    4. Configuring Route Predicate Factories and Gateway Filter Factories

    +
    +
    +

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

    +
    +
    +

    4.1. Shortcut Configuration

    +
    +

    Shortcut configuration is recognized by the filter name, followed by an equals sign (=), followed by argument values separated by commas (,).

    +
    +
    +
    application.yml
    +
    +
    spring:
+  cloud:
+    gateway:
+      routes:
+      - id: after_route
+        uri: https://example.org
+        predicates:
+        - Cookie=mycookie,mycookievalue
    +
    +
    +
    +

    The previous sample defines the Cookie Route Predicate Factory with two arguments, the cookie name, mycookie and the value to match mycookievalue.

    +
    +
    +
    +

    4.2. Fully Expanded Arguments

    +
    +

    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.

    +
    +
    +
    application.yml
    +
    +
    spring:
+  cloud:
+    gateway:
+      routes:
+      - id: after_route
+        uri: https://example.org
+        predicates:
+        - name: Cookie
+          args:
+            name: mycookie
+            regexp: mycookievalue
    +
    +
    +
    +

    This is the full configuration of the shortcut configuration of the Cookie predicate shown above.

    +
    +
    +
    +
    +
    +

    5. Route Predicate Factories

    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.

    -

    4.1. The After Route Predicate Factory

    +

    5.1. The After Route Predicate Factory

    -

    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:

    @@ -366,9 +435,9 @@ The following example configures an after route predicate:

    -

    4.2. The Before Route Predicate Factory

    +

    5.2. The Before Route Predicate Factory

    -

    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:

    @@ -394,9 +463,10 @@ The following example configures a before route predicate:

    -

    4.3. The Between Route Predicate Factory

    +

    5.3. The Between Route Predicate Factory

    -

    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:

    @@ -424,9 +494,9 @@ This could be useful for maintenance windows.

    - +
    -

    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:

    @@ -452,9 +522,9 @@ The following example configures a cookie route predicate factory:

    -

    4.5. The Header Route Predicate Factory

    +

    5.5. The Header 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:

    @@ -480,9 +550,9 @@ The following example configures a header route predicate:

    -

    4.6. The Host Route Predicate Factory

    +

    5.6. The Host Route Predicate Factory

    -

    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:

    @@ -516,9 +586,9 @@ Those values are then available for use by
    -

    4.7. The Method Route Predicate Factory

    +

    5.7. The Method Route Predicate Factory

    -

    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:

    @@ -543,9 +613,9 @@ The following example configures a method route predicate:

    -

    4.8. The Path Route Predicate Factory

    +

    5.8. The Path Route Predicate Factory

    -

    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:

    @@ -589,9 +659,9 @@ String segment = uriVariables.get("segment");
    -

    4.9. The Query Route Predicate Factory

    +

    5.9. The Query Route Predicate Factory

    -

    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:

    @@ -632,9 +702,9 @@ The following example configures a query route predicate:

    -

    4.10. The RemoteAddr Route Predicate Factory

    +

    5.10. The RemoteAddr Route Predicate Factory

    -

    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:

    @@ -659,9 +729,9 @@ The following example configures a RemoteAddr route predicate:

    -

    4.11. The Weight Route Predicate Factory

    +

    5.11. The Weight Route Predicate Factory

    -

    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:

    @@ -689,7 +759,7 @@ 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

    -

    4.11.1. Modifying the Way Remote Addresses Are Resolved

    +

    5.11.1. Modifying the Way Remote Addresses Are Resolved

    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 i
    -

    5. GatewayFilter Factories

    +

    6. GatewayFilter Factories

    Route 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

    -

    5.1. The AddRequestHeader GatewayFilter Factory

    +

    6.1. The AddRequestHeader GatewayFilter Factory

    -

    The 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:

    @@ -863,9 +933,9 @@ The following example configures an AddRequestHeader GatewayF
    -

    5.2. The AddRequestParameter GatewayFilter Factory

    +

    6.2. The AddRequestParameter GatewayFilter Factory

    -

    The 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:

    @@ -914,9 +984,9 @@ The following example configures an AddRequestParameter Gatew
    -

    5.3. The AddResponseHeader GatewayFilter Factory

    +

    6.3. The AddResponseHeader GatewayFilter Factory

    -

    The 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:

    @@ -965,7 +1035,7 @@ The following example configures an AddResponseHeader Gateway
    -

    5.4. The DedupeResponseHeader GatewayFilter Factory

    +

    6.4. The DedupeResponseHeader GatewayFilter Factory

    The 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:

    @@ -996,7 +1066,7 @@ The accepted values are RETAIN_FIRST (default), RETAIN_LAST
    -

    5.5. Spring Cloud CircuitBreaker GatewayFilter Factory

    +

    6.5. Spring Cloud CircuitBreaker GatewayFilter Factory

    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

    -

    5.6. The FallbackHeaders GatewayFilter Factory

    +

    6.6. The FallbackHeaders GatewayFilter Factory

    The 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:

    @@ -1195,7 +1265,7 @@ The headers with the exception type, message and (if available) root cause excep
    -

    5.7. The MapRequestHeader GatewayFilter Factory

    +

    6.7. The MapRequestHeader GatewayFilter Factory

    The 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:

    -

    5.8. The PrefixPath GatewayFilter Factory

    +

    6.8. The PrefixPath GatewayFilter Factory

    The PrefixPath GatewayFilter factory takes a single prefix parameter. The following example configures a PrefixPath GatewayFilter:

    @@ -1253,7 +1323,7 @@ So a request to /hello would be sent to /mypath/hello.
    -

    5.9. The PreserveHostHeader GatewayFilter Factory

    +

    6.9. The PreserveHostHeader GatewayFilter Factory

    The 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

    -

    5.10. The RequestRateLimiter GatewayFilter Factory

    +

    6.10. The RequestRateLimiter GatewayFilter Factory

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

    @@ -1340,7 +1410,7 @@ spring.cloud.gateway.routes[0].filters[0]=RequestRateLimiter=2, 2, #{@userkeyres
    -

    5.10.1. The Redis RateLimiter

    +

    6.10.1. The Redis RateLimiter

    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.

    @@ -1432,7 +1502,7 @@ The following listing defines a rate limiter that uses the KeyResolver
    -

    5.11. The RedirectTo GatewayFilter Factory

    +

    6.11. The RedirectTo GatewayFilter Factory

    The 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

    -

    5.12. The RemoveHopByHopHeadersFilter GatewayFilter Factory

    -
    -

    The RemoveHopByHopHeadersFilter GatewayFilter Factory removes headers from forwarded requests. -The default list of headers that is removed comes from the IETF.

    -
    -
    -
    The default removed headers are:
    -
      -
    • -

      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.

    -
    -
    -
    -

    5.13. The RemoveRequestHeader GatewayFilter Factory

    +

    6.12. The RemoveRequestHeader GatewayFilter Factory

    The 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

    -

    5.14. RemoveResponseHeader GatewayFilter Factory

    +

    6.13. RemoveResponseHeader GatewayFilter Factory

    The 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

    -

    5.15. The RemoveRequestParameter GatewayFilter Factory

    +

    6.14. The RemoveRequestParameter GatewayFilter Factory

    The 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

    -

    5.16. The RewritePath GatewayFilter Factory

    +

    6.15. The RewritePath GatewayFilter Factory

    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. @@ -1620,7 +1651,7 @@ The following listing configures a RewritePath GatewayFilter<

    -

    5.17. RewriteLocationResponseHeader GatewayFilter Factory

    +

    6.16. RewriteLocationResponseHeader GatewayFilter Factory

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

    -

    5.18. The RewriteResponseHeader GatewayFilter Factory

    +

    6.17. The RewriteResponseHeader GatewayFilter Factory

    The 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

    -

    5.19. The SaveSession GatewayFilter Factory

    +

    6.18. The SaveSession GatewayFilter Factory

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

    -

    5.20. The SecureHeaders GatewayFilter Factory

    +

    6.19. The SecureHeaders GatewayFilter Factory

    The SecureHeaders GatewayFilter factory adds a number of headers to the response, per the recommendation made in this blog post.

    @@ -1826,7 +1857,7 @@ The lowercase full name of the secure header needs to be used to disable it..
    -

    5.21. The SetPath GatewayFilter Factory

    +

    6.20. The SetPath GatewayFilter Factory

    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. @@ -1858,7 +1889,7 @@ The following example configures a SetPath GatewayFilter

    -

    5.22. The SetRequestHeader GatewayFilter Factory

    +

    6.21. The SetRequestHeader GatewayFilter Factory

    The SetRequestHeader GatewayFilter factory takes name and value parameters. The following listing configures a SetRequestHeader GatewayFilter:

    @@ -1910,7 +1941,7 @@ The following example configures an SetRequestHeader GatewayF
    -

    5.23. The SetResponseHeader GatewayFilter Factory

    +

    6.22. The SetResponseHeader GatewayFilter Factory

    The SetResponseHeader GatewayFilter factory takes name and value parameters. The following listing configures a SetResponseHeader GatewayFilter:

    @@ -1962,7 +1993,7 @@ The following example configures an SetResponseHeader Gateway
    -

    5.24. The SetStatus GatewayFilter Factory

    +

    6.23. The SetStatus GatewayFilter Factory

    The 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:

    -

    5.25. The StripPrefix GatewayFilter Factory

    +

    6.24. The StripPrefix GatewayFilter Factory

    The 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<

    -

    5.26. The Retry GatewayFilter Factory

    +

    6.25. The Retry GatewayFilter Factory

    -

    The Retry GatewayFilter factory supports the following parameters:

    +

    The Retry GatewayFilter factory supports the following parameters:

      @@ -2115,6 +2146,7 @@ If 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 -The retry filter does not currently support retrying with a body (for example, for POST or PUT requests with a body). - - - -
    -
    - - - -
    - - 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. +
    +
    -

    5.27. The RequestSize GatewayFilter Factory

    +

    6.26. The RequestSize GatewayFilter Factory

    When 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:

    @@ -2206,21 +2239,9 @@ The default request size is set to five MB if not provided as a filter argument
    -

    5.28. Modify a Request Body GatewayFilter Factory

    -
    - - - - - -
    - - -This filter is considered BETA, and the API may change in the future. -
    -
    +

    6.27. Modify a Request Body GatewayFilter Factory

    -

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

    @@ -2274,21 +2295,9 @@ static class Hello {
    -

    5.29. Modify a Response Body GatewayFilter Factory

    -
    -
    - - - - -
    - - -This filter is considered BETA and the API may change in the future. -
    -
    +

    6.28. Modify a Response Body GatewayFilter Factory

    -

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

    @@ -2324,7 +2333,7 @@ public RouteLocator routes(RouteLocatorBuilder builder) {
    -

    5.30. Default Filters

    +

    6.29. Default Filters

    To add a filter and apply it to all routes, you can use spring.cloud.gateway.default-filters. This property takes a list of filters. @@ -2349,7 +2358,7 @@ The following listing defines a set of default filters:

    -

    6. Global Filters

    +

    7. Global Filters

    The GlobalFilter interface has the same signature as GatewayFilter. @@ -2368,7 +2377,7 @@ This interface and its usage are subject to change in future milestone releases.

    -

    6.1. Combined Global Filter and GatewayFilter Ordering

    +

    7.1. Combined Global Filter and GatewayFilter Ordering

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

    @@ -2408,7 +2417,7 @@ public class CustomGlobalFilter implements GlobalFilter, Ordered {
    -

    6.2. Forward Routing Filter

    +

    7.2. Forward Routing Filter

    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

    -

    6.3. The LoadBalancerClient Filter

    +

    7.3. The LoadBalancerClient Filter

    The 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

    -

    6.4. The ReactiveLoadBalancerClientFilter

    +

    7.4. The ReactiveLoadBalancerClientFilter

    The 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

    -

    6.5. The Netty Routing Filter

    +

    7.5. The Netty Routing Filter

    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

    -

    6.6. The Netty Write Response Filter

    +

    7.6. The Netty Write Response Filter

    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

    -

    6.7. The RouteToRequestUrl Filter

    +

    7.7. The RouteToRequestUrl Filter

    If 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

    -

    6.8. The Websocket Routing Filter

    +

    7.8. The Websocket Routing Filter

    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.

    @@ -2624,7 +2633,7 @@ If you use SockJS as a fallback over nor
    -

    6.9. The Gateway Metrics Filter

    +

    7.9. The Gateway Metrics Filter

    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:

    @@ -2667,7 +2676,7 @@ To enable the prometheus endpoint, add micrometer-registry-prometheus
    -

    6.10. Marking An Exchange As Routed

    +

    7.10. Marking An Exchange As Routed

    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.

    -

    7. TLS and SSL

    +

    8. HttpHeadersFilters

    +
    +
    +

    HttpHeadersFilters are applied to requests before sending them downstream, such as in the NettyRoutingFilter.

    +
    +
    +

    8.1. Forwarded Headers Filter

    +
    +

    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.

    +
    +
    +
    +

    8.2. RemoveHopByHop Headers Filter

    +
    +

    The RemoveHopByHop Headers Filter removes headers from forwarded requests. The default list of headers that is removed comes from the IETF.

    +
    +
    +
    The default removed headers are:
    +
      +
    • +

      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.

    +
    +
    +
    +

    8.3. XForwarded Headers Filter

    +
    +

    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

      +
      • +
    +
    +
    +
    +
    +
    +

    9. TLS and SSL

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

    -

    7.1. TLS Handshake

    +

    9.1. TLS Handshake

    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:<

    -

    8. Configuration

    +

    10. Configuration

    Configuration for Spring Cloud Gateway is driven by a collection of RouteDefinitionLocator instances. @@ -2836,7 +2947,7 @@ The following two examples are equivalent:

    -

    9. Route Metadata Configuration

    +

    11. Route Metadata Configuration

    You can configure additional parameters for each route by using metadata, as follows:

    @@ -2880,13 +2991,13 @@ route.getMetadata(someKey);
    -

    10. Http timeouts configuration

    +

    12. Http timeouts configuration

    Http timeouts (response and connect) can be configured for all routes and overridden for each specific route.

    -

    10.1. Global timeouts

    +

    12.1. Global timeouts

    To configure Global http timeouts:
    connect-timeout must be specified in milliseconds.
    @@ -2905,7 +3016,7 @@ route.getMetadata(someKey);

    -

    10.2. Per-route timeouts

    +

    12.2. Per-route timeouts

    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

    -

    10.3. Fluent Java Routes API

    +

    12.3. Fluent Java Routes API

    To allow for simple configuration in Java, the RouteLocatorBuilder bean includes a fluent API. The following listing shows how it works:

    @@ -2994,7 +3105,7 @@ By using the fluent Java API, you can use the and(), or()
    -

    10.4. The DiscoveryClient Route Definition Locator

    +

    12.4. The DiscoveryClient Route Definition Locator

    You can configure the gateway to create routes based on services registered with a DiscoveryClient compatible service registry.

    @@ -3002,7 +3113,7 @@ By using the fluent Java API, you can use the 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.

    -

    10.4.1. Configuring Predicates and Filters For DiscoveryClient Routes

    +

    12.4.1. Configuring Predicates and Filters For DiscoveryClient Routes

    By default, the fateway defines a single predicate and filter for routes created with a DiscoveryClient.

    @@ -3042,7 +3153,7 @@ spring.cloud.gateway.discovery.locator.filters[1].args[replacement]: "'/${remain
    -

    11. Reactor Netty Access Logs

    +

    13. Reactor Netty Access Logs

    To enable Reactor Netty access logs, set -Dreactor.netty.http.server.accessLogEnabled=true.

    @@ -3087,7 +3198,7 @@ It must be a Java System Property, not a Spring Boot property.
    -

    12. CORS Configuration

    +

    14. CORS Configuration

    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

    -

    13. Actuator API

    +

    15. Actuator API

    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

    -

    13.1. Verbose Actuator Format

    +

    15.1. Verbose Actuator Format

    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:

    -

    13.2. Retrieving Route Filters

    +

    15.2. Retrieving Route Filters

    This section details how to retrieve route filters, including:

    @@ -3200,7 +3311,7 @@ The following example configures /actuator/gateway/routes:

    -

    13.2.1. Global Filters

    +

    15.2.1. Global Filters

    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:

    @@ -3228,7 +3339,7 @@ For each global filter, there is a string representation of the filter object (f
    -

    13.2.2. Route Filters

    +

    15.2.2. Route Filters

    To retrieve the GatewayFilter factories applied to routes, make a GET request to /actuator/gateway/routefilters. The resulting response is similar to the following:

    @@ -3254,14 +3365,14 @@ Note that the null value is due to an incomplete implementation of
    -

    13.3. Refreshing the Route Cache

    +

    15.3. Refreshing the Route Cache

    To clear the routes cache, make a POST request to /actuator/gateway/refresh. The request returns a 200 without a response body.

    -

    13.4. Retrieving the Routes Defined in the Gateway

    +

    15.4. Retrieving the Routes Defined in the Gateway

    To retrieve the routes defined in the gateway, make a GET request to /actuator/gateway/routes. The resulting response is similar to the following:

    @@ -3334,7 +3445,7 @@ The following table describes the structure of each element (each is a route) of
    -

    13.5. Retrieving Information about a Particular Route

    +

    15.5. Retrieving Information about a Particular Route

    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:

    @@ -3403,7 +3514,7 @@ The resulting response is similar to the following:

    -

    13.6. Creating and Deleting a Particular Route

    +

    15.6. Creating and Deleting a Particular Route

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

    @@ -3412,7 +3523,7 @@ The resulting response is similar to the following:

    -

    13.7. Recap: The List of All endpoints

    +

    15.7. Recap: The List of All endpoints

    The folloiwng table below summarizes the Spring Cloud Gateway actuator endpoints (note that each endpoint has /actuator/gateway as the base-path):

    @@ -3471,13 +3582,13 @@ The resulting response is similar to the following:

    -

    14. Troubleshooting

    +

    16. Troubleshooting

    This section covers common problems that may arise when you use Spring Cloud Gateway.

    -

    14.1. Log Levels

    +

    16.1. Log Levels

    The following loggers may contain valuable troubleshooting information at the DEBUG and TRACE levels:

    @@ -3505,7 +3616,7 @@ The resulting response is similar to the following:

    -

    14.2. Wiretap

    +

    16.2. Wiretap

    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

    -

    15. Developer Guide

    +

    17. Developer Guide

    -

    TODO: overview of writing custom integrations

    +

    These are basic guides to writing some custom components of the gateway.

    -

    15.1. Writing Custom Route Predicate Factories

    +

    17.1. Writing Custom Route Predicate Factories

    -

    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.

    +
    +
    +
    MyRoutePredicateFactory.java
    +
    +
    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
+    }
+
+}
    +
    -

    15.2. Writing Custom GatewayFilter Factories

    +

    17.2. Writing Custom GatewayFilter Factories

    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:

    -

    15.3. Writing Custom Global Filters

    +

    17.3. Writing Custom Global Filters

    To write a custom global filter, you must implement GlobalFilter interface. This applies the filter to all requests.

    @@ -3636,17 +3775,23 @@ public GlobalFilter customGlobalPostFilter() {
    -
    -

    15.4. Writing Custom Route Locators and Writers

    -
    -

    TODO: document writing Custom Route Locators and Writers

    -
    -
    -

    16. Building a Simple Gateway by Using Spring MVC or Webflux

    +

    18. Building a Simple Gateway by Using Spring MVC or Webflux

    +
    + + + + + +
    + + +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

    -

    17. Configuration properties

    +

    19. Configuration properties

    To see the list of all Spring Cloud Gateway related configuration properties, see the appendix.