(window.webpackJsonp=window.webpackJsonp||[]).push([[74],{505:function(e,t,a){"use strict";a.r(t);var r=a(56),o=Object(r.a)({},(function(){var e=this,t=e.$createElement,a=e._self._c||t;return a("ContentSlotsDistributor",{attrs:{"slot-key":e.$parent.slotKey}},[a("h1",{attrs:{id:"spring-cloud-gateway"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#spring-cloud-gateway"}},[e._v("#")]),e._v(" Spring Cloud Gateway")]),e._v(" "),a("h2",{attrs:{id:"_1-how-to-include-spring-cloud-gateway"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-how-to-include-spring-cloud-gateway"}},[e._v("#")]),e._v(" 1. How to Include Spring Cloud Gateway")]),e._v(" "),a("p",[e._v("To include Spring Cloud Gateway in your project, use the starter with a group ID of "),a("code",[e._v("org.springframework.cloud")]),e._v(" and an artifact ID of "),a("code",[e._v("spring-cloud-starter-gateway")]),e._v(".\nSee the "),a("a",{attrs:{href:"https://projects.spring.io/spring-cloud/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Cloud Project page"),a("OutboundLink")],1),e._v(" for details on setting up your build system with the current Spring Cloud Release Train.")]),e._v(" "),a("p",[e._v("If you include the starter, but you do not want the gateway to be enabled, set "),a("code",[e._v("spring.cloud.gateway.enabled=false")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Spring Cloud Gateway is built on "),a("a",{attrs:{href:"https://spring.io/projects/spring-boot#learn",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Boot 2.x"),a("OutboundLink")],1),e._v(", "),a("a",{attrs:{href:"https://docs.spring.io/spring/docs/current/spring-framework-reference/web-reactive.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring WebFlux"),a("OutboundLink")],1),e._v(", and "),a("a",{attrs:{href:"https://projectreactor.io/docs",target:"_blank",rel:"noopener noreferrer"}},[e._v("Project Reactor"),a("OutboundLink")],1),e._v("."),a("br"),e._v("As a consequence, many of the familiar synchronous libraries (Spring Data and Spring Security, for example) and patterns you know may not apply when you use Spring Cloud Gateway."),a("br"),e._v("If you are unfamiliar with these projects, we suggest you begin by reading their documentation to familiarize yourself with some of the new concepts before working with Spring Cloud Gateway.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Spring Cloud Gateway requires the Netty runtime provided by Spring Boot and Spring Webflux."),a("br"),e._v("It does not work in a traditional Servlet Container or when built as a WAR.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h2",{attrs:{id:"_2-glossary"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-glossary"}},[e._v("#")]),e._v(" 2. Glossary")]),e._v(" "),a("ul",[a("li",[a("p",[a("strong",[e._v("Route")]),e._v(": The basic building block of the gateway.\nIt is defined by an ID, a destination URI, a collection of predicates, and a collection of filters. A route is matched if the aggregate predicate is true.")])]),e._v(" "),a("li",[a("p",[a("strong",[e._v("Predicate")]),e._v(": This is a "),a("a",{attrs:{href:"https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Java 8 Function Predicate"),a("OutboundLink")],1),e._v(". The input type is a "),a("a",{attrs:{href:"https://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/server/ServerWebExchange.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Framework "),a("code",[e._v("ServerWebExchange")]),a("OutboundLink")],1),e._v(".\nThis lets you match on anything from the HTTP request, such as headers or parameters.")])]),e._v(" "),a("li",[a("p",[a("strong",[e._v("Filter")]),e._v(": These are instances of "),a("a",{attrs:{href:"https://github.com/spring-cloud/spring-cloud-gateway/tree/main/spring-cloud-gateway-server/src/main/java/org/springframework/cloud/gateway/filter/GatewayFilter.java",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("GatewayFilter")]),a("OutboundLink")],1),e._v(" that have been constructed with a specific factory.\nHere, you can modify requests and responses before or after sending the downstream request.")])])]),e._v(" "),a("h2",{attrs:{id:"_3-how-it-works"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-how-it-works"}},[e._v("#")]),e._v(" 3. How It Works")]),e._v(" "),a("p",[e._v("The following diagram provides a high-level overview of how Spring Cloud Gateway works:")]),e._v(" "),a("p",[a("img",{attrs:{src:"https://docs.spring.io/spring-cloud-gateway/docs/3.1.1/reference/html/images/spring_cloud_gateway_diagram.png",alt:"Spring Cloud Gateway Diagram"}})]),e._v(" "),a("p",[e._v("Clients make requests to Spring Cloud Gateway. If the Gateway Handler Mapping determines that a request matches a route, it is sent to the Gateway Web Handler.\nThis handler runs the request through a filter chain that is specific to the request.\nThe reason the filters are divided by the dotted line is that filters can run logic both before and after the proxy request is sent.\nAll “pre” filter logic is executed. Then the proxy request is made. After the proxy request is made, the “post” filter logic is run.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("URIs defined in routes without a port get default port values of 80 and 443 for the HTTP and HTTPS URIs, respectively.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h2",{attrs:{id:"_4-configuring-route-predicate-factories-and-gateway-filter-factories"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_4-configuring-route-predicate-factories-and-gateway-filter-factories"}},[e._v("#")]),e._v(" 4. Configuring Route Predicate Factories and Gateway Filter Factories")]),e._v(" "),a("p",[e._v("There are two ways to configure predicates and filters: shortcuts and fully expanded arguments. Most examples below use the shortcut way.")]),e._v(" "),a("p",[e._v("The name and argument names will be listed as "),a("code",[e._v("code")]),e._v(" 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.")]),e._v(" "),a("h3",{attrs:{id:"_4-1-shortcut-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_4-1-shortcut-configuration"}},[e._v("#")]),e._v(" 4.1. Shortcut Configuration")]),e._v(" "),a("p",[e._v("Shortcut configuration is recognized by the filter name, followed by an equals sign ("),a("code",[e._v("=")]),e._v("), followed by argument values separated by commas ("),a("code",[e._v(",")]),e._v(").")]),e._v(" "),a("p",[e._v("application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: after_route\n        uri: https://example.org\n        predicates:\n        - Cookie=mycookie,mycookievalue\n")])])]),a("p",[e._v("The previous sample defines the "),a("code",[e._v("Cookie")]),e._v(" Route Predicate Factory with two arguments, the cookie name, "),a("code",[e._v("mycookie")]),e._v(" and the value to match "),a("code",[e._v("mycookievalue")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_4-2-fully-expanded-arguments"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_4-2-fully-expanded-arguments"}},[e._v("#")]),e._v(" 4.2. Fully Expanded Arguments")]),e._v(" "),a("p",[e._v("Fully expanded arguments appear more like standard yaml configuration with name/value pairs. Typically, there will be a "),a("code",[e._v("name")]),e._v(" key and an "),a("code",[e._v("args")]),e._v(" key. The "),a("code",[e._v("args")]),e._v(" key is a map of key value pairs to configure the predicate or filter.")]),e._v(" "),a("p",[e._v("application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: after_route\n        uri: https://example.org\n        predicates:\n        - name: Cookie\n          args:\n            name: mycookie\n            regexp: mycookievalue\n")])])]),a("p",[e._v("This is the full configuration of the shortcut configuration of the "),a("code",[e._v("Cookie")]),e._v(" predicate shown above.")]),e._v(" "),a("h2",{attrs:{id:"_5-route-predicate-factories"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-route-predicate-factories"}},[e._v("#")]),e._v(" 5. Route Predicate Factories")]),e._v(" "),a("p",[e._v("Spring Cloud Gateway matches routes as part of the Spring WebFlux "),a("code",[e._v("HandlerMapping")]),e._v(" infrastructure.\nSpring Cloud Gateway includes many built-in route predicate factories.\nAll of these predicates match on different attributes of the HTTP request.\nYou can combine multiple route predicate factories with logical "),a("code",[e._v("and")]),e._v(" statements.")]),e._v(" "),a("h3",{attrs:{id:"_5-1-the-after-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-1-the-after-route-predicate-factory"}},[e._v("#")]),e._v(" 5.1. The After Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("After")]),e._v(" route predicate factory takes one parameter, a "),a("code",[e._v("datetime")]),e._v(" (which is a java "),a("code",[e._v("ZonedDateTime")]),e._v(").\nThis predicate matches requests that happen after the specified datetime.\nThe following example configures an after route predicate:")]),e._v(" "),a("p",[e._v("Example 1. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: after_route\n        uri: https://example.org\n        predicates:\n        - After=2017-01-20T17:42:47.789-07:00[America/Denver]\n")])])]),a("p",[e._v("This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver).")]),e._v(" "),a("h3",{attrs:{id:"_5-2-the-before-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-2-the-before-route-predicate-factory"}},[e._v("#")]),e._v(" 5.2. The Before Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Before")]),e._v(" route predicate factory takes one parameter, a "),a("code",[e._v("datetime")]),e._v(" (which is a java "),a("code",[e._v("ZonedDateTime")]),e._v(").\nThis predicate matches requests that happen before the specified "),a("code",[e._v("datetime")]),e._v(".\nThe following example configures a before route predicate:")]),e._v(" "),a("p",[e._v("Example 2. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: before_route\n        uri: https://example.org\n        predicates:\n        - Before=2017-01-20T17:42:47.789-07:00[America/Denver]\n")])])]),a("p",[e._v("This route matches any request made before Jan 20, 2017 17:42 Mountain Time (Denver).")]),e._v(" "),a("h3",{attrs:{id:"_5-3-the-between-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-3-the-between-route-predicate-factory"}},[e._v("#")]),e._v(" 5.3. The Between Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Between")]),e._v(" route predicate factory takes two parameters, "),a("code",[e._v("datetime1")]),e._v(" and "),a("code",[e._v("datetime2")]),e._v("which are java "),a("code",[e._v("ZonedDateTime")]),e._v(" objects.\nThis predicate matches requests that happen after "),a("code",[e._v("datetime1")]),e._v(" and before "),a("code",[e._v("datetime2")]),e._v(".\nThe "),a("code",[e._v("datetime2")]),e._v(" parameter must be after "),a("code",[e._v("datetime1")]),e._v(".\nThe following example configures a between route predicate:")]),e._v(" "),a("p",[e._v("Example 3. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: between_route\n        uri: https://example.org\n        predicates:\n        - Between=2017-01-20T17:42:47.789-07:00[America/Denver], 2017-01-21T17:42:47.789-07:00[America/Denver]\n")])])]),a("p",[e._v("This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver) and before Jan 21, 2017 17:42 Mountain Time (Denver).\nThis could be useful for maintenance windows.")]),e._v(" "),a("h3",{attrs:{id:"_5-4-the-cookie-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-4-the-cookie-route-predicate-factory"}},[e._v("#")]),e._v(" 5.4. The Cookie Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Cookie")]),e._v(" route predicate factory takes two parameters, the cookie "),a("code",[e._v("name")]),e._v(" and a "),a("code",[e._v("regexp")]),e._v(" (which is a Java regular expression).\nThis predicate matches cookies that have the given name and whose values match the regular expression.\nThe following example configures a cookie route predicate factory:")]),e._v(" "),a("p",[e._v("Example 4. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: cookie_route\n        uri: https://example.org\n        predicates:\n        - Cookie=chocolate, ch.p\n")])])]),a("p",[e._v("This route matches requests that have a cookie named "),a("code",[e._v("chocolate")]),e._v(" whose value matches the "),a("code",[e._v("ch.p")]),e._v(" regular expression.")]),e._v(" "),a("h3",{attrs:{id:"_5-5-the-header-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-5-the-header-route-predicate-factory"}},[e._v("#")]),e._v(" 5.5. The Header Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Header")]),e._v(" route predicate factory takes two parameters, the "),a("code",[e._v("header")]),e._v(" and a "),a("code",[e._v("regexp")]),e._v(" (which is a Java regular expression).\nThis predicate matches with a header that has the given name whose value matches the regular expression.\nThe following example configures a header route predicate:")]),e._v(" "),a("p",[e._v("Example 5. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: header_route\n        uri: https://example.org\n        predicates:\n        - Header=X-Request-Id, \\d+\n")])])]),a("p",[e._v("This route matches if the request has a header named "),a("code",[e._v("X-Request-Id")]),e._v(" whose value matches the "),a("code",[e._v("\\d+")]),e._v(" regular expression (that is, it has a value of one or more digits).")]),e._v(" "),a("h3",{attrs:{id:"_5-6-the-host-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-6-the-host-route-predicate-factory"}},[e._v("#")]),e._v(" 5.6. The Host Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Host")]),e._v(" route predicate factory takes one parameter: a list of host name "),a("code",[e._v("patterns")]),e._v(".\nThe pattern is an Ant-style pattern with "),a("code",[e._v(".")]),e._v(" as the separator.\nThis predicates matches the "),a("code",[e._v("Host")]),e._v(" header that matches the pattern.\nThe following example configures a host route predicate:")]),e._v(" "),a("p",[e._v("Example 6. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: host_route\n        uri: https://example.org\n        predicates:\n        - Host=**.somehost.org,**.anotherhost.org\n")])])]),a("p",[e._v("URI template variables (such as "),a("code",[e._v("{sub}.myhost.org")]),e._v(") are supported as well.")]),e._v(" "),a("p",[e._v("This route matches if the request has a "),a("code",[e._v("Host")]),e._v(" header with a value of "),a("code",[e._v("www.somehost.org")]),e._v(" or "),a("code",[e._v("beta.somehost.org")]),e._v(" or "),a("code",[e._v("www.anotherhost.org")]),e._v(".")]),e._v(" "),a("p",[e._v("This predicate extracts the URI template variables (such as "),a("code",[e._v("sub")]),e._v(", defined in the preceding example) as a map of names and values and places it in the "),a("code",[e._v("ServerWebExchange.getAttributes()")]),e._v(" with a key defined in "),a("code",[e._v("ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE")]),e._v(".\nThose values are then available for use by "),a("a",{attrs:{href:"#gateway-route-filters"}},[a("code",[e._v("GatewayFilter")]),e._v(" factories")])]),e._v(" "),a("h3",{attrs:{id:"_5-7-the-method-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-7-the-method-route-predicate-factory"}},[e._v("#")]),e._v(" 5.7. The Method Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Method")]),e._v(" Route Predicate Factory takes a "),a("code",[e._v("methods")]),e._v(" argument which is one or more parameters: the HTTP methods to match.\nThe following example configures a method route predicate:")]),e._v(" "),a("p",[e._v("Example 7. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: method_route\n        uri: https://example.org\n        predicates:\n        - Method=GET,POST\n")])])]),a("p",[e._v("This route matches if the request method was a "),a("code",[e._v("GET")]),e._v(" or a "),a("code",[e._v("POST")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_5-8-the-path-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-8-the-path-route-predicate-factory"}},[e._v("#")]),e._v(" 5.8. The Path Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Path")]),e._v(" Route Predicate Factory takes two parameters: a list of Spring "),a("code",[e._v("PathMatcher")]),e._v(" "),a("code",[e._v("patterns")]),e._v(" and an optional flag called "),a("code",[e._v("matchTrailingSlash")]),e._v(" (defaults to "),a("code",[e._v("true")]),e._v(").\nThe following example configures a path route predicate:")]),e._v(" "),a("p",[e._v("Example 8. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: path_route\n        uri: https://example.org\n        predicates:\n        - Path=/red/{segment},/blue/{segment}\n")])])]),a("p",[e._v("This route matches if the request path was, for example: "),a("code",[e._v("/red/1")]),e._v(" or "),a("code",[e._v("/red/1/")]),e._v(" or "),a("code",[e._v("/red/blue")]),e._v(" or "),a("code",[e._v("/blue/green")]),e._v(".")]),e._v(" "),a("p",[e._v("If "),a("code",[e._v("matchTrailingSlash")]),e._v(" is set to "),a("code",[e._v("false")]),e._v(", then request path "),a("code",[e._v("/red/1/")]),e._v(" will not be matched.")]),e._v(" "),a("p",[e._v("This predicate extracts the URI template variables (such as "),a("code",[e._v("segment")]),e._v(", defined in the preceding example) as a map of names and values and places it in the "),a("code",[e._v("ServerWebExchange.getAttributes()")]),e._v(" with a key defined in "),a("code",[e._v("ServerWebExchangeUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE")]),e._v(".\nThose values are then available for use by "),a("a",{attrs:{href:"#gateway-route-filters"}},[a("code",[e._v("GatewayFilter")]),e._v(" factories")])]),e._v(" "),a("p",[e._v("A utility method (called "),a("code",[e._v("get")]),e._v(") is available to make access to these variables easier.\nThe following example shows how to use the "),a("code",[e._v("get")]),e._v(" method:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Map<String, String> uriVariables = ServerWebExchangeUtils.getPathPredicateVariables(exchange);\n\nString segment = uriVariables.get("segment");\n')])])]),a("h3",{attrs:{id:"_5-9-the-query-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-9-the-query-route-predicate-factory"}},[e._v("#")]),e._v(" 5.9. The Query Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Query")]),e._v(" route predicate factory takes two parameters: a required "),a("code",[e._v("param")]),e._v(" and an optional "),a("code",[e._v("regexp")]),e._v(" (which is a Java regular expression).\nThe following example configures a query route predicate:")]),e._v(" "),a("p",[e._v("Example 9. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: query_route\n        uri: https://example.org\n        predicates:\n        - Query=green\n")])])]),a("p",[e._v("The preceding route matches if the request contained a "),a("code",[e._v("green")]),e._v(" query parameter.")]),e._v(" "),a("p",[e._v("application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: query_route\n        uri: https://example.org\n        predicates:\n        - Query=red, gree.\n")])])]),a("p",[e._v("The preceding route matches if the request contained a "),a("code",[e._v("red")]),e._v(" query parameter whose value matched the "),a("code",[e._v("gree.")]),e._v(" regexp, so "),a("code",[e._v("green")]),e._v(" and "),a("code",[e._v("greet")]),e._v(" would match.")]),e._v(" "),a("h3",{attrs:{id:"_5-10-the-remoteaddr-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-10-the-remoteaddr-route-predicate-factory"}},[e._v("#")]),e._v(" 5.10. The RemoteAddr Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RemoteAddr")]),e._v(" route predicate factory takes a list (min size 1) of "),a("code",[e._v("sources")]),e._v(", which are CIDR-notation (IPv4 or IPv6) strings, such as "),a("code",[e._v("192.168.0.1/16")]),e._v(" (where "),a("code",[e._v("192.168.0.1")]),e._v(" is an IP address and "),a("code",[e._v("16")]),e._v(" is a subnet mask).\nThe following example configures a RemoteAddr route predicate:")]),e._v(" "),a("p",[e._v("Example 10. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: remoteaddr_route\n        uri: https://example.org\n        predicates:\n        - RemoteAddr=192.168.1.1/24\n")])])]),a("p",[e._v("This route matches if the remote address of the request was, for example, "),a("code",[e._v("192.168.1.10")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_5-10-1-modifying-the-way-remote-addresses-are-resolved"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-10-1-modifying-the-way-remote-addresses-are-resolved"}},[e._v("#")]),e._v(" 5.10.1. Modifying the Way Remote Addresses Are Resolved")]),e._v(" "),a("p",[e._v("By default, the RemoteAddr route predicate factory uses the remote address from the incoming request.\nThis may not match the actual client IP address if Spring Cloud Gateway sits behind a proxy layer.")]),e._v(" "),a("p",[e._v("You can customize the way that the remote address is resolved by setting a custom "),a("code",[e._v("RemoteAddressResolver")]),e._v(".\nSpring Cloud Gateway comes with one non-default remote address resolver that is based off of the "),a("a",{attrs:{href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For",target:"_blank",rel:"noopener noreferrer"}},[e._v("X-Forwarded-For header"),a("OutboundLink")],1),e._v(", "),a("code",[e._v("XForwardedRemoteAddressResolver")]),e._v(".")]),e._v(" "),a("p",[a("code",[e._v("XForwardedRemoteAddressResolver")]),e._v(" has two static constructor methods, which take different approaches to security:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("XForwardedRemoteAddressResolver::trustAll")]),e._v(" returns a "),a("code",[e._v("RemoteAddressResolver")]),e._v(" that always takes the first IP address found in the "),a("code",[e._v("X-Forwarded-For")]),e._v(" header.\nThis approach is vulnerable to spoofing, as a malicious client could set an initial value for the "),a("code",[e._v("X-Forwarded-For")]),e._v(", which would be accepted by the resolver.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("XForwardedRemoteAddressResolver::maxTrustedIndex")]),e._v(" takes an index that correlates to the number of trusted infrastructure running in front of Spring Cloud Gateway.\nIf Spring Cloud Gateway is, for example only accessible through HAProxy, then a value of 1 should be used.\nIf two hops of trusted infrastructure are required before Spring Cloud Gateway is accessible, then a value of 2 should be used.")])])]),e._v(" "),a("p",[e._v("Consider the following header value:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("X-Forwarded-For: 0.0.0.1, 0.0.0.2, 0.0.0.3\n")])])]),a("p",[e._v("The following "),a("code",[e._v("maxTrustedIndex")]),e._v(" values yield the following remote addresses:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[a("code",[e._v("maxTrustedIndex")])]),e._v(" "),a("th",[e._v("result")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[e._v("["),a("code",[e._v("Integer.MIN_VALUE")]),e._v(",0]")]),e._v(" "),a("td",[e._v("(invalid, "),a("code",[e._v("IllegalArgumentException")]),e._v(" during initialization)")])]),e._v(" "),a("tr",[a("td",[e._v("1")]),e._v(" "),a("td",[e._v("0.0.0.3")])]),e._v(" "),a("tr",[a("td",[e._v("2")]),e._v(" "),a("td",[e._v("0.0.0.2")])]),e._v(" "),a("tr",[a("td",[e._v("3")]),e._v(" "),a("td",[e._v("0.0.0.1")])]),e._v(" "),a("tr",[a("td",[e._v("[4, "),a("code",[e._v("Integer.MAX_VALUE")]),e._v("]")]),e._v(" "),a("td",[e._v("0.0.0.1")])])])]),e._v(" "),a("p",[e._v("The following example shows how to achieve the same configuration with Java:")]),e._v(" "),a("p",[e._v("Example 11. GatewayConfig.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RemoteAddressResolver resolver = XForwardedRemoteAddressResolver\n    .maxTrustedIndex(1);\n\n...\n\n.route("direct-route",\n    r -> r.remoteAddr("10.1.1.1", "10.10.1.1/24")\n        .uri("https://downstream1")\n.route("proxied-route",\n    r -> r.remoteAddr(resolver, "10.10.1.1", "10.10.1.1/24")\n        .uri("https://downstream2")\n)\n')])])]),a("h3",{attrs:{id:"_5-11-the-weight-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-11-the-weight-route-predicate-factory"}},[e._v("#")]),e._v(" 5.11. The Weight Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Weight")]),e._v(" route predicate factory takes two arguments: "),a("code",[e._v("group")]),e._v(" and "),a("code",[e._v("weight")]),e._v(" (an int). The weights are calculated per group.\nThe following example configures a weight route predicate:")]),e._v(" "),a("p",[e._v("Example 12. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: weight_high\n        uri: https://weighthigh.org\n        predicates:\n        - Weight=group1, 8\n      - id: weight_low\n        uri: https://weightlow.org\n        predicates:\n        - Weight=group1, 2\n")])])]),a("p",[e._v("This route would forward ~80% of traffic to "),a("a",{attrs:{href:"https://weighthigh.org",target:"_blank",rel:"noopener noreferrer"}},[e._v("weighthigh.org"),a("OutboundLink")],1),e._v(" and ~20% of traffic to "),a("a",{attrs:{href:"https://weighlow.org",target:"_blank",rel:"noopener noreferrer"}},[e._v("weighlow.org"),a("OutboundLink")],1)]),e._v(" "),a("h3",{attrs:{id:"_5-12-the-xforwarded-remote-addr-route-predicate-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-12-the-xforwarded-remote-addr-route-predicate-factory"}},[e._v("#")]),e._v(" 5.12. The XForwarded Remote Addr Route Predicate Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("XForwarded Remote Addr")]),e._v(" route predicate factory takes a list (min size 1) of "),a("code",[e._v("sources")]),e._v(", which are CIDR-notation (IPv4 or IPv6) strings, such as "),a("code",[e._v("192.168.0.1/16")]),e._v(" (where "),a("code",[e._v("192.168.0.1")]),e._v(" is an IP address and "),a("code",[e._v("16")]),e._v(" is a subnet mask).")]),e._v(" "),a("p",[e._v("This route predicate allows requests to be filtered based on the "),a("code",[e._v("X-Forwarded-For")]),e._v(" HTTP header.")]),e._v(" "),a("p",[e._v("This can be used with reverse proxies such as load balancers or web application firewalls where\nthe request should only be allowed if it comes from a trusted list of IP addresses used by those\nreverse proxies.")]),e._v(" "),a("p",[e._v("The following example configures a XForwardedRemoteAddr route predicate:")]),e._v(" "),a("p",[e._v("Example 13. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: xforwarded_remoteaddr_route\n        uri: https://example.org\n        predicates:\n        - XForwardedRemoteAddr=192.168.1.1/24\n")])])]),a("p",[e._v("This route matches if the "),a("code",[e._v("X-Forwarded-For")]),e._v(" header contains, for example, "),a("code",[e._v("192.168.1.10")]),e._v(".")]),e._v(" "),a("h2",{attrs:{id:"_6-gatewayfilter-factories"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-gatewayfilter-factories"}},[e._v("#")]),e._v(" 6. "),a("code",[e._v("GatewayFilter")]),e._v(" Factories")]),e._v(" "),a("p",[e._v("Route filters allow the modification of the incoming HTTP request or outgoing HTTP response in some manner.\nRoute filters are scoped to a particular route.\nSpring Cloud Gateway includes many built-in GatewayFilter Factories.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("For more detailed examples of how to use any of the following filters, take a look at the "),a("a",{attrs:{href:"https://github.com/spring-cloud/spring-cloud-gateway/tree/master/spring-cloud-gateway-server/src/test/java/org/springframework/cloud/gateway/filter/factory",target:"_blank",rel:"noopener noreferrer"}},[e._v("unit tests"),a("OutboundLink")],1),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_6-1-the-addrequestheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-1-the-addrequestheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.1. The "),a("code",[e._v("AddRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("AddRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a "),a("code",[e._v("name")]),e._v(" and "),a("code",[e._v("value")]),e._v(" parameter.\nThe following example configures an "),a("code",[e._v("AddRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 14. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: add_request_header_route\n        uri: https://example.org\n        filters:\n        - AddRequestHeader=X-Request-red, blue\n")])])]),a("p",[e._v("This listing adds "),a("code",[e._v("X-Request-red:blue")]),e._v(" header to the downstream request’s headers for all matching requests.")]),e._v(" "),a("p",[a("code",[e._v("AddRequestHeader")]),e._v(" is aware of the URI variables used to match a path or host.\nURI variables may be used in the value and are expanded at runtime.\nThe following example configures an "),a("code",[e._v("AddRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" that uses a variable:")]),e._v(" "),a("p",[e._v("Example 15. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: add_request_header_route\n        uri: https://example.org\n        predicates:\n        - Path=/red/{segment}\n        filters:\n        - AddRequestHeader=X-Request-Red, Blue-{segment}\n")])])]),a("h3",{attrs:{id:"_6-2-the-addrequestparameter-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-2-the-addrequestparameter-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.2. The "),a("code",[e._v("AddRequestParameter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("AddRequestParameter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory takes a "),a("code",[e._v("name")]),e._v(" and "),a("code",[e._v("value")]),e._v(" parameter.\nThe following example configures an "),a("code",[e._v("AddRequestParameter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 16. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: add_request_parameter_route\n        uri: https://example.org\n        filters:\n        - AddRequestParameter=red, blue\n")])])]),a("p",[e._v("This will add "),a("code",[e._v("red=blue")]),e._v(" to the downstream request’s query string for all matching requests.")]),e._v(" "),a("p",[a("code",[e._v("AddRequestParameter")]),e._v(" is aware of the URI variables used to match a path or host.\nURI variables may be used in the value and are expanded at runtime.\nThe following example configures an "),a("code",[e._v("AddRequestParameter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" that uses a variable:")]),e._v(" "),a("p",[e._v("Example 17. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: add_request_parameter_route\n        uri: https://example.org\n        predicates:\n        - Host: {segment}.myhost.org\n        filters:\n        - AddRequestParameter=foo, bar-{segment}\n")])])]),a("h3",{attrs:{id:"_6-3-the-addresponseheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-3-the-addresponseheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.3. The "),a("code",[e._v("AddResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("AddResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory takes a "),a("code",[e._v("name")]),e._v(" and "),a("code",[e._v("value")]),e._v(" parameter.\nThe following example configures an "),a("code",[e._v("AddResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 18. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: add_response_header_route\n        uri: https://example.org\n        filters:\n        - AddResponseHeader=X-Response-Red, Blue\n")])])]),a("p",[e._v("This adds "),a("code",[e._v("X-Response-Red:Blue")]),e._v(" header to the downstream response’s headers for all matching requests.")]),e._v(" "),a("p",[a("code",[e._v("AddResponseHeader")]),e._v(" is aware of URI variables used to match a path or host.\nURI variables may be used in the value and are expanded at runtime.\nThe following example configures an "),a("code",[e._v("AddResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" that uses a variable:")]),e._v(" "),a("p",[e._v("Example 19. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: add_response_header_route\n        uri: https://example.org\n        predicates:\n        - Host: {segment}.myhost.org\n        filters:\n        - AddResponseHeader=foo, bar-{segment}\n")])])]),a("h3",{attrs:{id:"_6-4-the-deduperesponseheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-4-the-deduperesponseheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.4. The "),a("code",[e._v("DedupeResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The DedupeResponseHeader GatewayFilter factory takes a "),a("code",[e._v("name")]),e._v(" parameter and an optional "),a("code",[e._v("strategy")]),e._v(" parameter. "),a("code",[e._v("name")]),e._v(" can contain a space-separated list of header names.\nThe following example configures a "),a("code",[e._v("DedupeResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 20. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: dedupe_response_header_route\n        uri: https://example.org\n        filters:\n        - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin\n")])])]),a("p",[e._v("This removes duplicate values of "),a("code",[e._v("Access-Control-Allow-Credentials")]),e._v(" and "),a("code",[e._v("Access-Control-Allow-Origin")]),e._v(" response headers in cases when both the gateway CORS logic and the downstream logic add them.")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("DedupeResponseHeader")]),e._v(" filter also accepts an optional "),a("code",[e._v("strategy")]),e._v(" parameter.\nThe accepted values are "),a("code",[e._v("RETAIN_FIRST")]),e._v(" (default), "),a("code",[e._v("RETAIN_LAST")]),e._v(", and "),a("code",[e._v("RETAIN_UNIQUE")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_6-5-spring-cloud-circuitbreaker-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-5-spring-cloud-circuitbreaker-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.5. Spring Cloud CircuitBreaker GatewayFilter Factory")]),e._v(" "),a("p",[e._v("The Spring Cloud CircuitBreaker GatewayFilter factory uses the Spring Cloud CircuitBreaker APIs to wrap Gateway routes in\na circuit breaker. Spring Cloud CircuitBreaker supports multiple libraries that can be used with Spring Cloud Gateway. Spring Cloud supports Resilience4J out of the box.")]),e._v(" "),a("p",[e._v("To enable the Spring Cloud CircuitBreaker filter, you need to place "),a("code",[e._v("spring-cloud-starter-circuitbreaker-reactor-resilience4j")]),e._v(" on the classpath.\nThe following example configures a Spring Cloud CircuitBreaker "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 21. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: circuitbreaker_route\n        uri: https://example.org\n        filters:\n        - CircuitBreaker=myCircuitBreaker\n")])])]),a("p",[e._v("To configure the circuit breaker, see the configuration for the underlying circuit breaker implementation you are using.")]),e._v(" "),a("ul",[a("li",[a("a",{attrs:{href:"https://cloud.spring.io/spring-cloud-circuitbreaker/reference/html/spring-cloud-circuitbreaker.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Resilience4J Documentation"),a("OutboundLink")],1)])]),e._v(" "),a("p",[e._v("The Spring Cloud CircuitBreaker filter can also accept an optional "),a("code",[e._v("fallbackUri")]),e._v(" parameter.\nCurrently, only "),a("code",[e._v("forward:")]),e._v(" schemed URIs are supported.\nIf the fallback is called, the request is forwarded to the controller matched by the URI.\nThe following example configures such a fallback:")]),e._v(" "),a("p",[e._v("Example 22. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: circuitbreaker_route\n        uri: lb://backing-service:8088\n        predicates:\n        - Path=/consumingServiceEndpoint\n        filters:\n        - name: CircuitBreaker\n          args:\n            name: myCircuitBreaker\n            fallbackUri: forward:/inCaseOfFailureUseThis\n        - RewritePath=/consumingServiceEndpoint, /backingServiceEndpoint\n")])])]),a("p",[e._v("The following listing does the same thing in Java:")]),e._v(" "),a("p",[e._v("Example 23. Application.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic RouteLocator routes(RouteLocatorBuilder builder) {\n    return builder.routes()\n        .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint")\n            .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis"))\n                .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088")\n        .build();\n}\n')])])]),a("p",[e._v("This example forwards to the "),a("code",[e._v("/inCaseofFailureUseThis")]),e._v(" URI when the circuit breaker fallback is called.\nNote that this example also demonstrates the (optional) Spring Cloud LoadBalancer load-balancing (defined by the "),a("code",[e._v("lb")]),e._v(" prefix on the destination URI).")]),e._v(" "),a("p",[e._v("The primary scenario is to use the "),a("code",[e._v("fallbackUri")]),e._v(" to define an internal controller or handler within the gateway application.\nHowever, you can also reroute the request to a controller or handler in an external application, as follows:")]),e._v(" "),a("p",[e._v("Example 24. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: ingredients\n        uri: lb://ingredients\n        predicates:\n        - Path=//ingredients/**\n        filters:\n        - name: CircuitBreaker\n          args:\n            name: fetchIngredients\n            fallbackUri: forward:/fallback\n      - id: ingredients-fallback\n        uri: http://localhost:9994\n        predicates:\n        - Path=/fallback\n")])])]),a("p",[e._v("In this example, there is no "),a("code",[e._v("fallback")]),e._v(" endpoint or handler in the gateway application.\nHowever, there is one in another application, registered under "),a("code",[e._v("[localhost:9994](http://localhost:9994)")]),e._v(".")]),e._v(" "),a("p",[e._v("In case of the request being forwarded to fallback, the Spring Cloud CircuitBreaker Gateway filter also provides the "),a("code",[e._v("Throwable")]),e._v(" that has caused it.\nIt is added to the "),a("code",[e._v("ServerWebExchange")]),e._v(" as the "),a("code",[e._v("ServerWebExchangeUtils.CIRCUITBREAKER_EXECUTION_EXCEPTION_ATTR")]),e._v(" attribute that can be used when handling the fallback within the gateway application.")]),e._v(" "),a("p",[e._v("For the external controller/handler scenario, headers can be added with exception details.\nYou can find more information on doing so in the "),a("a",{attrs:{href:"#fallback-headers"}},[e._v("FallbackHeaders GatewayFilter Factory section")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_6-5-1-tripping-the-circuit-breaker-on-status-codes"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-5-1-tripping-the-circuit-breaker-on-status-codes"}},[e._v("#")]),e._v(" 6.5.1. Tripping The Circuit Breaker On Status Codes")]),e._v(" "),a("p",[e._v("In some cases you might want to trip a circuit breaker based on the status code\nreturned from the route it wraps. The circuit breaker config object takes a list of\nstatus codes that if returned will cause the the circuit breaker to be tripped. When setting the\nstatus codes you want to trip the circuit breaker you can either use a integer with the status code\nvalue or the String representation of the "),a("code",[e._v("HttpStatus")]),e._v(" enumeration.")]),e._v(" "),a("p",[e._v("Example 25. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('spring:\n  cloud:\n    gateway:\n      routes:\n      - id: circuitbreaker_route\n        uri: lb://backing-service:8088\n        predicates:\n        - Path=/consumingServiceEndpoint\n        filters:\n        - name: CircuitBreaker\n          args:\n            name: myCircuitBreaker\n            fallbackUri: forward:/inCaseOfFailureUseThis\n            statusCodes:\n              - 500\n              - "NOT_FOUND"\n')])])]),a("p",[e._v("Example 26. Application.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic RouteLocator routes(RouteLocatorBuilder builder) {\n    return builder.routes()\n        .route("circuitbreaker_route", r -> r.path("/consumingServiceEndpoint")\n            .filters(f -> f.circuitBreaker(c -> c.name("myCircuitBreaker").fallbackUri("forward:/inCaseOfFailureUseThis").addStatusCode("INTERNAL_SERVER_ERROR"))\n                .rewritePath("/consumingServiceEndpoint", "/backingServiceEndpoint")).uri("lb://backing-service:8088")\n        .build();\n}\n')])])]),a("h3",{attrs:{id:"_6-6-the-fallbackheaders-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-6-the-fallbackheaders-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.6. The "),a("code",[e._v("FallbackHeaders")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("FallbackHeaders")]),e._v(" factory lets you add Spring Cloud CircuitBreaker execution exception details in the headers of a request forwarded to a "),a("code",[e._v("fallbackUri")]),e._v(" in an external application, as in the following scenario:")]),e._v(" "),a("p",[e._v("Example 27. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: ingredients\n        uri: lb://ingredients\n        predicates:\n        - Path=//ingredients/**\n        filters:\n        - name: CircuitBreaker\n          args:\n            name: fetchIngredients\n            fallbackUri: forward:/fallback\n      - id: ingredients-fallback\n        uri: http://localhost:9994\n        predicates:\n        - Path=/fallback\n        filters:\n        - name: FallbackHeaders\n          args:\n            executionExceptionTypeHeaderName: Test-Header\n")])])]),a("p",[e._v("In this example, after an execution exception occurs while running the circuit breaker, the request is forwarded to the "),a("code",[e._v("fallback")]),e._v(" endpoint or handler in an application running on "),a("code",[e._v("localhost:9994")]),e._v(".\nThe headers with the exception type, message and (if available) root cause exception type and message are added to that request by the "),a("code",[e._v("FallbackHeaders")]),e._v(" filter.")]),e._v(" "),a("p",[e._v("You can overwrite the names of the headers in the configuration by setting the values of the following arguments (shown with their default values):")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("executionExceptionTypeHeaderName")]),e._v(" ("),a("code",[e._v('"Execution-Exception-Type"')]),e._v(")")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("executionExceptionMessageHeaderName")]),e._v(" ("),a("code",[e._v('"Execution-Exception-Message"')]),e._v(")")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("rootCauseExceptionTypeHeaderName")]),e._v(" ("),a("code",[e._v('"Root-Cause-Exception-Type"')]),e._v(")")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("rootCauseExceptionMessageHeaderName")]),e._v(" ("),a("code",[e._v('"Root-Cause-Exception-Message"')]),e._v(")")])])]),e._v(" "),a("p",[e._v("For more information on circuit breakers and the gateway see the "),a("a",{attrs:{href:"#spring-cloud-circuitbreaker-filter-factory"}},[e._v("Spring Cloud CircuitBreaker Factory section")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_6-7-the-maprequestheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-7-the-maprequestheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.7. The "),a("code",[e._v("MapRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("MapRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes "),a("code",[e._v("fromHeader")]),e._v(" and "),a("code",[e._v("toHeader")]),e._v(" parameters.\nIt creates a new named header ("),a("code",[e._v("toHeader")]),e._v("), and the value is extracted out of an existing named header ("),a("code",[e._v("fromHeader")]),e._v(") from the incoming http request.\nIf the input header does not exist, the filter has no impact.\nIf the new named header already exists, its values are augmented with the new values.\nThe following example configures a "),a("code",[e._v("MapRequestHeader")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 28. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: map_request_header_route\n        uri: https://example.org\n        filters:\n        - MapRequestHeader=Blue, X-Request-Red\n")])])]),a("p",[e._v("This adds "),a("code",[e._v("X-Request-Red:<values>")]),e._v(" header to the downstream request with updated values from the incoming HTTP request’s "),a("code",[e._v("Blue")]),e._v(" header.")]),e._v(" "),a("h3",{attrs:{id:"_6-8-the-prefixpath-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-8-the-prefixpath-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.8. The "),a("code",[e._v("PrefixPath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("PrefixPath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a single "),a("code",[e._v("prefix")]),e._v(" parameter.\nThe following example configures a "),a("code",[e._v("PrefixPath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 29. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: prefixpath_route\n        uri: https://example.org\n        filters:\n        - PrefixPath=/mypath\n")])])]),a("p",[e._v("This will prefix "),a("code",[e._v("/mypath")]),e._v(" to the path of all matching requests.\nSo a request to "),a("code",[e._v("/hello")]),e._v(" would be sent to "),a("code",[e._v("/mypath/hello")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_6-9-the-preservehostheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-9-the-preservehostheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.9. The "),a("code",[e._v("PreserveHostHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("PreserveHostHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory has no parameters.\nThis 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.\nThe following example configures a "),a("code",[e._v("PreserveHostHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 30. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: preserve_host_route\n        uri: https://example.org\n        filters:\n        - PreserveHostHeader\n")])])]),a("h3",{attrs:{id:"_6-10-the-requestratelimiter-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-10-the-requestratelimiter-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.10. The "),a("code",[e._v("RequestRateLimiter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RequestRateLimiter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory uses a "),a("code",[e._v("RateLimiter")]),e._v(" implementation to determine if the current request is allowed to proceed. If it is not, a status of "),a("code",[e._v("HTTP 429 - Too Many Requests")]),e._v(" (by default) is returned.")]),e._v(" "),a("p",[e._v("This filter takes an optional "),a("code",[e._v("keyResolver")]),e._v(" parameter and parameters specific to the rate limiter (described later in this section).")]),e._v(" "),a("p",[a("code",[e._v("keyResolver")]),e._v(" is a bean that implements the "),a("code",[e._v("KeyResolver")]),e._v(" interface.\nIn configuration, reference the bean by name using SpEL."),a("code",[e._v("#{@myKeyResolver}")]),e._v(" is a SpEL expression that references a bean named "),a("code",[e._v("myKeyResolver")]),e._v(".\nThe following listing shows the "),a("code",[e._v("KeyResolver")]),e._v(" interface:")]),e._v(" "),a("p",[e._v("Example 31. KeyResolver.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("public interface KeyResolver {\n    Mono<String> resolve(ServerWebExchange exchange);\n}\n")])])]),a("p",[e._v("The "),a("code",[e._v("KeyResolver")]),e._v(" interface lets pluggable strategies derive the key for limiting requests.\nIn future milestone releases, there will be some "),a("code",[e._v("KeyResolver")]),e._v(" implementations.")]),e._v(" "),a("p",[e._v("The default implementation of "),a("code",[e._v("KeyResolver")]),e._v(" is the "),a("code",[e._v("PrincipalNameKeyResolver")]),e._v(", which retrieves the "),a("code",[e._v("Principal")]),e._v(" from the "),a("code",[e._v("ServerWebExchange")]),e._v(" and calls "),a("code",[e._v("Principal.getName()")]),e._v(".")]),e._v(" "),a("p",[e._v("By default, if the "),a("code",[e._v("KeyResolver")]),e._v(" does not find a key, requests are denied.\nYou can adjust this behavior by setting the "),a("code",[e._v("spring.cloud.gateway.filter.request-rate-limiter.deny-empty-key")]),e._v(" ("),a("code",[e._v("true")]),e._v(" or "),a("code",[e._v("false")]),e._v(") and "),a("code",[e._v("spring.cloud.gateway.filter.request-rate-limiter.empty-key-status-code")]),e._v(" properties.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The "),a("code",[e._v("RequestRateLimiter")]),e._v(' is not configurable with the "shortcut" notation. The following example below is '),a("em",[e._v("invalid")]),e._v(":"),a("br"),a("br"),e._v("Example 32. application.properties"),a("br"),a("br"),a("code",[e._v("<br/># INVALID SHORTCUT CONFIGURATION<br/>spring.cloud.gateway.routes[0].filters[0]=RequestRateLimiter=2, 2, #{@userkeyresolver}<br/>")])])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_6-10-1-the-redis-ratelimiter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-10-1-the-redis-ratelimiter"}},[e._v("#")]),e._v(" 6.10.1. The Redis "),a("code",[e._v("RateLimiter")])]),e._v(" "),a("p",[e._v("The Redis implementation is based off of work done at "),a("a",{attrs:{href:"https://stripe.com/blog/rate-limiters",target:"_blank",rel:"noopener noreferrer"}},[e._v("Stripe"),a("OutboundLink")],1),e._v(".\nIt requires the use of the "),a("code",[e._v("spring-boot-starter-data-redis-reactive")]),e._v(" Spring Boot starter.")]),e._v(" "),a("p",[e._v("The algorithm used is the "),a("a",{attrs:{href:"https://en.wikipedia.org/wiki/Token_bucket",target:"_blank",rel:"noopener noreferrer"}},[e._v("Token Bucket Algorithm"),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("redis-rate-limiter.replenishRate")]),e._v(" property is how many requests per second you want a user to be allowed to do, without any dropped requests.\nThis is the rate at which the token bucket is filled.")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("redis-rate-limiter.burstCapacity")]),e._v(" property is the maximum number of requests a user is allowed to do in a single second.\nThis is the number of tokens the token bucket can hold.\nSetting this value to zero blocks all requests.")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("redis-rate-limiter.requestedTokens")]),e._v(" property is how many tokens a request costs.\nThis is the number of tokens taken from the bucket for each request and defaults to "),a("code",[e._v("1")]),e._v(".")]),e._v(" "),a("p",[e._v("A steady rate is accomplished by setting the same value in "),a("code",[e._v("replenishRate")]),e._v(" and "),a("code",[e._v("burstCapacity")]),e._v(".\nTemporary bursts can be allowed by setting "),a("code",[e._v("burstCapacity")]),e._v(" higher than "),a("code",[e._v("replenishRate")]),e._v(".\nIn this case, the rate limiter needs to be allowed some time between bursts (according to "),a("code",[e._v("replenishRate")]),e._v("), as two consecutive bursts will result in dropped requests ("),a("code",[e._v("HTTP 429 - Too Many Requests")]),e._v(").\nThe following listing configures a "),a("code",[e._v("redis-rate-limiter")]),e._v(":")]),e._v(" "),a("p",[e._v("Rate limits bellow "),a("code",[e._v("1 request/s")]),e._v(" are accomplished by setting "),a("code",[e._v("replenishRate")]),e._v(" to the wanted number of requests, "),a("code",[e._v("requestedTokens")]),e._v(" to the timespan in seconds and "),a("code",[e._v("burstCapacity")]),e._v(" to the product of "),a("code",[e._v("replenishRate")]),e._v(" and "),a("code",[e._v("requestedTokens")]),e._v(", e.g. setting "),a("code",[e._v("replenishRate=1")]),e._v(", "),a("code",[e._v("requestedTokens=60")]),e._v(" and "),a("code",[e._v("burstCapacity=60")]),e._v(" will result in a limit of "),a("code",[e._v("1 request/min")]),e._v(".")]),e._v(" "),a("p",[e._v("Example 33. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: requestratelimiter_route\n        uri: https://example.org\n        filters:\n        - name: RequestRateLimiter\n          args:\n            redis-rate-limiter.replenishRate: 10\n            redis-rate-limiter.burstCapacity: 20\n            redis-rate-limiter.requestedTokens: 1\n")])])]),a("p",[e._v("The following example configures a KeyResolver in Java:")]),e._v(" "),a("p",[e._v("Example 34. Config.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\nKeyResolver userKeyResolver() {\n    return exchange -> Mono.just(exchange.getRequest().getQueryParams().getFirst("user"));\n}\n')])])]),a("p",[e._v("This defines a request rate limit of 10 per user. A burst of 20 is allowed, but, in the next second, only 10 requests are available.\nThe "),a("code",[e._v("KeyResolver")]),e._v(" is a simple one that gets the "),a("code",[e._v("user")]),e._v(" request parameter (note that this is not recommended for production).")]),e._v(" "),a("p",[e._v("You can also define a rate limiter as a bean that implements the "),a("code",[e._v("RateLimiter")]),e._v(" interface.\nIn configuration, you can reference the bean by name using SpEL."),a("code",[e._v("#{@myRateLimiter}")]),e._v(" is a SpEL expression that references a bean with named "),a("code",[e._v("myRateLimiter")]),e._v(".\nThe following listing defines a rate limiter that uses the "),a("code",[e._v("KeyResolver")]),e._v(" defined in the previous listing:")]),e._v(" "),a("p",[e._v("Example 35. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('spring:\n  cloud:\n    gateway:\n      routes:\n      - id: requestratelimiter_route\n        uri: https://example.org\n        filters:\n        - name: RequestRateLimiter\n          args:\n            rate-limiter: "#{@myRateLimiter}"\n            key-resolver: "#{@userKeyResolver}"\n')])])]),a("h3",{attrs:{id:"_6-11-the-redirectto-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-11-the-redirectto-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.11. The "),a("code",[e._v("RedirectTo")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RedirectTo")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes two parameters, "),a("code",[e._v("status")]),e._v(" and "),a("code",[e._v("url")]),e._v(".\nThe "),a("code",[e._v("status")]),e._v(" parameter should be a 300 series redirect HTTP code, such as 301.\nThe "),a("code",[e._v("url")]),e._v(" parameter should be a valid URL.\nThis is the value of the "),a("code",[e._v("Location")]),e._v(" header.\nFor relative redirects, you should use "),a("code",[e._v("uri: no://op")]),e._v(" as the uri of your route definition.\nThe following listing configures a "),a("code",[e._v("RedirectTo")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 36. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: prefixpath_route\n        uri: https://example.org\n        filters:\n        - RedirectTo=302, https://acme.org\n")])])]),a("p",[e._v("This will send a status 302 with a "),a("code",[e._v("Location:https://acme.org")]),e._v(" header to perform a redirect.")]),e._v(" "),a("h3",{attrs:{id:"_6-12-the-removerequestheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-12-the-removerequestheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.12. The "),a("code",[e._v("RemoveRequestHeader")]),e._v(" GatewayFilter Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RemoveRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a "),a("code",[e._v("name")]),e._v(" parameter.\nIt is the name of the header to be removed.\nThe following listing configures a "),a("code",[e._v("RemoveRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 37. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: removerequestheader_route\n        uri: https://example.org\n        filters:\n        - RemoveRequestHeader=X-Request-Foo\n")])])]),a("p",[e._v("This removes the "),a("code",[e._v("X-Request-Foo")]),e._v(" header before it is sent downstream.")]),e._v(" "),a("h3",{attrs:{id:"_6-13-removeresponseheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-13-removeresponseheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.13. "),a("code",[e._v("RemoveResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RemoveResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a "),a("code",[e._v("name")]),e._v(" parameter.\nIt is the name of the header to be removed.\nThe following listing configures a "),a("code",[e._v("RemoveResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 38. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: removeresponseheader_route\n        uri: https://example.org\n        filters:\n        - RemoveResponseHeader=X-Response-Foo\n")])])]),a("p",[e._v("This will remove the "),a("code",[e._v("X-Response-Foo")]),e._v(" header from the response before it is returned to the gateway client.")]),e._v(" "),a("p",[e._v("To remove any kind of sensitive header, you should configure this filter for any routes for which you may want to do so.\nIn addition, you can configure this filter once by using "),a("code",[e._v("spring.cloud.gateway.default-filters")]),e._v(" and have it applied to all routes.")]),e._v(" "),a("h3",{attrs:{id:"_6-14-the-removerequestparameter-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-14-the-removerequestparameter-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.14. The "),a("code",[e._v("RemoveRequestParameter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RemoveRequestParameter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a "),a("code",[e._v("name")]),e._v(" parameter.\nIt is the name of the query parameter to be removed.\nThe following example configures a "),a("code",[e._v("RemoveRequestParameter")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 39. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: removerequestparameter_route\n        uri: https://example.org\n        filters:\n        - RemoveRequestParameter=red\n")])])]),a("p",[e._v("This will remove the "),a("code",[e._v("red")]),e._v(" parameter before it is sent downstream.")]),e._v(" "),a("h3",{attrs:{id:"_6-15-the-rewritepath-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-15-the-rewritepath-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.15. The "),a("code",[e._v("RewritePath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RewritePath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a path "),a("code",[e._v("regexp")]),e._v(" parameter and a "),a("code",[e._v("replacement")]),e._v(" parameter.\nThis uses Java regular expressions for a flexible way to rewrite the request path.\nThe following listing configures a "),a("code",[e._v("RewritePath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 40. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: rewritepath_route\n        uri: https://example.org\n        predicates:\n        - Path=/red/**\n        filters:\n        - RewritePath=/red/?(?<segment>.*), /$\\{segment}\n")])])]),a("p",[e._v("For a request path of "),a("code",[e._v("/red/blue")]),e._v(", this sets the path to "),a("code",[e._v("/blue")]),e._v(" before making the downstream request. Note that the "),a("code",[e._v("$")]),e._v(" should be replaced with "),a("code",[e._v("$\\")]),e._v(" because of the YAML specification.")]),e._v(" "),a("h3",{attrs:{id:"_6-16-rewritelocationresponseheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-16-rewritelocationresponseheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.16. "),a("code",[e._v("RewriteLocationResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RewriteLocationResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory modifies the value of the "),a("code",[e._v("Location")]),e._v(" response header, usually to get rid of backend-specific details.\nIt takes "),a("code",[e._v("stripVersionMode")]),e._v(", "),a("code",[e._v("locationHeaderName")]),e._v(", "),a("code",[e._v("hostValue")]),e._v(", and "),a("code",[e._v("protocolsRegex")]),e._v(" parameters.\nThe following listing configures a "),a("code",[e._v("RewriteLocationResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 41. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: rewritelocationresponseheader_route\n        uri: http://example.org\n        filters:\n        - RewriteLocationResponseHeader=AS_IN_REQUEST, Location, ,\n")])])]),a("p",[e._v("For example, for a request of "),a("code",[e._v("POST [api.example.com/some/object/name](https://api.example.com/some/object/name)")]),e._v(", the "),a("code",[e._v("Location")]),e._v(" response header value of "),a("code",[e._v("[object-service.prod.example.net/v2/some/object/id](https://object-service.prod.example.net/v2/some/object/id)")]),e._v(" is rewritten as "),a("code",[e._v("[api.example.com/some/object/id](https://api.example.com/some/object/id)")]),e._v(".")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("stripVersionMode")]),e._v(" parameter has the following possible values: "),a("code",[e._v("NEVER_STRIP")]),e._v(", "),a("code",[e._v("AS_IN_REQUEST")]),e._v(" (default), and "),a("code",[e._v("ALWAYS_STRIP")]),e._v(".")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("NEVER_STRIP")]),e._v(": The version is not stripped, even if the original request path contains no version.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("AS_IN_REQUEST")]),e._v(" The version is stripped only if the original request path contains no version.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("ALWAYS_STRIP")]),e._v(" The version is always stripped, even if the original request path contains version.")])])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("hostValue")]),e._v(" parameter, if provided, is used to replace the "),a("code",[e._v("host:port")]),e._v(" portion of the response "),a("code",[e._v("Location")]),e._v(" header.\nIf it is not provided, the value of the "),a("code",[e._v("Host")]),e._v(" request header is used.")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("protocolsRegex")]),e._v(" parameter must be a valid regex "),a("code",[e._v("String")]),e._v(", against which the protocol name is matched.\nIf it is not matched, the filter does nothing.\nThe default is "),a("code",[e._v("http|https|ftp|ftps")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_6-17-the-rewriteresponseheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-17-the-rewriteresponseheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.17. The "),a("code",[e._v("RewriteResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RewriteResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes "),a("code",[e._v("name")]),e._v(", "),a("code",[e._v("regexp")]),e._v(", and "),a("code",[e._v("replacement")]),e._v(" parameters.\nIt uses Java regular expressions for a flexible way to rewrite the response header value.\nThe following example configures a "),a("code",[e._v("RewriteResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 42. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: rewriteresponseheader_route\n        uri: https://example.org\n        filters:\n        - RewriteResponseHeader=X-Response-Red, , password=[^&]+, password=***\n")])])]),a("p",[e._v("For a header value of "),a("code",[e._v("/42?user=ford&password=omg!what&flag=true")]),e._v(", it is set to "),a("code",[e._v("/42?user=ford&password=***&flag=true")]),e._v(" after making the downstream request.\nYou must use "),a("code",[e._v("$\\")]),e._v(" to mean "),a("code",[e._v("$")]),e._v(" because of the YAML specification.")]),e._v(" "),a("h3",{attrs:{id:"_6-18-the-savesession-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-18-the-savesession-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.18. The "),a("code",[e._v("SaveSession")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("SaveSession")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory forces a "),a("code",[e._v("WebSession::save")]),e._v(" operation "),a("em",[e._v("before")]),e._v(" forwarding the call downstream.\nThis is of particular use when using something like "),a("a",{attrs:{href:"https://projects.spring.io/spring-session/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Session"),a("OutboundLink")],1),e._v(" with a lazy data store and you need to ensure the session state has been saved before making the forwarded call.\nThe following example configures a "),a("code",[e._v("SaveSession")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 43. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: save_session\n        uri: https://example.org\n        predicates:\n        - Path=/foo/**\n        filters:\n        - SaveSession\n")])])]),a("p",[e._v("If you integrate "),a("a",{attrs:{href:"https://projects.spring.io/spring-security/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Security"),a("OutboundLink")],1),e._v(" with Spring Session and want to ensure security details have been forwarded to the remote process, this is critical.")]),e._v(" "),a("h3",{attrs:{id:"_6-19-the-secureheaders-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-19-the-secureheaders-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.19. The "),a("code",[e._v("SecureHeaders")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("SecureHeaders")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory adds a number of headers to the response, per the recommendation made in "),a("a",{attrs:{href:"https://blog.appcanary.com/2017/http-security-headers.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("this blog post"),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("p",[e._v("The following headers (shown with their default values) are added:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("X-Xss-Protection:1 (mode=block")]),e._v(")")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Strict-Transport-Security (max-age=631138519")]),e._v(")")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("X-Frame-Options (DENY)")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("X-Content-Type-Options (nosniff)")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Referrer-Policy (no-referrer)")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Content-Security-Policy (default-src 'self' https:; font-src 'self' https: data:; img-src 'self' https: data:; object-src 'none'; script-src https:; style-src 'self' https: 'unsafe-inline)'")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("X-Download-Options (noopen)")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("X-Permitted-Cross-Domain-Policies (none)")])])])]),e._v(" "),a("p",[e._v("To change the default values, set the appropriate property in the "),a("code",[e._v("spring.cloud.gateway.filter.secure-headers")]),e._v(" namespace.\nThe following properties are available:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("xss-protection-header")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("strict-transport-security")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("x-frame-options")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("x-content-type-options")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("referrer-policy")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("content-security-policy")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("x-download-options")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("x-permitted-cross-domain-policies")])])])]),e._v(" "),a("p",[e._v("To disable the default values set the "),a("code",[e._v("spring.cloud.gateway.filter.secure-headers.disable")]),e._v(" property with comma-separated values.\nThe following example shows how to do so:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring.cloud.gateway.filter.secure-headers.disable=x-frame-options,strict-transport-security\n")])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The lowercase full name of the secure header needs to be used to disable it..")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_6-20-the-setpath-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-20-the-setpath-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.20. The "),a("code",[e._v("SetPath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("SetPath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a path "),a("code",[e._v("template")]),e._v(" parameter.\nIt offers a simple way to manipulate the request path by allowing templated segments of the path.\nThis uses the URI templates from Spring Framework.\nMultiple matching segments are allowed.\nThe following example configures a "),a("code",[e._v("SetPath")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 44. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: setpath_route\n        uri: https://example.org\n        predicates:\n        - Path=/red/{segment}\n        filters:\n        - SetPath=/{segment}\n")])])]),a("p",[e._v("For a request path of "),a("code",[e._v("/red/blue")]),e._v(", this sets the path to "),a("code",[e._v("/blue")]),e._v(" before making the downstream request.")]),e._v(" "),a("h3",{attrs:{id:"_6-21-the-setrequestheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-21-the-setrequestheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.21. The "),a("code",[e._v("SetRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("SetRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes "),a("code",[e._v("name")]),e._v(" and "),a("code",[e._v("value")]),e._v(" parameters.\nThe following listing configures a "),a("code",[e._v("SetRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 45. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: setrequestheader_route\n        uri: https://example.org\n        filters:\n        - SetRequestHeader=X-Request-Red, Blue\n")])])]),a("p",[e._v("This "),a("code",[e._v("GatewayFilter")]),e._v(" replaces (rather than adding) all headers with the given name.\nSo, if the downstream server responded with a "),a("code",[e._v("X-Request-Red:1234")]),e._v(", this would be replaced with "),a("code",[e._v("X-Request-Red:Blue")]),e._v(", which is what the downstream service would receive.")]),e._v(" "),a("p",[a("code",[e._v("SetRequestHeader")]),e._v(" is aware of URI variables used to match a path or host.\nURI variables may be used in the value and are expanded at runtime.\nThe following example configures an "),a("code",[e._v("SetRequestHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" that uses a variable:")]),e._v(" "),a("p",[e._v("Example 46. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: setrequestheader_route\n        uri: https://example.org\n        predicates:\n        - Host: {segment}.myhost.org\n        filters:\n        - SetRequestHeader=foo, bar-{segment}\n")])])]),a("h3",{attrs:{id:"_6-22-the-setresponseheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-22-the-setresponseheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.22. The "),a("code",[e._v("SetResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("SetResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes "),a("code",[e._v("name")]),e._v(" and "),a("code",[e._v("value")]),e._v(" parameters.\nThe following listing configures a "),a("code",[e._v("SetResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 47. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: setresponseheader_route\n        uri: https://example.org\n        filters:\n        - SetResponseHeader=X-Response-Red, Blue\n")])])]),a("p",[e._v("This GatewayFilter replaces (rather than adding) all headers with the given name.\nSo, if the downstream server responded with a "),a("code",[e._v("X-Response-Red:1234")]),e._v(", this is replaced with "),a("code",[e._v("X-Response-Red:Blue")]),e._v(", which is what the gateway client would receive.")]),e._v(" "),a("p",[a("code",[e._v("SetResponseHeader")]),e._v(" is aware of URI variables used to match a path or host.\nURI variables may be used in the value and will be expanded at runtime.\nThe following example configures an "),a("code",[e._v("SetResponseHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" that uses a variable:")]),e._v(" "),a("p",[e._v("Example 48. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: setresponseheader_route\n        uri: https://example.org\n        predicates:\n        - Host: {segment}.myhost.org\n        filters:\n        - SetResponseHeader=foo, bar-{segment}\n")])])]),a("h3",{attrs:{id:"_6-23-the-setstatus-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-23-the-setstatus-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.23. The "),a("code",[e._v("SetStatus")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("SetStatus")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes a single parameter, "),a("code",[e._v("status")]),e._v(".\nIt must be a valid Spring "),a("code",[e._v("HttpStatus")]),e._v(".\nIt may be the integer value "),a("code",[e._v("404")]),e._v(" or the string representation of the enumeration: "),a("code",[e._v("NOT_FOUND")]),e._v(".\nThe following listing configures a "),a("code",[e._v("SetStatus")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 49. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: setstatusstring_route\n        uri: https://example.org\n        filters:\n        - SetStatus=UNAUTHORIZED\n      - id: setstatusint_route\n        uri: https://example.org\n        filters:\n        - SetStatus=401\n")])])]),a("p",[e._v("In either case, the HTTP status of the response is set to 401.")]),e._v(" "),a("p",[e._v("You can configure the "),a("code",[e._v("SetStatus")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" to return the original HTTP status code from the proxied request in a header in the response.\nThe header is added to the response if configured with the following property:")]),e._v(" "),a("p",[e._v("Example 50. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      set-status:\n        original-status-header-name: original-http-status\n")])])]),a("h3",{attrs:{id:"_6-24-the-stripprefix-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-24-the-stripprefix-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.24. The "),a("code",[e._v("StripPrefix")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("StripPrefix")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory takes one parameter, "),a("code",[e._v("parts")]),e._v(".\nThe "),a("code",[e._v("parts")]),e._v(" parameter indicates the number of parts in the path to strip from the request before sending it downstream.\nThe following listing configures a "),a("code",[e._v("StripPrefix")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 51. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: nameRoot\n        uri: https://nameservice\n        predicates:\n        - Path=/name/**\n        filters:\n        - StripPrefix=2\n")])])]),a("p",[e._v("When a request is made through the gateway to "),a("code",[e._v("/name/blue/red")]),e._v(", the request made to "),a("code",[e._v("nameservice")]),e._v(" looks like "),a("code",[e._v("[nameservice/red](https://nameservice/red)")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_6-25-the-retry-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-25-the-retry-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.25. The Retry "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Retry")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory supports the following parameters:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("retries")]),e._v(": The number of retries that should be attempted.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("statuses")]),e._v(": The HTTP status codes that should be retried, represented by using "),a("code",[e._v("org.springframework.http.HttpStatus")]),e._v(".")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("methods")]),e._v(": The HTTP methods that should be retried, represented by using "),a("code",[e._v("org.springframework.http.HttpMethod")]),e._v(".")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("series")]),e._v(": The series of status codes to be retried, represented by using "),a("code",[e._v("org.springframework.http.HttpStatus.Series")]),e._v(".")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("exceptions")]),e._v(": A list of thrown exceptions that should be retried.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("backoff")]),e._v(": The configured exponential backoff for the retries.\nRetries are performed after a backoff interval of "),a("code",[e._v("firstBackoff * (factor ^ n)")]),e._v(", where "),a("code",[e._v("n")]),e._v(" is the iteration.\nIf "),a("code",[e._v("maxBackoff")]),e._v(" is configured, the maximum backoff applied is limited to "),a("code",[e._v("maxBackoff")]),e._v(".\nIf "),a("code",[e._v("basedOnPreviousValue")]),e._v(" is true, the backoff is calculated byusing "),a("code",[e._v("prevBackoff * factor")]),e._v(".")])])]),e._v(" "),a("p",[e._v("The following defaults are configured for "),a("code",[e._v("Retry")]),e._v(" filter, if enabled:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("retries")]),e._v(": Three times")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("series")]),e._v(": 5XX series")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("methods")]),e._v(": GET method")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("exceptions")]),e._v(": "),a("code",[e._v("IOException")]),e._v(" and "),a("code",[e._v("TimeoutException")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("backoff")]),e._v(": disabled")])])]),e._v(" "),a("p",[e._v("The following listing configures a Retry "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 52. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: retry_test\n        uri: http://localhost:8080/flakey\n        predicates:\n        - Host=*.retry.com\n        filters:\n        - name: Retry\n          args:\n            retries: 3\n            statuses: BAD_GATEWAY\n            methods: GET,POST\n            backoff:\n              firstBackoff: 10ms\n              maxBackoff: 50ms\n              factor: 2\n              basedOnPreviousValue: false\n")])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("When using the retry filter with a "),a("code",[e._v("forward:")]),e._v(" 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."),a("br"),e._v("For example, if the target endpoint is an annotated controller, the target controller method should not return "),a("code",[e._v("ResponseEntity")]),e._v(" with an error status code."),a("br"),e._v("Instead, it should throw an "),a("code",[e._v("Exception")]),e._v(" or signal an error (for example, through a "),a("code",[e._v("Mono.error(ex)")]),e._v(" return value), which the retry filter can be configured to handle by retrying.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("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 "),a("code",[e._v("ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR")]),e._v(". The type of the object is a "),a("code",[e._v("org.springframework.core.io.buffer.DataBuffer")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v('A simplified "shortcut" notation can be added with a single '),a("code",[e._v("status")]),e._v(" and "),a("code",[e._v("method")]),e._v(".")]),e._v(" "),a("p",[e._v("The following two examples are equivalent:")]),e._v(" "),a("p",[e._v("Example 53. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: retry_route\n        uri: https://example.org\n        filters:\n        - name: Retry\n          args:\n            retries: 3\n            statuses: INTERNAL_SERVER_ERROR\n            methods: GET\n            backoff:\n              firstBackoff: 10ms\n              maxBackoff: 50ms\n              factor: 2\n              basedOnPreviousValue: false\n\n      - id: retryshortcut_route\n        uri: https://example.org\n        filters:\n        - Retry=3,INTERNAL_SERVER_ERROR,GET,10ms,50ms,2,false\n")])])]),a("h3",{attrs:{id:"_6-26-the-requestsize-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-26-the-requestsize-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.26. The "),a("code",[e._v("RequestSize")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("When the request size is greater than the permissible limit, the "),a("code",[e._v("RequestSize")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory can restrict a request from reaching the downstream service.\nThe filter takes a "),a("code",[e._v("maxSize")]),e._v(" parameter.\nThe "),a("code",[e._v("maxSize")]),e._v(" is a "),a("code",[e._v("DataSize")]),e._v(" type, so values can be defined as a number followed by an optional "),a("code",[e._v("DataUnit")]),e._v(" suffix such as 'KB' or 'MB'. The default is 'B' for bytes.\nIt is the permissible size limit of the request defined in bytes.\nThe following listing configures a "),a("code",[e._v("RequestSize")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 54. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: request_size_route\n        uri: http://localhost:8080/upload\n        predicates:\n        - Path=/upload\n        filters:\n        - name: RequestSize\n          args:\n            maxSize: 5000000\n")])])]),a("p",[e._v("The "),a("code",[e._v("RequestSize")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory sets the response status as "),a("code",[e._v("413 Payload Too Large")]),e._v(" with an additional header "),a("code",[e._v("errorMessage")]),e._v(" when the request is rejected due to size. The following example shows such an "),a("code",[e._v("errorMessage")]),e._v(":")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("errorMessage : Request size is larger than permissible limit. Request size is 6.0 MB where permissible limit is 5.0 MB\n")])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The default request size is set to five MB if not provided as a filter argument in the route definition.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_6-27-the-setrequesthostheader-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-27-the-setrequesthostheader-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.27. The "),a("code",[e._v("SetRequestHostHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("There are certain situation when the host header may need to be overridden. In this situation, the "),a("code",[e._v("SetRequestHostHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory can replace the existing host header with a specified vaue.\nThe filter takes a "),a("code",[e._v("host")]),e._v(" parameter.\nThe following listing configures a "),a("code",[e._v("SetRequestHostHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 55. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: set_request_host_header_route\n        uri: http://localhost:8080/headers\n        predicates:\n        - Path=/headers\n        filters:\n        - name: SetRequestHostHeader\n          args:\n            host: example.org\n")])])]),a("p",[e._v("The "),a("code",[e._v("SetRequestHostHeader")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" factory replaces the value of the host header with "),a("code",[e._v("example.org")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_6-28-modify-a-request-body-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-28-modify-a-request-body-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.28. Modify a Request Body "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("ModifyRequestBody")]),e._v(" filter filter to modify the request body before it is sent downstream by the gateway.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("This filter can be configured only by using the Java DSL.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("The following listing shows how to modify a request body "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic RouteLocator routes(RouteLocatorBuilder builder) {\n    return builder.routes()\n        .route("rewrite_request_obj", r -> r.host("*.rewriterequestobj.org")\n            .filters(f -> f.prefixPath("/httpbin")\n                .modifyRequestBody(String.class, Hello.class, MediaType.APPLICATION_JSON_VALUE,\n                    (exchange, s) -> return Mono.just(new Hello(s.toUpperCase())))).uri(uri))\n        .build();\n}\n\nstatic class Hello {\n    String message;\n\n    public Hello() { }\n\n    public Hello(String message) {\n        this.message = message;\n    }\n\n    public String getMessage() {\n        return message;\n    }\n\n    public void setMessage(String message) {\n        this.message = message;\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("if the request has no body, the "),a("code",[e._v("RewriteFilter")]),e._v(" will be passed "),a("code",[e._v("null")]),e._v(". "),a("code",[e._v("Mono.empty()")]),e._v(" should be returned to assign a missing body in the request.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_6-29-modify-a-response-body-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-29-modify-a-response-body-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.29. Modify a Response Body "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("ModifyResponseBody")]),e._v(" filter to modify the response body before it is sent back to the client.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("This filter can be configured only by using the Java DSL.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("The following listing shows how to modify a response body "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic RouteLocator routes(RouteLocatorBuilder builder) {\n    return builder.routes()\n        .route("rewrite_response_upper", r -> r.host("*.rewriteresponseupper.org")\n            .filters(f -> f.prefixPath("/httpbin")\n                .modifyResponseBody(String.class, String.class,\n                    (exchange, s) -> Mono.just(s.toUpperCase()))).uri(uri))\n        .build();\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("if the response has no body, the "),a("code",[e._v("RewriteFilter")]),e._v(" will be passed "),a("code",[e._v("null")]),e._v(". "),a("code",[e._v("Mono.empty()")]),e._v(" should be returned to assign a missing body in the response.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_6-30-token-relay-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-30-token-relay-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.30. Token Relay "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("A Token Relay is where an OAuth2 consumer acts as a Client and\nforwards the incoming token to outgoing resource requests. The\nconsumer can be a pure Client (like an SSO application) or a Resource\nServer.")]),e._v(" "),a("p",[e._v("Spring Cloud Gateway can forward OAuth2 access tokens downstream to the services\nit is proxying. To add this functionlity to gateway you need to add the"),a("code",[e._v("TokenRelayGatewayFilterFactory")]),e._v(" like this:")]),e._v(" "),a("p",[e._v("App.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic RouteLocator customRouteLocator(RouteLocatorBuilder builder) {\n    return builder.routes()\n            .route("resource", r -> r.path("/resource")\n                    .filters(f -> f.tokenRelay())\n                    .uri("http://localhost:9000"))\n            .build();\n}\n')])])]),a("p",[e._v("or this")]),e._v(" "),a("p",[e._v("application.yaml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: resource\n        uri: http://localhost:9000\n        predicates:\n        - Path=/resource\n        filters:\n        - TokenRelay=\n")])])]),a("p",[e._v("and it will (in addition to logging the user in and grabbing a token)\npass the authentication token downstream to the services (in this case"),a("code",[e._v("/resource")]),e._v(").")]),e._v(" "),a("p",[e._v("To enable this for Spring Cloud Gateway add the following dependencies")]),e._v(" "),a("ul",[a("li",[a("code",[e._v("org.springframework.boot:spring-boot-starter-oauth2-client")])])]),e._v(" "),a("p",[e._v("How does it work? The\n{githubmaster}/src/main/java/org/springframework/cloud/gateway/security/TokenRelayGatewayFilterFactory.java[filter]\nextracts an access token from the currently authenticated user,\nand puts it in a request header for the downstream requests.")]),e._v(" "),a("p",[e._v("For a full working sample see "),a("a",{attrs:{href:"https://github.com/spring-cloud-samples/sample-gateway-oauth2login",target:"_blank",rel:"noopener noreferrer"}},[e._v("this project"),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("A "),a("code",[e._v("TokenRelayGatewayFilterFactory")]),e._v(" bean will only be created if the proper "),a("code",[e._v("spring.security.oauth2.client.*")]),e._v(" properties are set which will trigger creation of a "),a("code",[e._v("ReactiveClientRegistrationRepository")]),e._v(" bean.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The default implementation of "),a("code",[e._v("ReactiveOAuth2AuthorizedClientService")]),e._v(" used by "),a("code",[e._v("TokenRelayGatewayFilterFactory")]),e._v("uses an in-memory data store. You will need to provide your own implementation "),a("code",[e._v("ReactiveOAuth2AuthorizedClientService")]),e._v("if you need a more robust solution.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_6-31-the-cacherequestbody-gatewayfilter-factory"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-31-the-cacherequestbody-gatewayfilter-factory"}},[e._v("#")]),e._v(" 6.31. The "),a("code",[e._v("CacheRequestBody")]),e._v(" "),a("code",[e._v("GatewayFilter")]),e._v(" Factory")]),e._v(" "),a("p",[e._v("There are certain situation need to read body.Since the request body stream can only be read once, we need to cache the request body.\nYou can use the "),a("code",[e._v("CacheRequestBody")]),e._v(" filter to cache request body before it send to the downstream and get body from exchagne attribute.")]),e._v(" "),a("p",[e._v("The following listing shows how to cache the request body "),a("code",[e._v("GatewayFilter")]),e._v(":")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic RouteLocator routes(RouteLocatorBuilder builder) {\n    return builder.routes()\n        .route("cache_request_body_route", r -> r.path("/downstream/**")\n            .filters(f -> f.prefixPath("/httpbin")\n                .cacheRequestBody(String.class).uri(uri))\n        .build();\n}\n')])])]),a("p",[e._v("Example 56. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: cache_request_body_route\n        uri: lb://downstream\n        predicates:\n        - Path=/downstream/**\n        filters:\n        - name: CacheRequestBody\n          args:\n            bodyClass: java.lang.String\n")])])]),a("p",[a("code",[e._v("CacheRequestBody")]),e._v(" will extract request body and conver it to body class (such as "),a("code",[e._v("java.lang.String")]),e._v(", defined in the preceding example). then places it in the "),a("code",[e._v("ServerWebExchange.getAttributes()")]),e._v(" with a key defined in "),a("code",[e._v("ServerWebExchangeUtils.CACHED_REQUEST_BODY_ATTR")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("This filter only works with http request (including https).")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_6-32-default-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-32-default-filters"}},[e._v("#")]),e._v(" 6.32. Default Filters")]),e._v(" "),a("p",[e._v("To add a filter and apply it to all routes, you can use "),a("code",[e._v("spring.cloud.gateway.default-filters")]),e._v(".\nThis property takes a list of filters.\nThe following listing defines a set of default filters:")]),e._v(" "),a("p",[e._v("Example 57. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      default-filters:\n      - AddResponseHeader=X-Response-Default-Red, Default-Blue\n      - PrefixPath=/httpbin\n")])])]),a("h2",{attrs:{id:"_7-global-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-global-filters"}},[e._v("#")]),e._v(" 7. Global Filters")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("GlobalFilter")]),e._v(" interface has the same signature as "),a("code",[e._v("GatewayFilter")]),e._v(".\nThese are special filters that are conditionally applied to all routes.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("This interface and its usage are subject to change in future milestone releases.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_7-1-combined-global-filter-and-gatewayfilter-ordering"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-1-combined-global-filter-and-gatewayfilter-ordering"}},[e._v("#")]),e._v(" 7.1. Combined Global Filter and "),a("code",[e._v("GatewayFilter")]),e._v(" Ordering")]),e._v(" "),a("p",[e._v("When a request matches a route, the filtering web handler adds all instances of "),a("code",[e._v("GlobalFilter")]),e._v(" and all route-specific instances of "),a("code",[e._v("GatewayFilter")]),e._v(" to a filter chain.\nThis combined filter chain is sorted by the "),a("code",[e._v("org.springframework.core.Ordered")]),e._v(" interface, which you can set by implementing the "),a("code",[e._v("getOrder()")]),e._v(" method.")]),e._v(" "),a("p",[e._v("As Spring Cloud Gateway distinguishes between “pre” and “post” phases for filter logic execution (see "),a("a",{attrs:{href:"#gateway-how-it-works"}},[e._v("How it Works")]),e._v("), the filter with the highest precedence is the first in the “pre”-phase and the last in the “post”-phase.")]),e._v(" "),a("p",[e._v("The following listing configures a filter chain:")]),e._v(" "),a("p",[e._v("Example 58. ExampleConfiguration.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic GlobalFilter customFilter() {\n    return new CustomGlobalFilter();\n}\n\npublic class CustomGlobalFilter implements GlobalFilter, Ordered {\n\n    @Override\n    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {\n        log.info("custom global filter");\n        return chain.filter(exchange);\n    }\n\n    @Override\n    public int getOrder() {\n        return -1;\n    }\n}\n')])])]),a("h3",{attrs:{id:"_7-2-forward-routing-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-2-forward-routing-filter"}},[e._v("#")]),e._v(" 7.2. Forward Routing Filter")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("ForwardRoutingFilter")]),e._v(" looks for a URI in the exchange attribute "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR")]),e._v(".\nIf the URL has a "),a("code",[e._v("forward")]),e._v(" scheme (such as "),a("code",[e._v("forward:///localendpoint")]),e._v("), it uses the Spring "),a("code",[e._v("DispatcherHandler")]),e._v(" to handle the request.\nThe path part of the request URL is overridden with the path in the forward URL.\nThe unmodified original URL is appended to the list in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR")]),e._v(" attribute.")]),e._v(" "),a("h3",{attrs:{id:"_7-3-the-reactiveloadbalancerclientfilter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-3-the-reactiveloadbalancerclientfilter"}},[e._v("#")]),e._v(" 7.3. The "),a("code",[e._v("ReactiveLoadBalancerClientFilter")])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("ReactiveLoadBalancerClientFilter")]),e._v(" looks for a URI in the exchange attribute named "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR")]),e._v(".\nIf the URL has a "),a("code",[e._v("lb")]),e._v(" scheme (such as "),a("code",[e._v("lb://myservice")]),e._v("), it uses the Spring Cloud "),a("code",[e._v("ReactorLoadBalancer")]),e._v(" to resolve the name ("),a("code",[e._v("myservice")]),e._v(" in this example) to an actual host and port and replaces the URI in the same attribute.\nThe unmodified original URL is appended to the list in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR")]),e._v(" attribute.\nThe filter also looks in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR")]),e._v(" attribute to see if it equals "),a("code",[e._v("lb")]),e._v(".\nIf so, the same rules apply.\nThe following listing configures a "),a("code",[e._v("ReactiveLoadBalancerClientFilter")]),e._v(":")]),e._v(" "),a("p",[e._v("Example 59. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: myRoute\n        uri: lb://service\n        predicates:\n        - Path=/service/**\n")])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("By default, when a service instance cannot be found by the "),a("code",[e._v("ReactorLoadBalancer")]),e._v(", a "),a("code",[e._v("503")]),e._v(" is returned."),a("br"),e._v("You can configure the gateway to return a "),a("code",[e._v("404")]),e._v(" by setting "),a("code",[e._v("spring.cloud.gateway.loadbalancer.use404=true")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The "),a("code",[e._v("isSecure")]),e._v(" value of the "),a("code",[e._v("ServiceInstance")]),e._v(" returned from the "),a("code",[e._v("ReactiveLoadBalancerClientFilter")]),e._v(" overrides"),a("br"),e._v("the scheme specified in the request made to the Gateway."),a("br"),e._v("For example, if the request comes into the Gateway over "),a("code",[e._v("HTTPS")]),e._v(" but the "),a("code",[e._v("ServiceInstance")]),e._v(" indicates it is not secure, the downstream request is made over "),a("code",[e._v("HTTP")]),e._v("."),a("br"),e._v("The opposite situation can also apply."),a("br"),e._v("However, if "),a("code",[e._v("GATEWAY_SCHEME_PREFIX_ATTR")]),e._v(" is specified for the route in the Gateway configuration, the prefix is stripped and the resulting scheme from the route URL overrides the "),a("code",[e._v("ServiceInstance")]),e._v(" configuration.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Gateway supports all the LoadBalancer features. You can read more about them in the "),a("a",{attrs:{href:"https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Cloud Commons documentation"),a("OutboundLink")],1),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_7-4-the-netty-routing-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-4-the-netty-routing-filter"}},[e._v("#")]),e._v(" 7.4. The Netty Routing Filter")]),e._v(" "),a("p",[e._v("The Netty routing filter runs if the URL located in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR")]),e._v(" exchange attribute has a "),a("code",[e._v("http")]),e._v(" or "),a("code",[e._v("https")]),e._v(" scheme.\nIt uses the Netty "),a("code",[e._v("HttpClient")]),e._v(" to make the downstream proxy request.\nThe response is put in the "),a("code",[e._v("ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR")]),e._v(" exchange attribute for use in a later filter.\n(There is also an experimental "),a("code",[e._v("WebClientHttpRoutingFilter")]),e._v(" that performs the same function but does not require Netty.)")]),e._v(" "),a("h3",{attrs:{id:"_7-5-the-netty-write-response-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-5-the-netty-write-response-filter"}},[e._v("#")]),e._v(" 7.5. The Netty Write Response Filter")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("NettyWriteResponseFilter")]),e._v(" runs if there is a Netty "),a("code",[e._v("HttpClientResponse")]),e._v(" in the "),a("code",[e._v("ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR")]),e._v(" exchange attribute.\nIt runs after all other filters have completed and writes the proxy response back to the gateway client response.\n(There is also an experimental "),a("code",[e._v("WebClientWriteResponseFilter")]),e._v(" that performs the same function but does not require Netty.)")]),e._v(" "),a("h3",{attrs:{id:"_7-6-the-routetorequesturl-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-6-the-routetorequesturl-filter"}},[e._v("#")]),e._v(" 7.6. The "),a("code",[e._v("RouteToRequestUrl")]),e._v(" Filter")]),e._v(" "),a("p",[e._v("If there is a "),a("code",[e._v("Route")]),e._v(" object in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR")]),e._v(" exchange attribute, the "),a("code",[e._v("RouteToRequestUrlFilter")]),e._v(" runs.\nIt creates a new URI, based off of the request URI but updated with the URI attribute of the "),a("code",[e._v("Route")]),e._v(" object.\nThe new URI is placed in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR")]),e._v(" exchange attribute.")]),e._v(" "),a("p",[e._v("If the URI has a scheme prefix, such as "),a("code",[e._v("lb:ws://serviceid")]),e._v(", the "),a("code",[e._v("lb")]),e._v(" scheme is stripped from the URI and placed in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR")]),e._v(" for use later in the filter chain.")]),e._v(" "),a("h3",{attrs:{id:"_7-7-the-websocket-routing-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-7-the-websocket-routing-filter"}},[e._v("#")]),e._v(" 7.7. The Websocket Routing Filter")]),e._v(" "),a("p",[e._v("If the URL located in the "),a("code",[e._v("ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR")]),e._v(" exchange attribute has a "),a("code",[e._v("ws")]),e._v(" or "),a("code",[e._v("wss")]),e._v(" scheme, the websocket routing filter runs. It uses the Spring WebSocket infrastructure to forward the websocket request downstream.")]),e._v(" "),a("p",[e._v("You can load-balance websockets by prefixing the URI with "),a("code",[e._v("lb")]),e._v(", such as "),a("code",[e._v("lb:ws://serviceid")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("If you use "),a("a",{attrs:{href:"https://github.com/sockjs",target:"_blank",rel:"noopener noreferrer"}},[e._v("SockJS"),a("OutboundLink")],1),e._v(" as a fallback over normal HTTP, you should configure a normal HTTP route as well as the websocket Route.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("The following listing configures a websocket routing filter:")]),e._v(" "),a("p",[e._v("Example 60. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      # SockJS route\n      - id: websocket_sockjs_route\n        uri: http://localhost:3001\n        predicates:\n        - Path=/websocket/info/**\n      # Normal Websocket route\n      - id: websocket_route\n        uri: ws://localhost:3001\n        predicates:\n        - Path=/websocket/**\n")])])]),a("h3",{attrs:{id:"_7-8-the-gateway-metrics-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-8-the-gateway-metrics-filter"}},[e._v("#")]),e._v(" 7.8. The Gateway Metrics Filter")]),e._v(" "),a("p",[e._v("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 "),a("code",[e._v("spring.cloud.gateway.metrics.enabled")]),e._v(" is not set to "),a("code",[e._v("false")]),e._v(". This filter adds a timer metric named "),a("code",[e._v("spring.cloud.gateway.requests")]),e._v(" with the following tags:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("routeId")]),e._v(": The route ID.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("routeUri")]),e._v(": The URI to which the API is routed.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("outcome")]),e._v(": The outcome, as classified by "),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/HttpStatus.Series.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("HttpStatus.Series"),a("OutboundLink")],1),e._v(".")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("status")]),e._v(": The HTTP status of the request returned to the client.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("httpStatusCode")]),e._v(": The HTTP Status of the request returned to the client.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("httpMethod")]),e._v(": The HTTP method used for the request.")])])]),e._v(" "),a("p",[e._v("In addition, through the property "),a("code",[e._v("spring.cloud.gateway.metrics.tags.path.enabled")]),e._v(" (by default, set to false), you can activate an extra metric with the tag:")]),e._v(" "),a("ul",[a("li",[a("code",[e._v("path")]),e._v(": Path of the request.")])]),e._v(" "),a("p",[e._v("These metrics are then available to be scraped from "),a("code",[e._v("/actuator/metrics/spring.cloud.gateway.requests")]),e._v(" and can be easily integrated with Prometheus to create a "),a("a",{attrs:{href:"images/gateway-grafana-dashboard.jpeg"}},[e._v("Grafana")]),e._v(" "),a("a",{attrs:{href:"gateway-grafana-dashboard.json"}},[e._v("dashboard")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("To enable the prometheus endpoint, add "),a("code",[e._v("micrometer-registry-prometheus")]),e._v(" as a project dependency.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_7-9-marking-an-exchange-as-routed"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_7-9-marking-an-exchange-as-routed"}},[e._v("#")]),e._v(" 7.9. Marking An Exchange As Routed")]),e._v(" "),a("p",[e._v("After the gateway has routed a "),a("code",[e._v("ServerWebExchange")]),e._v(", it marks that exchange as “routed” by adding "),a("code",[e._v("gatewayAlreadyRouted")]),e._v("to the exchange attributes. Once a request has been marked as routed, other routing filters will not route the request again,\nessentially skipping the filter. There are convenience methods that you can use to mark an exchange as routed\nor check if an exchange has already been routed.")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("ServerWebExchangeUtils.isAlreadyRouted")]),e._v(" takes a "),a("code",[e._v("ServerWebExchange")]),e._v(" object and checks if it has been “routed”.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("ServerWebExchangeUtils.setAlreadyRouted")]),e._v(" takes a "),a("code",[e._v("ServerWebExchange")]),e._v(" object and marks it as “routed”.")])])]),e._v(" "),a("h2",{attrs:{id:"_8-httpheadersfilters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_8-httpheadersfilters"}},[e._v("#")]),e._v(" 8. HttpHeadersFilters")]),e._v(" "),a("p",[e._v("HttpHeadersFilters are applied to requests before sending them downstream, such as in the "),a("code",[e._v("NettyRoutingFilter")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_8-1-forwarded-headers-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_8-1-forwarded-headers-filter"}},[e._v("#")]),e._v(" 8.1. Forwarded Headers Filter")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Forwarded")]),e._v(" Headers Filter creates a "),a("code",[e._v("Forwarded")]),e._v(" header to send to the downstream service. It adds the "),a("code",[e._v("Host")]),e._v(" header, scheme and port of the current request to any existing "),a("code",[e._v("Forwarded")]),e._v(" header.")]),e._v(" "),a("h3",{attrs:{id:"_8-2-removehopbyhop-headers-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_8-2-removehopbyhop-headers-filter"}},[e._v("#")]),e._v(" 8.2. RemoveHopByHop Headers Filter")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RemoveHopByHop")]),e._v(" Headers Filter removes headers from forwarded requests. The default list of headers that is removed comes from the "),a("a",{attrs:{href:"https://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-14#section-7.1.3",target:"_blank",rel:"noopener noreferrer"}},[e._v("IETF"),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("p",[e._v("The default removed headers are:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("Connection")])]),e._v(" "),a("li",[a("p",[e._v("Keep-Alive")])]),e._v(" "),a("li",[a("p",[e._v("Proxy-Authenticate")])]),e._v(" "),a("li",[a("p",[e._v("Proxy-Authorization")])]),e._v(" "),a("li",[a("p",[e._v("TE")])]),e._v(" "),a("li",[a("p",[e._v("Trailer")])]),e._v(" "),a("li",[a("p",[e._v("Transfer-Encoding")])]),e._v(" "),a("li",[a("p",[e._v("Upgrade")])])]),e._v(" "),a("p",[e._v("To change this, set the "),a("code",[e._v("spring.cloud.gateway.filter.remove-hop-by-hop.headers")]),e._v(" property to the list of header names to remove.")]),e._v(" "),a("h3",{attrs:{id:"_8-3-xforwarded-headers-filter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_8-3-xforwarded-headers-filter"}},[e._v("#")]),e._v(" 8.3. XForwarded Headers Filter")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("XForwarded")]),e._v(" Headers Filter creates various a "),a("code",[e._v("X-Forwarded-*")]),e._v(" headers to send to the downstream service. It users the "),a("code",[e._v("Host")]),e._v(" header, scheme, port and path of the current request to create the various headers.")]),e._v(" "),a("p",[e._v("Creating of individual headers can be controlled by the following boolean properties (defaults to true):")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.for-enabled")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.host-enabled")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.port-enabled")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.proto-enabled")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.prefix-enabled")])])])]),e._v(" "),a("p",[e._v("Appending multiple headers can be controlled by the following boolean properties (defaults to true):")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.for-append")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.host-append")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.port-append")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.proto-append")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("spring.cloud.gateway.x-forwarded.prefix-append")])])])]),e._v(" "),a("h2",{attrs:{id:"_9-tls-and-ssl"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_9-tls-and-ssl"}},[e._v("#")]),e._v(" 9. TLS and SSL")]),e._v(" "),a("p",[e._v("The gateway can listen for requests on HTTPS by following the usual Spring server configuration.\nThe following example shows how to do so:")]),e._v(" "),a("p",[e._v("Example 61. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("server:\n  ssl:\n    enabled: true\n    key-alias: scg\n    key-store-password: scg1234\n    key-store: classpath:scg-keystore.p12\n    key-store-type: PKCS12\n")])])]),a("p",[e._v("You can route gateway routes to both HTTP and HTTPS backends.\nIf you are routing to an HTTPS backend, you can configure the gateway to trust all downstream certificates with the following configuration:")]),e._v(" "),a("p",[e._v("Example 62. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      httpclient:\n        ssl:\n          useInsecureTrustManager: true\n")])])]),a("p",[e._v("Using an insecure trust manager is not suitable for production.\nFor a production deployment, you can configure the gateway with a set of known certificates that it can trust with the following configuration:")]),e._v(" "),a("p",[e._v("Example 63. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      httpclient:\n        ssl:\n          trustedX509Certificates:\n          - cert1.pem\n          - cert2.pem\n")])])]),a("p",[e._v("If the Spring Cloud Gateway is not provisioned with trusted certificates, the default trust store is used (which you can override by setting the "),a("code",[e._v("javax.net.ssl.trustStore")]),e._v(" system property).")]),e._v(" "),a("h3",{attrs:{id:"_9-1-tls-handshake"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_9-1-tls-handshake"}},[e._v("#")]),e._v(" 9.1. TLS Handshake")]),e._v(" "),a("p",[e._v("The gateway maintains a client pool that it uses to route to backends.\nWhen communicating over HTTPS, the client initiates a TLS handshake.\nA number of timeouts are associated with this handshake.\nYou can configure these timeouts can be configured (defaults shown) as follows:")]),e._v(" "),a("p",[e._v("Example 64. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      httpclient:\n        ssl:\n          handshake-timeout-millis: 10000\n          close-notify-flush-timeout-millis: 3000\n          close-notify-read-timeout-millis: 0\n")])])]),a("h2",{attrs:{id:"_10-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_10-configuration"}},[e._v("#")]),e._v(" 10. Configuration")]),e._v(" "),a("p",[e._v("Configuration for Spring Cloud Gateway is driven by a collection of "),a("code",[e._v("RouteDefinitionLocator")]),e._v(" instances.\nThe following listing shows the definition of the "),a("code",[e._v("RouteDefinitionLocator")]),e._v(" interface:")]),e._v(" "),a("p",[e._v("Example 65. RouteDefinitionLocator.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("public interface RouteDefinitionLocator {\n    Flux<RouteDefinition> getRouteDefinitions();\n}\n")])])]),a("p",[e._v("By default, a "),a("code",[e._v("PropertiesRouteDefinitionLocator")]),e._v(" loads properties by using Spring Boot’s "),a("code",[e._v("@ConfigurationProperties")]),e._v(" mechanism.")]),e._v(" "),a("p",[e._v("The earlier configuration examples all use a shortcut notation that uses positional arguments rather than named ones.\nThe following two examples are equivalent:")]),e._v(" "),a("p",[e._v("Example 66. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      routes:\n      - id: setstatus_route\n        uri: https://example.org\n        filters:\n        - name: SetStatus\n          args:\n            status: 401\n      - id: setstatusshortcut_route\n        uri: https://example.org\n        filters:\n        - SetStatus=401\n")])])]),a("p",[e._v("For some usages of the gateway, properties are adequate, but some production use cases benefit from loading configuration from an external source, such as a database. Future milestone versions will have "),a("code",[e._v("RouteDefinitionLocator")]),e._v(" implementations based off of Spring Data Repositories, such as Redis, MongoDB, and Cassandra.")]),e._v(" "),a("h3",{attrs:{id:"_10-1-routedefinition-metrics"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_10-1-routedefinition-metrics"}},[e._v("#")]),e._v(" 10.1. RouteDefinition Metrics")]),e._v(" "),a("p",[e._v("To enable "),a("code",[e._v("RouteDefinition")]),e._v(" metrics, add spring-boot-starter-actuator as a project dependency. Then, by default, the metrics will be available as long as the property "),a("code",[e._v("spring.cloud.gateway.metrics.enabled")]),e._v(" is set to "),a("code",[e._v("true")]),e._v(". A gauge metric named "),a("code",[e._v("spring.cloud.gateway.routes.count")]),e._v(" will be added, whose value is the number of "),a("code",[e._v("RouteDefinitions")]),e._v(". This metric will be available from "),a("code",[e._v("/actuator/metrics/spring.cloud.gateway.routes.count")]),e._v(".")]),e._v(" "),a("h2",{attrs:{id:"_11-route-metadata-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_11-route-metadata-configuration"}},[e._v("#")]),e._v(" 11. Route Metadata Configuration")]),e._v(" "),a("p",[e._v("You can configure additional parameters for each route by using metadata, as follows:")]),e._v(" "),a("p",[e._v("Example 67. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('spring:\n  cloud:\n    gateway:\n      routes:\n      - id: route_with_metadata\n        uri: https://example.org\n        metadata:\n          optionName: "OptionValue"\n          compositeObject:\n            name: "value"\n          iAmNumber: 1\n')])])]),a("p",[e._v("You could acquire all metadata properties from an exchange, as follows:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Route route = exchange.getAttribute(GATEWAY_ROUTE_ATTR);\n// get all metadata properties\nroute.getMetadata();\n// get a single metadata property\nroute.getMetadata(someKey);\n")])])]),a("h2",{attrs:{id:"_12-http-timeouts-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_12-http-timeouts-configuration"}},[e._v("#")]),e._v(" 12. Http timeouts configuration")]),e._v(" "),a("p",[e._v("Http timeouts (response and connect) can be configured for all routes and overridden for each specific route.")]),e._v(" "),a("h3",{attrs:{id:"_12-1-global-timeouts"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_12-1-global-timeouts"}},[e._v("#")]),e._v(" 12.1. Global timeouts")]),e._v(" "),a("p",[e._v("To configure Global http timeouts:"),a("br"),e._v(" "),a("code",[e._v("connect-timeout")]),e._v(" must be specified in milliseconds."),a("br"),e._v(" "),a("code",[e._v("response-timeout")]),e._v(" must be specified as a java.time.Duration")]),e._v(" "),a("p",[e._v("global http timeouts example")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      httpclient:\n        connect-timeout: 1000\n        response-timeout: 5s\n")])])]),a("h3",{attrs:{id:"_12-2-per-route-timeouts"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_12-2-per-route-timeouts"}},[e._v("#")]),e._v(" 12.2. Per-route timeouts")]),e._v(" "),a("p",[e._v("To configure per-route timeouts:"),a("br"),e._v(" "),a("code",[e._v("connect-timeout")]),e._v(" must be specified in milliseconds."),a("br"),e._v(" "),a("code",[e._v("response-timeout")]),e._v(" must be specified in milliseconds.")]),e._v(" "),a("p",[e._v("per-route http timeouts configuration via configuration")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("      - id: per_route_timeouts\n        uri: https://example.org\n        predicates:\n          - name: Path\n            args:\n              pattern: /delay/{timeout}\n        metadata:\n          response-timeout: 200\n          connect-timeout: 200\n")])])]),a("p",[e._v("per-route timeouts configuration using Java DSL")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.cloud.gateway.support.RouteMetadataUtils.CONNECT_TIMEOUT_ATTR;\nimport static org.springframework.cloud.gateway.support.RouteMetadataUtils.RESPONSE_TIMEOUT_ATTR;\n\n      @Bean\n      public RouteLocator customRouteLocator(RouteLocatorBuilder routeBuilder){\n         return routeBuilder.routes()\n               .route("test1", r -> {\n                  return r.host("*.somehost.org").and().path("/somepath")\n                        .filters(f -> f.addRequestHeader("header1", "header-value-1"))\n                        .uri("http://someuri")\n                        .metadata(RESPONSE_TIMEOUT_ATTR, 200)\n                        .metadata(CONNECT_TIMEOUT_ATTR, 200);\n               })\n               .build();\n      }\n')])])]),a("p",[e._v("A per-route "),a("code",[e._v("response-timeout")]),e._v(" with a negative value will disable the global "),a("code",[e._v("response-timeout")]),e._v(" value.")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("      - id: per_route_timeouts\n        uri: https://example.org\n        predicates:\n          - name: Path\n            args:\n              pattern: /delay/{timeout}\n        metadata:\n          response-timeout: -1\n")])])]),a("h3",{attrs:{id:"_12-3-fluent-java-routes-api"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_12-3-fluent-java-routes-api"}},[e._v("#")]),e._v(" 12.3. Fluent Java Routes API")]),e._v(" "),a("p",[e._v("To allow for simple configuration in Java, the "),a("code",[e._v("RouteLocatorBuilder")]),e._v(" bean includes a fluent API.\nThe following listing shows how it works:")]),e._v(" "),a("p",[e._v("Example 68. GatewaySampleApplication.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// static imports from GatewayFilters and RoutePredicates\n@Bean\npublic RouteLocator customRouteLocator(RouteLocatorBuilder builder, ThrottleGatewayFilterFactory throttle) {\n    return builder.routes()\n            .route(r -> r.host("**.abc.org").and().path("/image/png")\n                .filters(f ->\n                        f.addResponseHeader("X-TestHeader", "foobar"))\n                .uri("http://httpbin.org:80")\n            )\n            .route(r -> r.path("/image/webp")\n                .filters(f ->\n                        f.addResponseHeader("X-AnotherHeader", "baz"))\n                .uri("http://httpbin.org:80")\n                .metadata("key", "value")\n            )\n            .route(r -> r.order(-1)\n                .host("**.throttle.org").and().path("/get")\n                .filters(f -> f.filter(throttle.apply(1,\n                        1,\n                        10,\n                        TimeUnit.SECONDS)))\n                .uri("http://httpbin.org:80")\n                .metadata("key", "value")\n            )\n            .build();\n}\n')])])]),a("p",[e._v("This style also allows for more custom predicate assertions.\nThe predicates defined by "),a("code",[e._v("RouteDefinitionLocator")]),e._v(" beans are combined using logical "),a("code",[e._v("and")]),e._v(".\nBy using the fluent Java API, you can use the "),a("code",[e._v("and()")]),e._v(", "),a("code",[e._v("or()")]),e._v(", and "),a("code",[e._v("negate()")]),e._v(" operators on the "),a("code",[e._v("Predicate")]),e._v(" class.")]),e._v(" "),a("h3",{attrs:{id:"_12-4-the-discoveryclient-route-definition-locator"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_12-4-the-discoveryclient-route-definition-locator"}},[e._v("#")]),e._v(" 12.4. The "),a("code",[e._v("DiscoveryClient")]),e._v(" Route Definition Locator")]),e._v(" "),a("p",[e._v("You can configure the gateway to create routes based on services registered with a "),a("code",[e._v("DiscoveryClient")]),e._v(" compatible service registry.")]),e._v(" "),a("p",[e._v("To enable this, set "),a("code",[e._v("spring.cloud.gateway.discovery.locator.enabled=true")]),e._v(" and make sure a "),a("code",[e._v("DiscoveryClient")]),e._v(" implementation (such as Netflix Eureka, Consul, or Zookeeper) is on the classpath and enabled.")]),e._v(" "),a("h4",{attrs:{id:"_12-4-1-configuring-predicates-and-filters-for-discoveryclient-routes"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_12-4-1-configuring-predicates-and-filters-for-discoveryclient-routes"}},[e._v("#")]),e._v(" 12.4.1. Configuring Predicates and Filters For "),a("code",[e._v("DiscoveryClient")]),e._v(" Routes")]),e._v(" "),a("p",[e._v("By default, the gateway defines a single predicate and filter for routes created with a "),a("code",[e._v("DiscoveryClient")]),e._v(".")]),e._v(" "),a("p",[e._v("The default predicate is a path predicate defined with the pattern "),a("code",[e._v("/serviceId/**")]),e._v(", where "),a("code",[e._v("serviceId")]),e._v(" is\nthe ID of the service from the "),a("code",[e._v("DiscoveryClient")]),e._v(".")]),e._v(" "),a("p",[e._v("The default filter is a rewrite path filter with the regex "),a("code",[e._v("/serviceId/?(?<remaining>.*)")]),e._v(" and the replacement "),a("code",[e._v("/${remaining}")]),e._v(".\nThis strips the service ID from the path before the request is sent downstream.")]),e._v(" "),a("p",[e._v("If you want to customize the predicates or filters used by the "),a("code",[e._v("DiscoveryClient")]),e._v(" routes, set "),a("code",[e._v("spring.cloud.gateway.discovery.locator.predicates[x]")]),e._v(" and "),a("code",[e._v("spring.cloud.gateway.discovery.locator.filters[y]")]),e._v(".\nWhen doing so, you need to make sure to include the default predicate and filter shown earlier, if you want to retain that functionality.\nThe following example shows what this looks like:")]),e._v(" "),a("p",[e._v("Example 69. application.properties")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring.cloud.gateway.discovery.locator.predicates[0].name: Path\nspring.cloud.gateway.discovery.locator.predicates[0].args[pattern]: \"'/'+serviceId+'/**'\"\nspring.cloud.gateway.discovery.locator.predicates[1].name: Host\nspring.cloud.gateway.discovery.locator.predicates[1].args[pattern]: \"'**.foo.com'\"\nspring.cloud.gateway.discovery.locator.filters[0].name: CircuitBreaker\nspring.cloud.gateway.discovery.locator.filters[0].args[name]: serviceId\nspring.cloud.gateway.discovery.locator.filters[1].name: RewritePath\nspring.cloud.gateway.discovery.locator.filters[1].args[regexp]: \"'/' + serviceId + '/?(?<remaining>.*)'\"\nspring.cloud.gateway.discovery.locator.filters[1].args[replacement]: \"'/${remaining}'\"\n")])])]),a("h2",{attrs:{id:"_13-reactor-netty-access-logs"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_13-reactor-netty-access-logs"}},[e._v("#")]),e._v(" 13. Reactor Netty Access Logs")]),e._v(" "),a("p",[e._v("To enable Reactor Netty access logs, set "),a("code",[e._v("-Dreactor.netty.http.server.accessLogEnabled=true")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("It must be a Java System Property, not a Spring Boot property.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("You can configure the logging system to have a separate access log file. The following example creates a Logback configuration:")]),e._v(" "),a("p",[e._v("Example 70. logback.xml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('    <appender name="accessLog" class="ch.qos.logback.core.FileAppender">\n        <file>access_log.log</file>\n        <encoder>\n            <pattern>%msg%n</pattern>\n        </encoder>\n    </appender>\n    <appender name="async" class="ch.qos.logback.classic.AsyncAppender">\n        <appender-ref ref="accessLog" />\n    </appender>\n\n    <logger name="reactor.netty.http.server.AccessLog" level="INFO" additivity="false">\n        <appender-ref ref="async"/>\n    </logger>\n')])])]),a("h2",{attrs:{id:"_14-cors-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_14-cors-configuration"}},[e._v("#")]),e._v(" 14. CORS Configuration")]),e._v(" "),a("p",[e._v("You can configure the gateway to control CORS behavior. The “global” CORS configuration is a map of URL patterns to "),a("a",{attrs:{href:"https://docs.spring.io/spring/docs/5.0.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Framework "),a("code",[e._v("CorsConfiguration")]),a("OutboundLink")],1),e._v(".\nThe following example configures CORS:")]),e._v(" "),a("p",[e._v("Example 71. application.yml")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring:\n  cloud:\n    gateway:\n      globalcors:\n        cors-configurations:\n          '[/**]':\n            allowedOrigins: \"https://docs.spring.io\"\n            allowedMethods:\n            - GET\n")])])]),a("p",[e._v("In the preceding example, CORS requests are allowed from requests that originate from "),a("code",[e._v("docs.spring.io")]),e._v(" for all GET requested paths.")]),e._v(" "),a("p",[e._v("To provide the same CORS configuration to requests that are not handled by some gateway route predicate, set the "),a("code",[e._v("spring.cloud.gateway.globalcors.add-to-simple-url-handler-mapping")]),e._v(" property to "),a("code",[e._v("true")]),e._v(".\nThis is useful when you try to support CORS preflight requests and your route predicate does not evalute to "),a("code",[e._v("true")]),e._v(" because the HTTP method is "),a("code",[e._v("options")]),e._v(".")]),e._v(" "),a("h2",{attrs:{id:"_15-actuator-api"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-actuator-api"}},[e._v("#")]),e._v(" 15. Actuator API")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("/gateway")]),e._v(" actuator endpoint lets you monitor and interact with a Spring Cloud Gateway application.\nTo be remotely accessible, the endpoint has to be "),a("a",{attrs:{href:"https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-enabling-endpoints",target:"_blank",rel:"noopener noreferrer"}},[e._v("enabled"),a("OutboundLink")],1),e._v(" and "),a("a",{attrs:{href:"https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html#production-ready-endpoints-exposing-endpoints",target:"_blank",rel:"noopener noreferrer"}},[e._v("exposed over HTTP or JMX"),a("OutboundLink")],1),e._v(" in the application properties.\nThe following listing shows how to do so:")]),e._v(" "),a("p",[e._v("Example 72. application.properties")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("management.endpoint.gateway.enabled=true # default value\nmanagement.endpoints.web.exposure.include=gateway\n")])])]),a("h3",{attrs:{id:"_15-1-verbose-actuator-format"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-1-verbose-actuator-format"}},[e._v("#")]),e._v(" 15.1. Verbose Actuator Format")]),e._v(" "),a("p",[e._v("A new, more verbose format has been added to Spring Cloud Gateway.\nIt adds more detail to each route, letting you view the predicates and filters associated with each route along with any configuration that is available.\nThe following example configures "),a("code",[e._v("/actuator/gateway/routes")]),e._v(":")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('[\n  {\n    "predicate": "(Hosts: [**.addrequestheader.org] && Paths: [/headers], match trailing slash: true)",\n    "route_id": "add_request_header_test",\n    "filters": [\n      "[[AddResponseHeader X-Response-Default-Foo = \'Default-Bar\'], order = 1]",\n      "[[AddRequestHeader X-Request-Foo = \'Bar\'], order = 1]",\n      "[[PrefixPath prefix = \'/httpbin\'], order = 2]"\n    ],\n    "uri": "lb://testservice",\n    "order": 0\n  }\n]\n')])])]),a("p",[e._v("This feature is enabled by default. To disable it, set the following property:")]),e._v(" "),a("p",[e._v("Example 73. application.properties")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("spring.cloud.gateway.actuator.verbose.enabled=false\n")])])]),a("p",[e._v("This will default to "),a("code",[e._v("true")]),e._v(" in a future release.")]),e._v(" "),a("h3",{attrs:{id:"_15-2-retrieving-route-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-2-retrieving-route-filters"}},[e._v("#")]),e._v(" 15.2. Retrieving Route Filters")]),e._v(" "),a("p",[e._v("This section details how to retrieve route filters, including:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"#gateway-global-filters"}},[e._v("Global Filters")])])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"#gateway-route-filters"}},[e._v("[gateway-route-filters]")])])])]),e._v(" "),a("h4",{attrs:{id:"_15-2-1-global-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-2-1-global-filters"}},[e._v("#")]),e._v(" 15.2.1. Global Filters")]),e._v(" "),a("p",[e._v("To retrieve the "),a("a",{attrs:{href:"#global-filters"}},[e._v("global filters")]),e._v(" applied to all routes, make a "),a("code",[e._v("GET")]),e._v(" request to "),a("code",[e._v("/actuator/gateway/globalfilters")]),e._v(". The resulting response is similar to the following:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('{\n  "org.spring[email protected]77856cc5": 10100,\n  "o[email protected]4f6fd101": 10000,\n  "or[email protected]32d22650": -1,\n  "[email protected]6459d9": 2147483647,\n  "[email protected]5e0": 2147483647,\n  "[email protected]d23": 0,\n  "org.s[email protected]135064ea": 2147483637,\n  "[email protected]23c05889": 2147483646\n}\n')])])]),a("p",[e._v("The response contains the details of the global filters that are in place.\nFor each global filter, there is a string representation of the filter object (for example, "),a("code",[e._v("org.spring[[email protected]](/cdn-cgi/l/email-protection)77856cc5")]),e._v(") and the corresponding "),a("a",{attrs:{href:"#gateway-combined-global-filter-and-gatewayfilter-ordering"}},[e._v("order")]),e._v(" in the filter chain.}")]),e._v(" "),a("h4",{attrs:{id:"_15-2-2-route-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-2-2-route-filters"}},[e._v("#")]),e._v(" 15.2.2. Route Filters")]),e._v(" "),a("p",[e._v("To retrieve the "),a("a",{attrs:{href:"#gatewayfilter-factories"}},[a("code",[e._v("GatewayFilter")]),e._v(" factories")]),e._v(" applied to routes, make a "),a("code",[e._v("GET")]),e._v(" request to "),a("code",[e._v("/actuator/gateway/routefilters")]),e._v(".\nThe resulting response is similar to the following:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('{\n  "[[email protected] configClass = AbstractNameValueGatewayFilterFactory.NameValueConfig]": null,\n  "[[email protected] configClass = Object]": null,\n  "[[email protected] configClass = Object]": null\n}\n')])])]),a("p",[e._v("The response contains the details of the "),a("code",[e._v("GatewayFilter")]),e._v(" factories applied to any particular route.\nFor each factory there is a string representation of the corresponding object (for example, "),a("code",[e._v("[[[email protected]](/cdn-cgi/l/email-protection) configClass = Object]")]),e._v(").\nNote that the "),a("code",[e._v("null")]),e._v(" value is due to an incomplete implementation of the endpoint controller, because it tries to set the order of the object in the filter chain, which does not apply to a "),a("code",[e._v("GatewayFilter")]),e._v(" factory object.")]),e._v(" "),a("h3",{attrs:{id:"_15-3-refreshing-the-route-cache"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-3-refreshing-the-route-cache"}},[e._v("#")]),e._v(" 15.3. Refreshing the Route Cache")]),e._v(" "),a("p",[e._v("To clear the routes cache, make a "),a("code",[e._v("POST")]),e._v(" request to "),a("code",[e._v("/actuator/gateway/refresh")]),e._v(".\nThe request returns a 200 without a response body.")]),e._v(" "),a("h3",{attrs:{id:"_15-4-retrieving-the-routes-defined-in-the-gateway"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-4-retrieving-the-routes-defined-in-the-gateway"}},[e._v("#")]),e._v(" 15.4. Retrieving the Routes Defined in the Gateway")]),e._v(" "),a("p",[e._v("To retrieve the routes defined in the gateway, make a "),a("code",[e._v("GET")]),e._v(" request to "),a("code",[e._v("/actuator/gateway/routes")]),e._v(".\nThe resulting response is similar to the following:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('[{\n  "route_id": "first_route",\n  "route_object": {\n    "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/[email protected]",\n    "filters": [\n      "OrderedGatewayFilter{delegate=org.springframework.cloud.gateway.filter.factory.PreserveHostHeaderGatewayFilterFactory$$Lambda$436/[email protected], order=0}"\n    ]\n  },\n  "order": 0\n},\n{\n  "route_id": "second_route",\n  "route_object": {\n    "predicate": "org.springframework.cloud.gateway.handler.predicate.PathRoutePredicateFactory$$Lambda$432/[email protected]",\n    "filters": []\n  },\n  "order": 0\n}]\n')])])]),a("p",[e._v("The response contains the details of all the routes defined in the gateway.\nThe following table describes the structure of each element (each is a route) of the response:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Path")]),e._v(" "),a("th",[e._v("Type")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("route_id")])]),e._v(" "),a("td",[e._v("String")]),e._v(" "),a("td",[e._v("The route ID.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("route_object.predicate")])]),e._v(" "),a("td",[e._v("Object")]),e._v(" "),a("td",[e._v("The route predicate.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("route_object.filters")])]),e._v(" "),a("td",[e._v("Array")]),e._v(" "),a("td",[e._v("The "),a("a",{attrs:{href:"#gatewayfilter-factories"}},[a("code",[e._v("GatewayFilter")]),e._v(" factories")]),e._v(" applied to the route.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("order")])]),e._v(" "),a("td",[e._v("Number")]),e._v(" "),a("td",[e._v("The route order.")])])])]),e._v(" "),a("h3",{attrs:{id:"_15-5-retrieving-information-about-a-particular-route"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-5-retrieving-information-about-a-particular-route"}},[e._v("#")]),e._v(" 15.5. Retrieving Information about a Particular Route")]),e._v(" "),a("p",[e._v("To retrieve information about a single route, make a "),a("code",[e._v("GET")]),e._v(" request to "),a("code",[e._v("/actuator/gateway/routes/{id}")]),e._v(" (for example, "),a("code",[e._v("/actuator/gateway/routes/first_route")]),e._v(").\nThe resulting response is similar to the following:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('{\n  "id": "first_route",\n  "predicates": [{\n    "name": "Path",\n    "args": {"_genkey_0":"/first"}\n  }],\n  "filters": [],\n  "uri": "https://www.uri-destination.org",\n  "order": 0\n}\n')])])]),a("p",[e._v("The following table describes the structure of the response:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Path")]),e._v(" "),a("th",[e._v("Type")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("id")])]),e._v(" "),a("td",[e._v("String")]),e._v(" "),a("td",[e._v("The route ID.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("predicates")])]),e._v(" "),a("td",[e._v("Array")]),e._v(" "),a("td",[e._v("The collection of route predicates. Each item defines the name and the arguments of a given predicate.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("filters")])]),e._v(" "),a("td",[e._v("Array")]),e._v(" "),a("td",[e._v("The collection of filters applied to the route.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("uri")])]),e._v(" "),a("td",[e._v("String")]),e._v(" "),a("td",[e._v("The destination URI of the route.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("order")])]),e._v(" "),a("td",[e._v("Number")]),e._v(" "),a("td",[e._v("The route order.")])])])]),e._v(" "),a("h3",{attrs:{id:"_15-6-creating-and-deleting-a-particular-route"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-6-creating-and-deleting-a-particular-route"}},[e._v("#")]),e._v(" 15.6. Creating and Deleting a Particular Route")]),e._v(" "),a("p",[e._v("To create a route, make a "),a("code",[e._v("POST")]),e._v(" request to "),a("code",[e._v("/gateway/routes/{id_route_to_create}")]),e._v(" with a JSON body that specifies the fields of the route (see "),a("a",{attrs:{href:"#gateway-retrieving-information-about-a-particular-route"}},[e._v("Retrieving Information about a Particular Route")]),e._v(").")]),e._v(" "),a("p",[e._v("To delete a route, make a "),a("code",[e._v("DELETE")]),e._v(" request to "),a("code",[e._v("/gateway/routes/{id_route_to_delete}")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_15-7-recap-the-list-of-all-endpoints"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-7-recap-the-list-of-all-endpoints"}},[e._v("#")]),e._v(" 15.7. Recap: The List of All endpoints")]),e._v(" "),a("p",[e._v("The folloiwng table below summarizes the Spring Cloud Gateway actuator endpoints (note that each endpoint has "),a("code",[e._v("/actuator/gateway")]),e._v(" as the base-path):")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("ID")]),e._v(" "),a("th",[e._v("HTTP Method")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("globalfilters")])]),e._v(" "),a("td",[e._v("GET")]),e._v(" "),a("td",[e._v("Displays the list of global filters applied to the routes.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("routefilters")])]),e._v(" "),a("td",[e._v("GET")]),e._v(" "),a("td",[e._v("Displays the list of "),a("code",[e._v("GatewayFilter")]),e._v(" factories applied to a particular route.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("refresh")])]),e._v(" "),a("td",[e._v("POST")]),e._v(" "),a("td",[e._v("Clears the routes cache.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("routes")])]),e._v(" "),a("td",[e._v("GET")]),e._v(" "),a("td",[e._v("Displays the list of routes defined in the gateway.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("routes/{id}")])]),e._v(" "),a("td",[e._v("GET")]),e._v(" "),a("td",[e._v("Displays information about a particular route.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("routes/{id}")])]),e._v(" "),a("td",[e._v("POST")]),e._v(" "),a("td",[e._v("Adds a new route to the gateway.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("routes/{id}")])]),e._v(" "),a("td",[e._v("DELETE")]),e._v(" "),a("td",[e._v("Removes an existing route from the gateway.")])])])]),e._v(" "),a("h3",{attrs:{id:"_15-8-sharing-routes-between-multiple-gateway-instances"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_15-8-sharing-routes-between-multiple-gateway-instances"}},[e._v("#")]),e._v(" 15.8. Sharing Routes between multiple Gateway instances")]),e._v(" "),a("p",[e._v("Spring Cloud Gateway offers two "),a("code",[e._v("RouteDefinitionRepository")]),e._v(" implementations. The first one is the"),a("code",[e._v("InMemoryRouteDefinitionRepository")]),e._v(" which only lives within the memory of one Gateway instance.\nThis type of Repository is not suited to populate Routes across multiple Gateway instances.")]),e._v(" "),a("p",[e._v("In order to share Routes across a cluster of Spring Cloud Gateway instances, "),a("code",[e._v("RedisRouteDefinitionRepository")]),e._v(" can be used.\nTo enable this kind of repository, the following property has to set to true: "),a("code",[e._v("spring.cloud.gateway.redis-route-definition-repository.enabled")]),e._v("Likewise to the RedisRateLimiter Filter Factory it requires the use of the spring-boot-starter-data-redis-reactive Spring Boot starter.")]),e._v(" "),a("h2",{attrs:{id:"_16-troubleshooting"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_16-troubleshooting"}},[e._v("#")]),e._v(" 16. Troubleshooting")]),e._v(" "),a("p",[e._v("This section covers common problems that may arise when you use Spring Cloud Gateway.")]),e._v(" "),a("h3",{attrs:{id:"_16-1-log-levels"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_16-1-log-levels"}},[e._v("#")]),e._v(" 16.1. Log Levels")]),e._v(" "),a("p",[e._v("The following loggers may contain valuable troubleshooting information at the "),a("code",[e._v("DEBUG")]),e._v(" and "),a("code",[e._v("TRACE")]),e._v(" levels:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("org.springframework.cloud.gateway")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("org.springframework.http.server.reactive")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("org.springframework.web.reactive")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("org.springframework.boot.autoconfigure.web")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("reactor.netty")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("redisratelimiter")])])])]),e._v(" "),a("h3",{attrs:{id:"_16-2-wiretap"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_16-2-wiretap"}},[e._v("#")]),e._v(" 16.2. Wiretap")]),e._v(" "),a("p",[e._v("The Reactor Netty "),a("code",[e._v("HttpClient")]),e._v(" and "),a("code",[e._v("HttpServer")]),e._v(" can have wiretap enabled.\nWhen combined with setting the "),a("code",[e._v("reactor.netty")]),e._v(" log level to "),a("code",[e._v("DEBUG")]),e._v(" or "),a("code",[e._v("TRACE")]),e._v(", it enables the logging of information, such as headers and bodies sent and received across the wire.\nTo enable wiretap, set "),a("code",[e._v("spring.cloud.gateway.httpserver.wiretap=true")]),e._v(" or "),a("code",[e._v("spring.cloud.gateway.httpclient.wiretap=true")]),e._v(" for the "),a("code",[e._v("HttpServer")]),e._v(" and "),a("code",[e._v("HttpClient")]),e._v(", respectively.")]),e._v(" "),a("h2",{attrs:{id:"_17-developer-guide"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_17-developer-guide"}},[e._v("#")]),e._v(" 17. Developer Guide")]),e._v(" "),a("p",[e._v("These are basic guides to writing some custom components of the gateway.")]),e._v(" "),a("h3",{attrs:{id:"_17-1-writing-custom-route-predicate-factories"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_17-1-writing-custom-route-predicate-factories"}},[e._v("#")]),e._v(" 17.1. Writing Custom Route Predicate Factories")]),e._v(" "),a("p",[e._v("In order to write a Route Predicate you will need to implement "),a("code",[e._v("RoutePredicateFactory")]),e._v(" as a bean. There is an abstract class called "),a("code",[e._v("AbstractRoutePredicateFactory")]),e._v(" which you can extend.")]),e._v(" "),a("p",[e._v("MyRoutePredicateFactory.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Component\npublic class MyRoutePredicateFactory extends AbstractRoutePredicateFactory<MyRoutePredicateFactory.Config> {\n\n    public MyRoutePredicateFactory() {\n        super(Config.class);\n    }\n\n    @Override\n    public Predicate<ServerWebExchange> apply(Config config) {\n        // grab configuration from Config object\n        return exchange -> {\n            //grab the request\n            ServerHttpRequest request = exchange.getRequest();\n            //take information from the request to see if it\n            //matches configuration.\n            return matches(config, request);\n        };\n    }\n\n    public static class Config {\n        //Put the configuration properties for your filter here\n    }\n\n}\n")])])]),a("h3",{attrs:{id:"_17-2-writing-custom-gatewayfilter-factories"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_17-2-writing-custom-gatewayfilter-factories"}},[e._v("#")]),e._v(" 17.2. Writing Custom GatewayFilter Factories")]),e._v(" "),a("p",[e._v("To write a "),a("code",[e._v("GatewayFilter")]),e._v(", you must implement "),a("code",[e._v("GatewayFilterFactory")]),e._v(" as a bean.\nYou can extend an abstract class called "),a("code",[e._v("AbstractGatewayFilterFactory")]),e._v(".\nThe following examples show how to do so:")]),e._v(" "),a("p",[e._v("Example 74. PreGatewayFilterFactory.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Component\npublic class PreGatewayFilterFactory extends AbstractGatewayFilterFactory<PreGatewayFilterFactory.Config> {\n\n    public PreGatewayFilterFactory() {\n        super(Config.class);\n    }\n\n    @Override\n    public GatewayFilter apply(Config config) {\n        // grab configuration from Config object\n        return (exchange, chain) -> {\n            //If you want to build a "pre" filter you need to manipulate the\n            //request before calling chain.filter\n            ServerHttpRequest.Builder builder = exchange.getRequest().mutate();\n            //use builder to manipulate the request\n            return chain.filter(exchange.mutate().request(builder.build()).build());\n        };\n    }\n\n    public static class Config {\n        //Put the configuration properties for your filter here\n    }\n\n}\n')])])]),a("p",[e._v("PostGatewayFilterFactory.java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Component\npublic class PostGatewayFilterFactory extends AbstractGatewayFilterFactory<PostGatewayFilterFactory.Config> {\n\n    public PostGatewayFilterFactory() {\n        super(Config.class);\n    }\n\n    @Override\n    public GatewayFilter apply(Config config) {\n        // grab configuration from Config object\n        return (exchange, chain) -> {\n            return chain.filter(exchange).then(Mono.fromRunnable(() -> {\n                ServerHttpResponse response = exchange.getResponse();\n                //Manipulate the response in some way\n            }));\n        };\n    }\n\n    public static class Config {\n        //Put the configuration properties for your filter here\n    }\n\n}\n")])])]),a("h4",{attrs:{id:"_17-2-1-naming-custom-filters-and-references-in-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_17-2-1-naming-custom-filters-and-references-in-configuration"}},[e._v("#")]),e._v(" 17.2.1. Naming Custom Filters And References In Configuration")]),e._v(" "),a("p",[e._v("Custom filters class names should end in "),a("code",[e._v("GatewayFilterFactory")]),e._v(".")]),e._v(" "),a("p",[e._v("For example, to reference a filter named "),a("code",[e._v("Something")]),e._v(" in configuration files, the filter\nmust be in a class named "),a("code",[e._v("SomethingGatewayFilterFactory")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("It is possible to create a gateway filter named without the"),a("code",[e._v("GatewayFilterFactory")]),e._v(" suffix, such as "),a("code",[e._v("class AnotherThing")]),e._v(". This filter could be"),a("br"),e._v("referenced as "),a("code",[e._v("AnotherThing")]),e._v(" in configuration files. This is "),a("strong",[e._v("not")]),e._v(" a supported naming"),a("br"),e._v("convention and this syntax may be removed in future releases. Please update the filter"),a("br"),e._v("name to be compliant.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_17-3-writing-custom-global-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_17-3-writing-custom-global-filters"}},[e._v("#")]),e._v(" 17.3. Writing Custom Global Filters")]),e._v(" "),a("p",[e._v("To write a custom global filter, you must implement "),a("code",[e._v("GlobalFilter")]),e._v(" interface as a bean.\nThis applies the filter to all requests.")]),e._v(" "),a("p",[e._v("The following examples show how to set up global pre and post filters, respectively:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\npublic GlobalFilter customGlobalFilter() {\n    return (exchange, chain) -> exchange.getPrincipal()\n        .map(Principal::getName)\n        .defaultIfEmpty("Default User")\n        .map(userName -> {\n          //adds header to proxied request\n          exchange.getRequest().mutate().header("CUSTOM-REQUEST-HEADER", userName).build();\n          return exchange;\n        })\n        .flatMap(chain::filter);\n}\n\n@Bean\npublic GlobalFilter customGlobalPostFilter() {\n    return (exchange, chain) -> chain.filter(exchange)\n        .then(Mono.just(exchange))\n        .map(serverWebExchange -> {\n          //adds header to response\n          serverWebExchange.getResponse().getHeaders().set("CUSTOM-RESPONSE-HEADER",\n              HttpStatus.OK.equals(serverWebExchange.getResponse().getStatusCode()) ? "It worked": "It did not work");\n          return serverWebExchange;\n        })\n        .then();\n}\n')])])]),a("h2",{attrs:{id:"_18-building-a-simple-gateway-by-using-spring-mvc-or-webflux"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_18-building-a-simple-gateway-by-using-spring-mvc-or-webflux"}},[e._v("#")]),e._v(" 18. Building a Simple Gateway by Using Spring MVC or Webflux")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The following describes an alternative style gateway. None of the prior documentation applies to what follows.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Spring Cloud Gateway provides a utility object called "),a("code",[e._v("ProxyExchange")]),e._v(".\nYou can use it inside a regular Spring web handler as a method parameter.\nIt supports basic downstream HTTP exchanges through methods that mirror the HTTP verbs.\nWith MVC, it also supports forwarding to a local handler through the "),a("code",[e._v("forward()")]),e._v(" method.\nTo use the "),a("code",[e._v("ProxyExchange")]),e._v(", include the right module in your classpath (either "),a("code",[e._v("spring-cloud-gateway-mvc")]),e._v(" or "),a("code",[e._v("spring-cloud-gateway-webflux")]),e._v(").")]),e._v(" "),a("p",[e._v("The following MVC example proxies a request to "),a("code",[e._v("/test")]),e._v(" downstream to a remote server:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\n@SpringBootApplication\npublic class GatewaySampleApplication {\n\n    @Value("${remote.home}")\n    private URI home;\n\n    @GetMapping("/test")\n    public ResponseEntity<?> proxy(ProxyExchange<byte[]> proxy) throws Exception {\n        return proxy.uri(home.toString() + "/image/png").get();\n    }\n\n}\n')])])]),a("p",[e._v("The following example does the same thing with Webflux:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\n@SpringBootApplication\npublic class GatewaySampleApplication {\n\n    @Value("${remote.home}")\n    private URI home;\n\n    @GetMapping("/test")\n    public Mono<ResponseEntity<?>> proxy(ProxyExchange<byte[]> proxy) throws Exception {\n        return proxy.uri(home.toString() + "/image/png").get();\n    }\n\n}\n')])])]),a("p",[e._v("Convenience methods on the "),a("code",[e._v("ProxyExchange")]),e._v(" enable the handler method to discover and enhance the URI path of the incoming request.\nFor example, you might want to extract the trailing elements of a path to pass them downstream:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/proxy/path/**")\npublic ResponseEntity<?> proxyPath(ProxyExchange<byte[]> proxy) throws Exception {\n  String path = proxy.path("/proxy/path/");\n  return proxy.uri(home.toString() + "/foos/" + path).get();\n}\n')])])]),a("p",[e._v("All the features of Spring MVC and Webflux are available to gateway handler methods.\nAs a result, you can inject request headers and query parameters, for instance, and you can constrain the incoming requests with declarations in the mapping annotation.\nSee the documentation for "),a("code",[e._v("@RequestMapping")]),e._v(" in Spring MVC for more details of those features.")]),e._v(" "),a("p",[e._v("You can add headers to the downstream response by using the "),a("code",[e._v("header()")]),e._v(" methods on "),a("code",[e._v("ProxyExchange")]),e._v(".")]),e._v(" "),a("p",[e._v("You can also manipulate response headers (and anything else you like in the response) by adding a mapper to the "),a("code",[e._v("get()")]),e._v(" method (and other methods).\nThe mapper is a "),a("code",[e._v("Function")]),e._v(" that takes the incoming "),a("code",[e._v("ResponseEntity")]),e._v(" and converts it to an outgoing one.")]),e._v(" "),a("p",[e._v("First-class support is provided for “sensitive” headers (by default, "),a("code",[e._v("cookie")]),e._v(" and "),a("code",[e._v("authorization")]),e._v("), which are not passed downstream, and for “proxy” ("),a("code",[e._v("x-forwarded-*")]),e._v(") headers.")]),e._v(" "),a("h2",{attrs:{id:"_19-configuration-properties"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_19-configuration-properties"}},[e._v("#")]),e._v(" 19. Configuration properties")]),e._v(" "),a("p",[e._v("To see the list of all Spring Cloud Gateway related configuration properties, see "),a("RouterLink",{attrs:{to:"/en/spring-cloud/appendix.html"}},[e._v("the appendix")]),e._v(".")],1)])}),[],!1,null,null,null);t.default=o.exports}}]);