SpringCloud/spring-cloud-gateway
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync docs from 2.1.x to gh-pages

Browse Source
This commit is contained in:
buildmaster
2019-11-15 19:54:28 +00:00
parent c2b7b69a84
commit 520f3ec1cd
4 changed files with 95 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
2.1.x/multi/multi__global_filters.html
View File

@@ -34,7 +34,31 @@ the scheme specified in the request made to the Gateway. For example, if the re
but the <code class="literal">ServiceInstance</code> indicates it is not secure, then the downstream request will be made over
<code class="literal">HTTP</code>. The opposite situation can also apply. However if <code class="literal">GATEWAY_SCHEME_PREFIX_ATTR</code> is specified for the
route in the Gateway configuration, the prefix will be stripped and the resulting scheme from the
route URL will override the <code class="literal">ServiceInstance</code> configuration.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_netty_routing_filter" href="#_netty_routing_filter"></a>6.4&nbsp;Netty Routing Filter</h2></div></div></div><p>The Netty Routing Filter runs if the url located in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute has a <code class="literal">http</code> or <code class="literal">https</code> scheme. It uses the Netty <code class="literal">HttpClient</code> to make the downstream proxy request. The response is put in the <code class="literal">ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR</code> exchange attribute for use in a later filter. (There is an experimental <code class="literal">WebClientHttpRoutingFilter</code> that performs the same function, but does not require netty)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_netty_write_response_filter" href="#_netty_write_response_filter"></a>6.5&nbsp;Netty Write Response Filter</h2></div></div></div><p>The <code class="literal">NettyWriteResponseFilter</code> runs if there is a Netty <code class="literal">HttpClientResponse</code> in the <code class="literal">ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR</code> exchange attribute. It is run after all other filters have completed and writes the proxy response back to the gateway client response. (There is an experimental <code class="literal">WebClientWriteResponseFilter</code> that performs the same function, but does not require netty)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_routetorequesturl_filter" href="#_routetorequesturl_filter"></a>6.6&nbsp;RouteToRequestUrl Filter</h2></div></div></div><p>The <code class="literal">RouteToRequestUrlFilter</code> runs if there is a <code class="literal">Route</code> object in the <code class="literal">ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR</code> exchange attribute. It creates a new URI, based off of the request URI, but updated with the URI attribute of the <code class="literal">Route</code> object. The new URI is placed in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute`.</p><p>If the URI has a scheme prefix, such as <code class="literal">lb:ws://serviceid</code>, the <code class="literal">lb</code> scheme is stripped from the URI and placed in the <code class="literal">ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR</code> for use later in the filter chain.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_websocket_routing_filter" href="#_websocket_routing_filter"></a>6.7&nbsp;Websocket Routing Filter</h2></div></div></div><p>The Websocket Routing Filter runs if the url located in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute has a <code class="literal">ws</code> or <code class="literal">wss</code> scheme. It uses the Spring Web Socket infrastructure to forward the Websocket request downstream.</p><p>Websockets may be load-balanced by prefixing the URI with <code class="literal">lb</code>, such as <code class="literal">lb:ws://serviceid</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you are using <a class="link" href="https://github.com/sockjs" target="_top">SockJS</a> as a fallback over normal http, you should configure a normal HTTP route as well as the Websocket Route.</p></td></tr></table></div><p><b>application.yml.&nbsp;</b>
route URL will override the <code class="literal">ServiceInstance</code> configuration.</p></td></tr></table></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p><code class="literal">LoadBalancerClientFilter</code> uses a blocking Ribbon <code class="literal">LoadBalancerClient</code> under the hood.
We suggest you use <a class="link" href="multi__global_filters.html#reactive-loadbalancer-client-filter" title="6.4&nbsp;ReactiveLoadBalancerClientFilter"><code class="literal">ReactiveLoadBalancerClientFilter</code> instead</a>.
You can switch to using it by adding <code class="literal">org.springframework.cloud:spring-cloud-loadbalancer</code> dependency to your project
and setting the value of the <code class="literal">spring.cloud.loadbalancer.ribbon.enabled</code> to <code class="literal">false</code>.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="reactive-loadbalancer-client-filter" href="#reactive-loadbalancer-client-filter"></a>6.4&nbsp;ReactiveLoadBalancerClientFilter</h2></div></div></div><p>The <code class="literal">ReactiveLoadBalancerClientFilter</code> looks for a URI in the exchange attribute
<code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code>. If the url has a <code class="literal">lb</code> scheme (ie <code class="literal">lb://myservice</code>),
it will use the Spring Cloud <code class="literal">ReactorLoadBalancer</code> to resolve the name (<code class="literal">myservice</code> in the previous example)
to an actual host and port and replace the URI in the same attribute. The unmodified
original url is appended to the list in the <code class="literal">ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR</code> attribute.
The filter will also look in the <code class="literal">ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR</code> attribute to see if it equals
<code class="literal">lb</code> and then the same rules apply.</p><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> routes</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - id</span>: myRoute
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: lb://service
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/service/**</pre><p>
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>By default when a service instance cannot be found by the <code class="literal">ReactorLoadBalancer</code>, a <code class="literal">503</code> will be returned.
You can configure the Gateway to return a <code class="literal">404</code> by setting <code class="literal">spring.cloud.gateway.loadbalancer.use404=true</code>.</p></td></tr></table></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">isSecure</code> value of the <code class="literal">ServiceInstance</code> returned from the <code class="literal">ReactiveLoadBalancerClientFilter</code> will override
the scheme specified in the request made to the Gateway. For example, if the request comes into the Gateway over <code class="literal">HTTPS</code>
but the <code class="literal">ServiceInstance</code> indicates it is not secure, then the downstream request will be made over
<code class="literal">HTTP</code>. The opposite situation can also apply. However if <code class="literal">GATEWAY_SCHEME_PREFIX_ATTR</code> is specified for the
route in the Gateway configuration, the prefix will be stripped and the resulting scheme from the
route URL will override the <code class="literal">ServiceInstance</code> configuration.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_netty_routing_filter" href="#_netty_routing_filter"></a>6.5&nbsp;Netty Routing Filter</h2></div></div></div><p>The Netty Routing Filter runs if the url located in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute has a <code class="literal">http</code> or <code class="literal">https</code> scheme. It uses the Netty <code class="literal">HttpClient</code> to make the downstream proxy request. The response is put in the <code class="literal">ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR</code> exchange attribute for use in a later filter. (There is an experimental <code class="literal">WebClientHttpRoutingFilter</code> that performs the same function, but does not require netty)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_netty_write_response_filter" href="#_netty_write_response_filter"></a>6.6&nbsp;Netty Write Response Filter</h2></div></div></div><p>The <code class="literal">NettyWriteResponseFilter</code> runs if there is a Netty <code class="literal">HttpClientResponse</code> in the <code class="literal">ServerWebExchangeUtils.CLIENT_RESPONSE_ATTR</code> exchange attribute. It is run after all other filters have completed and writes the proxy response back to the gateway client response. (There is an experimental <code class="literal">WebClientWriteResponseFilter</code> that performs the same function, but does not require netty)</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_routetorequesturl_filter" href="#_routetorequesturl_filter"></a>6.7&nbsp;RouteToRequestUrl Filter</h2></div></div></div><p>The <code class="literal">RouteToRequestUrlFilter</code> runs if there is a <code class="literal">Route</code> object in the <code class="literal">ServerWebExchangeUtils.GATEWAY_ROUTE_ATTR</code> exchange attribute. It creates a new URI, based off of the request URI, but updated with the URI attribute of the <code class="literal">Route</code> object. The new URI is placed in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute`.</p><p>If the URI has a scheme prefix, such as <code class="literal">lb:ws://serviceid</code>, the <code class="literal">lb</code> scheme is stripped from the URI and placed in the <code class="literal">ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR</code> for use later in the filter chain.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_websocket_routing_filter" href="#_websocket_routing_filter"></a>6.8&nbsp;Websocket Routing Filter</h2></div></div></div><p>The Websocket Routing Filter runs if the url located in the <code class="literal">ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</code> exchange attribute has a <code class="literal">ws</code> or <code class="literal">wss</code> scheme. It uses the Spring Web Socket infrastructure to forward the Websocket request downstream.</p><p>Websockets may be load-balanced by prefixing the URI with <code class="literal">lb</code>, such as <code class="literal">lb:ws://serviceid</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>If you are using <a class="link" href="https://github.com/sockjs" target="_top">SockJS</a> as a fallback over normal http, you should configure a normal HTTP route as well as the Websocket Route.</p></td></tr></table></div><p><b>application.yml.&nbsp;</b>
</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute">spring</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> cloud</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> gateway</span>:
@@ -49,7 +73,7 @@ route URL will override the <code class="literal">ServiceInstance</code> configu
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> uri</span>: ws://localhost:<xslthl:number xmlns:xslthl="http://xslthl.sourceforge.net/">3001</xslthl:number>
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> predicates</span>:
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-attribute"> - Path</span>=/websocket/**</pre><p>
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_gateway_metrics_filter" href="#_gateway_metrics_filter"></a>6.8&nbsp;Gateway Metrics Filter</h2></div></div></div><p>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 <code class="literal">spring.cloud.gateway.metrics.enabled</code> is not set to <code class="literal">false</code>. This filter adds a timer metric named "gateway.requests" with the following tags:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">routeId</code>: The route id</li><li class="listitem"><code class="literal">routeUri</code>: The URI that the API will be routed to</li><li class="listitem"><code class="literal">outcome</code>: Outcome as classified by <a class="link" href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/HttpStatus.Series.html" target="_top">HttpStatus.Series</a></li><li class="listitem"><code class="literal">status</code>: Http Status of the request returned to the client</li><li class="listitem"><code class="literal">httpStatusCode</code>: Http Status of the request returned to the client</li><li class="listitem"><code class="literal">httpMethod</code>: The Http method used for the request</li></ul></div><p>These metrics are then available to be scraped from <code class="literal">/actuator/metrics/gateway.requests</code> and can be easily integrated with Prometheus to create a <a class="link" href="images/gateway-grafana-dashboard.jpeg" target="_top">Grafana</a> <a class="link" href="gateway-grafana-dashboard.json" target="_top">dashboard</a>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>To enable the prometheus endpoint add micrometer-registry-prometheus as a project dependency.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_marking_an_exchange_as_routed" href="#_marking_an_exchange_as_routed"></a>6.9&nbsp;Marking An Exchange As Routed</h2></div></div></div><p>After the Gateway has routed a <code class="literal">ServerWebExchange</code> it will mark that exchange as "routed" by adding <code class="literal">gatewayAlreadyRouted</code>
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_gateway_metrics_filter" href="#_gateway_metrics_filter"></a>6.9&nbsp;Gateway Metrics Filter</h2></div></div></div><p>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 <code class="literal">spring.cloud.gateway.metrics.enabled</code> is not set to <code class="literal">false</code>. This filter adds a timer metric named "gateway.requests" with the following tags:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">routeId</code>: The route id</li><li class="listitem"><code class="literal">routeUri</code>: The URI that the API will be routed to</li><li class="listitem"><code class="literal">outcome</code>: Outcome as classified by <a class="link" href="https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/HttpStatus.Series.html" target="_top">HttpStatus.Series</a></li><li class="listitem"><code class="literal">status</code>: Http Status of the request returned to the client</li><li class="listitem"><code class="literal">httpStatusCode</code>: Http Status of the request returned to the client</li><li class="listitem"><code class="literal">httpMethod</code>: The Http method used for the request</li></ul></div><p>These metrics are then available to be scraped from <code class="literal">/actuator/metrics/gateway.requests</code> and can be easily integrated with Prometheus to create a <a class="link" href="images/gateway-grafana-dashboard.jpeg" target="_top">Grafana</a> <a class="link" href="gateway-grafana-dashboard.json" target="_top">dashboard</a>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>To enable the prometheus endpoint add micrometer-registry-prometheus as a project dependency.</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_marking_an_exchange_as_routed" href="#_marking_an_exchange_as_routed"></a>6.10&nbsp;Marking An Exchange As Routed</h2></div></div></div><p>After the Gateway has routed a <code class="literal">ServerWebExchange</code> it will mark that exchange as "routed" by adding <code class="literal">gatewayAlreadyRouted</code>
to the exchange attributes. Once a request has been marked as routed, other routing filters will not route the request again,
essentially skipping the filter. There are convenience methods that you can use to mark an exchange as routed
or check if an exchange has already been routed.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">ServerWebExchangeUtils.isAlreadyRouted</code> takes a <code class="literal">ServerWebExchange</code> object and checks if it has been "routed"</li><li class="listitem"><code class="literal">ServerWebExchangeUtils.setAlreadyRouted</code> takes a <code class="literal">ServerWebExchange</code> object and marks it as "routed"</li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__gatewayfilter_factories.html">Prev</a>&nbsp;</td><td width="20%" align="center">&nbsp;</td><td width="40%" align="right">&nbsp;<a accesskey="n" href="multi__tls_ssl.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5.&nbsp;GatewayFilter Factories&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-gateway.html">Home</a></td><td width="40%" align="right" valign="top">&nbsp;7.&nbsp;TLS / SSL</td></tr></table></div></body></html>

2
2.1.x/multi/multi_spring-cloud-gateway.html
View File

File diff suppressed because one or more lines are too long

30
2.1.x/single/spring-cloud-gateway.html
View File

File diff suppressed because one or more lines are too long

41
2.1.x/spring-cloud-gateway.xml
View File

@@ -1322,6 +1322,47 @@ but the <literal>ServiceInstance</literal> indicates it is not secure, then the
route in the Gateway configuration, the prefix will be stripped and the resulting scheme from the
route URL will override the <literal>ServiceInstance</literal> configuration.</simpara>
</note>
<warning>
<simpara><literal>LoadBalancerClientFilter</literal> uses a blocking Ribbon <literal>LoadBalancerClient</literal> under the hood.
We suggest you use <link linkend="reactive-loadbalancer-client-filter"><literal>ReactiveLoadBalancerClientFilter</literal> instead</link>.
You can switch to using it by adding <literal>org.springframework.cloud:spring-cloud-loadbalancer</literal> dependency to your project
and setting the value of the <literal>spring.cloud.loadbalancer.ribbon.enabled</literal> to <literal>false</literal>.</simpara>
</warning>
</section>
<section xml:id="reactive-loadbalancer-client-filter">
<title>ReactiveLoadBalancerClientFilter</title>
<simpara>The <literal>ReactiveLoadBalancerClientFilter</literal> looks for a URI in the exchange attribute
<literal>ServerWebExchangeUtils.GATEWAY_REQUEST_URL_ATTR</literal>. If the url has a <literal>lb</literal> scheme (ie <literal>lb://myservice</literal>),
it will use the Spring Cloud <literal>ReactorLoadBalancer</literal> to resolve the name (<literal>myservice</literal> in the previous example)
to an actual host and port and replace the URI in the same attribute. The unmodified
original url is appended to the list in the <literal>ServerWebExchangeUtils.GATEWAY_ORIGINAL_REQUEST_URL_ATTR</literal> attribute.
The filter will also look in the <literal>ServerWebExchangeUtils.GATEWAY_SCHEME_PREFIX_ATTR</literal> attribute to see if it equals
<literal>lb</literal> and then the same rules apply.</simpara>
<formalpara>
<title>application.yml</title>
<para>
<programlisting language="yaml" linenumbering="unnumbered">spring:
cloud:
gateway:
routes:
- id: myRoute
uri: lb://service
predicates:
- Path=/service/**</programlisting>
</para>
</formalpara>
<note>
<simpara>By default when a service instance cannot be found by the <literal>ReactorLoadBalancer</literal>, a <literal>503</literal> will be returned.
You can configure the Gateway to return a <literal>404</literal> by setting <literal>spring.cloud.gateway.loadbalancer.use404=true</literal>.</simpara>
</note>
<note>
<simpara>The <literal>isSecure</literal> value of the <literal>ServiceInstance</literal> returned from the <literal>ReactiveLoadBalancerClientFilter</literal> will override
the scheme specified in the request made to the Gateway. For example, if the request comes into the Gateway over <literal>HTTPS</literal>
but the <literal>ServiceInstance</literal> indicates it is not secure, then the downstream request will be made over
<literal>HTTP</literal>. The opposite situation can also apply. However if <literal>GATEWAY_SCHEME_PREFIX_ATTR</literal> is specified for the
route in the Gateway configuration, the prefix will be stripped and the resulting scheme from the
route URL will override the <literal>ServiceInstance</literal> configuration.</simpara>
</note>
</section>
<section xml:id="_netty_routing_filter">
<title>Netty Routing Filter</title>