From ed441b8325e75c7f3c0794de6b4c3e09887bcb8f Mon Sep 17 00:00:00 2001 From: buildmaster Date: Mon, 19 Nov 2018 21:17:48 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- .../multi__polyglot_support_with_sidecar.html | 2 +- multi/multi__router_and_filter_zuul.html | 25 +++++++++---- multi/multi_retrying-failed-requests.html | 6 ++-- multi/multi_spring-cloud-netflix.html | 2 +- single/spring-cloud-netflix.html | 35 ++++++++++++------- spring-cloud-netflix.xml | 24 +++++++++++-- 6 files changed, 67 insertions(+), 27 deletions(-) diff --git a/multi/multi__polyglot_support_with_sidecar.html b/multi/multi__polyglot_support_with_sidecar.html index e766d12c6..dfe84a52a 100644 --- a/multi/multi__polyglot_support_with_sidecar.html +++ b/multi/multi__polyglot_support_with_sidecar.html @@ -55,4 +55,4 @@ might result in a YAML document resembling the following:

  password: password
 info:
   description: Spring Cloud Samples
-  url: https://github.com/spring-cloud-samples
Prev   Next
8. Router and Filter: Zuul Home 10. Retrying Failed Requests
\ No newline at end of file + url: https://github.com/spring-cloud-samples

To enable the health check request to accept all certificates when using HTTPs set sidecar.accept-all-ssl-certificates to `true.

Prev   Next
8. Router and Filter: Zuul Home 10. Retrying Failed Requests
\ No newline at end of file diff --git a/multi/multi__router_and_filter_zuul.html b/multi/multi__router_and_filter_zuul.html index a3f040a98..b476d0a58 100644 --- a/multi/multi__router_and_filter_zuul.html +++ b/multi/multi__router_and_filter_zuul.html @@ -326,17 +326,28 @@ The following example adds a filter by using a Spring Configuration file:

public LocationRewriteFilter locationRewriteFilter() { return new LocationRewriteFilter(); } -}
[Caution]Caution

Use this filter carefully. The filter acts on the Location header of ALL 3XX response codes, which may not be appropriate in all scenarios, such as when redirecting the user to an external URL.

8.15 Metrics

Zuul will provide metrics under the Actuator metrics endpoint for any failures that might occur when routing requests. +}

[Caution]Caution

Use this filter carefully. The filter acts on the Location header of ALL 3XX response codes, which may not be appropriate in all scenarios, such as when redirecting the user to an external URL.

8.15 Enabling Cross Origin Requests

By default Zuul routes all Cross Origin requests (CORS) to the services. If you want instead Zuul to handle these requests it can be done by providing custom WebMvcConfigurer bean:

@Bean
+public WebMvcConfigurer corsConfigurer() {
+    return new WebMvcConfigurer() {
+        public void addCorsMappings(CorsRegistry registry) {
+            registry.addMapping("/path-1/**")
+                    .allowedOrigins("http://allowed-origin.com")
+                    .allowedMethods("GET", "POST");
+        }
+    };
+}

In the example above, we allow GET and POST methods from http://allowed-origin.com to send cross-origin requests to the endpoints starting with path-1. +You can apply CORS configuration to a specific path pattern or globally for the whole application, using /** mapping. +You can customize properties: allowedOrigins,allowedMethods,allowedHeaders,exposedHeaders,allowCredentials and maxAge via this configuration.

8.16 Metrics

Zuul will provide metrics under the Actuator metrics endpoint for any failures that might occur when routing requests. These metrics can be viewed by hitting /actuator/metrics. The metrics will have a name that has the format -ZUUL::EXCEPTION:errorCause:statusCode.

8.16 Zuul Developer Guide

For a general overview of how Zuul works, see the Zuul Wiki.

8.16.1 The Zuul Servlet

Zuul is implemented as a Servlet. For the general cases, Zuul is embedded into the Spring Dispatch mechanism. This lets Spring MVC be in control of the routing. +ZUUL::EXCEPTION:errorCause:statusCode.

8.17 Zuul Developer Guide

For a general overview of how Zuul works, see the Zuul Wiki.

8.17.1 The Zuul Servlet

Zuul is implemented as a Servlet. For the general cases, Zuul is embedded into the Spring Dispatch mechanism. This lets Spring MVC be in control of the routing. In this case, Zuul buffers requests. If there is a need to go through Zuul without buffering requests (for example, for large file uploads), the Servlet is also installed outside of the Spring Dispatcher. By default, the servlet has an address of /zuul. -This path can be changed with the zuul.servlet-path property.

8.16.2 Zuul RequestContext

To pass information between filters, Zuul uses a RequestContext. +This path can be changed with the zuul.servlet-path property.

8.17.2 Zuul RequestContext

To pass information between filters, Zuul uses a RequestContext. Its data is held in a ThreadLocal specific to each request. Information about where to route requests, errors, and the actual HttpServletRequest and HttpServletResponse are stored there. -The RequestContext extends ConcurrentHashMap, so anything can be stored in the context. FilterConstants contains the keys used by the filters installed by Spring Cloud Netflix (more on these later).

8.16.3 @EnableZuulProxy vs. @EnableZuulServer

Spring Cloud Netflix installs a number of filters, depending on which annotation was used to enable Zuul. @EnableZuulProxy is a superset of @EnableZuulServer. In other words, @EnableZuulProxy contains all the filters installed by @EnableZuulServer. The additional filters in the “proxy” enable routing functionality. If you want a “blank” Zuul, you should use @EnableZuulServer.

8.16.4 @EnableZuulServer Filters

@EnableZuulServer creates a SimpleRouteLocator that loads route definitions from Spring Boot configuration files.

The following filters are installed (as normal Spring Beans):

  • Pre filters:

    • ServletDetectionFilter: Detects whether the request is through the Spring Dispatcher. Sets a boolean with a key of FilterConstants.IS_DISPATCHER_SERVLET_REQUEST_KEY.
    • FormBodyWrapperFilter: Parses form data and re-encodes it for downstream requests.
    • DebugFilter: If the debug request parameter is set, sets RequestContext.setDebugRouting() and RequestContext.setDebugRequest() to true. -*Route filters:
    • SendForwardFilter: Forwards requests by using the Servlet RequestDispatcher. The forwarding location is stored in the RequestContext attribute, FilterConstants.FORWARD_TO_KEY. This is useful for forwarding to endpoints in the current application.

  • Post filters:

    • SendResponseFilter: Writes responses from proxied requests to the current response.

  • Error filters:

    • SendErrorFilter: Forwards to /error (by default) if RequestContext.getThrowable() is not null. You can change the default forwarding path (/error) by setting the error.path property.

8.16.5 @EnableZuulProxy Filters

Creates a DiscoveryClientRouteLocator that loads route definitions from a DiscoveryClient (such as Eureka) as well as from properties. A route is created for each serviceId from the DiscoveryClient. As new services are added, the routes are refreshed.

In addition to the filters described earlier, the following filters are installed (as normal Spring Beans):

  • Pre filters:

    • PreDecorationFilter: Determines where and how to route, depending on the supplied RouteLocator. It also sets various proxy-related headers for downstream requests.

  • Route filters:

    • RibbonRoutingFilter: Uses Ribbon, Hystrix, and pluggable HTTP clients to send requests. Service IDs are found in the RequestContext attribute, FilterConstants.SERVICE_ID_KEY. This filter can use different HTTP clients:

      • Apache HttpClient: The default client.
      • Squareup OkHttpClient v3: Enabled by having the com.squareup.okhttp3:okhttp library on the classpath and setting ribbon.okhttp.enabled=true.
      • Netflix Ribbon HTTP client: Enabled by setting ribbon.restclient.enabled=true. This client has limitations, including that it does not support the PATCH method, but it also has built-in retry.
    • SimpleHostRoutingFilter: Sends requests to predetermined URLs through an Apache HttpClient. URLs are found in RequestContext.getRouteHost().

8.16.6 Custom Zuul Filter Examples

Most of the following "How to Write" examples below are included Sample Zuul Filters project. There are also examples of manipulating the request or response body in that repository.

This section includes the following examples:

How to Write a Pre Filter

Pre filters set up data in the RequestContext for use in filters downstream. +The RequestContext extends ConcurrentHashMap, so anything can be stored in the context. FilterConstants contains the keys used by the filters installed by Spring Cloud Netflix (more on these later).

8.17.3 @EnableZuulProxy vs. @EnableZuulServer

Spring Cloud Netflix installs a number of filters, depending on which annotation was used to enable Zuul. @EnableZuulProxy is a superset of @EnableZuulServer. In other words, @EnableZuulProxy contains all the filters installed by @EnableZuulServer. The additional filters in the “proxy” enable routing functionality. If you want a “blank” Zuul, you should use @EnableZuulServer.

8.17.4 @EnableZuulServer Filters

@EnableZuulServer creates a SimpleRouteLocator that loads route definitions from Spring Boot configuration files.

The following filters are installed (as normal Spring Beans):

  • Pre filters:

    • ServletDetectionFilter: Detects whether the request is through the Spring Dispatcher. Sets a boolean with a key of FilterConstants.IS_DISPATCHER_SERVLET_REQUEST_KEY.
    • FormBodyWrapperFilter: Parses form data and re-encodes it for downstream requests.
    • DebugFilter: If the debug request parameter is set, sets RequestContext.setDebugRouting() and RequestContext.setDebugRequest() to true. +*Route filters:
    • SendForwardFilter: Forwards requests by using the Servlet RequestDispatcher. The forwarding location is stored in the RequestContext attribute, FilterConstants.FORWARD_TO_KEY. This is useful for forwarding to endpoints in the current application.

  • Post filters:

    • SendResponseFilter: Writes responses from proxied requests to the current response.

  • Error filters:

    • SendErrorFilter: Forwards to /error (by default) if RequestContext.getThrowable() is not null. You can change the default forwarding path (/error) by setting the error.path property.

8.17.5 @EnableZuulProxy Filters

Creates a DiscoveryClientRouteLocator that loads route definitions from a DiscoveryClient (such as Eureka) as well as from properties. A route is created for each serviceId from the DiscoveryClient. As new services are added, the routes are refreshed.

In addition to the filters described earlier, the following filters are installed (as normal Spring Beans):

  • Pre filters:

    • PreDecorationFilter: Determines where and how to route, depending on the supplied RouteLocator. It also sets various proxy-related headers for downstream requests.

  • Route filters:

    • RibbonRoutingFilter: Uses Ribbon, Hystrix, and pluggable HTTP clients to send requests. Service IDs are found in the RequestContext attribute, FilterConstants.SERVICE_ID_KEY. This filter can use different HTTP clients:

      • Apache HttpClient: The default client.
      • Squareup OkHttpClient v3: Enabled by having the com.squareup.okhttp3:okhttp library on the classpath and setting ribbon.okhttp.enabled=true.
      • Netflix Ribbon HTTP client: Enabled by setting ribbon.restclient.enabled=true. This client has limitations, including that it does not support the PATCH method, but it also has built-in retry.
    • SimpleHostRoutingFilter: Sends requests to predetermined URLs through an Apache HttpClient. URLs are found in RequestContext.getRouteHost().

8.17.6 Custom Zuul Filter Examples

Most of the following "How to Write" examples below are included Sample Zuul Filters project. There are also examples of manipulating the request or response body in that repository.

This section includes the following examples:

How to Write a Pre Filter

Pre filters set up data in the RequestContext for use in filters downstream. The main use case is to set information required for route filters. The following example shows a Zuul pre filter:

public class QueryParamPreFilter extends ZuulFilter {
 	@Override
@@ -465,9 +476,9 @@ The following example shows a Zuul route filter:
 		servletResponse.addHeader("X-Sample", UUID.randomUUID().toString());
 		return null;
 	}
-}
[Note]Note
Other manipulations, such as transforming the response body, are much more complex and computationally intensive.

8.16.7 How Zuul Errors Work

If an exception is thrown during any portion of the Zuul filter lifecycle, the error filters are executed. +}

[Note]Note

Other manipulations, such as transforming the response body, are much more complex and computationally intensive.

8.17.7 How Zuul Errors Work

If an exception is thrown during any portion of the Zuul filter lifecycle, the error filters are executed. The SendErrorFilter is only run if RequestContext.getThrowable() is not null. -It then sets specific javax.servlet.error.* attributes in the request and forwards the request to the Spring Boot error page.

8.16.8 Zuul Eager Application Context Loading

Zuul internally uses Ribbon for calling the remote URLs. +It then sets specific javax.servlet.error.* attributes in the request and forwards the request to the Spring Boot error page.

8.17.8 Zuul Eager Application Context Loading

Zuul internally uses Ribbon for calling the remote URLs. By default, Ribbon clients are lazily loaded by Spring Cloud on first call. This behavior can be changed for Zuul by using the following configuration, which results eager loading of the child Ribbon related Application contexts at application startup time. The following example shows how to enable eager loading:

application.yml.  diff --git a/multi/multi_retrying-failed-requests.html b/multi/multi_retrying-failed-requests.html index 7124fa449..c6d77a40f 100644 --- a/multi/multi_retrying-failed-requests.html +++ b/multi/multi_retrying-failed-requests.html @@ -6,11 +6,11 @@ No matter how you choose to create your HTTP requests, there is always a chance When a request fails, you may want to have the request be retried automatically. To do so when using Sping Cloud Netflix, you need to include Spring Retry on your application’s classpath. When Spring Retry is present, load-balanced RestTemplates, Feign, and Zuul automatically retry any failed requests (assuming your configuration allows doing so).

10.1 BackOff Policies

By default, no backoff policy is used when retrying requests. -If you would like to configure a backoff policy, you need to create a bean of type LoadBalancedBackOffPolicyFactory, which is used to create a BackOffPolicy for a given service, as shown in the following example:

@Configuration
+If you would like to configure a backoff policy, you need to create a bean of type LoadBalancedRetryFactory and override the createBackOffPolicy method for a given service, as shown in the following example:
@Configuration
 public class MyConfiguration {
     @Bean
-    LoadBalancedBackOffPolicyFactory backOffPolicyFactory() {
-        return new LoadBalancedBackOffPolicyFactory() {
+    LoadBalancedRetryFactory retryFactory() {
+        return new LoadBalancedRetryFactory() {
             @Override
             public BackOffPolicy createBackOffPolicy(String service) {
                 return new ExponentialBackOffPolicy();
diff --git a/multi/multi_spring-cloud-netflix.html b/multi/multi_spring-cloud-netflix.html
index 604df1ffd..5b67c0e5a 100644
--- a/multi/multi_spring-cloud-netflix.html
+++ b/multi/multi_spring-cloud-netflix.html
@@ -1,3 +1,3 @@
 
       
-   Spring Cloud Netflix
Spring Cloud Netflix
   Next
Spring Cloud Netflix
Table of Contents
1. Service Discovery: Eureka Clients
1.1. How to Include Eureka Client
1.2. Registering with Eureka
1.3. Authenticating with the Eureka Server
1.4. Status Page and Health Indicator
1.5. Registering a Secure Application
1.6. Eureka’s Health Checks
1.7. Eureka Metadata for Instances and Clients
1.7.1. Using Eureka on Cloud Foundry
1.7.2. Using Eureka on AWS
1.7.3. Changing the Eureka Instance ID
1.8. Using the EurekaClient
1.8.1. EurekaClient without Jersey
1.9. Alternatives to the Native Netflix EurekaClient
1.10. Why Is It so Slow to Register a Service?
1.11. Zones
2. Service Discovery: Eureka Server
2.1. How to Include Eureka Server
2.2. How to Run a Eureka Server
2.3. High Availability, Zones and Regions
2.4. Standalone Mode
2.5. Peer Awareness
2.6. When to Prefer IP Address
2.7. Securing The Eureka Server
3. Circuit Breaker: Hystrix Clients
3.1. How to Include Hystrix
3.2. Propagating the Security Context or Using Spring Scopes
3.3. Health Indicator
3.4. Hystrix Metrics Stream
4. Circuit Breaker: Hystrix Dashboard
5. Hystrix Timeouts And Ribbon Clients
5.1. How to Include the Hystrix Dashboard
5.2. Turbine
5.2.1. Clusters Endpoint
5.3. Turbine Stream
6. Client Side Load Balancer: Ribbon
6.1. How to Include Ribbon
6.2. Customizing the Ribbon Client
6.3. Customizing the Default for All Ribbon Clients
6.4. Customizing the Ribbon Client by Setting Properties
6.5. Using Ribbon with Eureka
6.6. Example: How to Use Ribbon Without Eureka
6.7. Example: Disable Eureka Use in Ribbon
6.8. Using the Ribbon API Directly
6.9. Caching of Ribbon Configuration
6.10. How to Configure Hystrix Thread Pools
6.11. How to Provide a Key to Ribbon’s IRule
7. External Configuration: Archaius
8. Router and Filter: Zuul
8.1. How to Include Zuul
8.2. Embedded Zuul Reverse Proxy
8.3. Zuul Http Client
8.4. Cookies and Sensitive Headers
8.5. Ignored Headers
8.6. Management Endpoints
8.6.1. Routes Endpoint
8.6.2. Filters Endpoint
8.7. Strangulation Patterns and Local Forwards
8.8. Uploading Files through Zuul
8.9. Query String Encoding
8.10. Plain Embedded Zuul
8.11. Disable Zuul Filters
8.12. Providing Hystrix Fallbacks For Routes
8.13. Zuul Timeouts
8.14. Rewriting the Location header
8.15. Metrics
8.16. Zuul Developer Guide
8.16.1. The Zuul Servlet
8.16.2. Zuul RequestContext
8.16.3. @EnableZuulProxy vs. @EnableZuulServer
8.16.4. @EnableZuulServer Filters
8.16.5. @EnableZuulProxy Filters
8.16.6. Custom Zuul Filter Examples
How to Write a Pre Filter
How to Write a Route Filter
How to Write a Post Filter
8.16.7. How Zuul Errors Work
8.16.8. Zuul Eager Application Context Loading
9. Polyglot support with Sidecar
10. Retrying Failed Requests
10.1. BackOff Policies
10.2. Configuration
10.2.1. Zuul
11. HTTP Clients
   Next
   

\ No newline at end of file
+   Spring Cloud Netflix
Spring Cloud Netflix
   Next
Spring Cloud Netflix
Table of Contents
1. Service Discovery: Eureka Clients
1.1. How to Include Eureka Client
1.2. Registering with Eureka
1.3. Authenticating with the Eureka Server
1.4. Status Page and Health Indicator
1.5. Registering a Secure Application
1.6. Eureka’s Health Checks
1.7. Eureka Metadata for Instances and Clients
1.7.1. Using Eureka on Cloud Foundry
1.7.2. Using Eureka on AWS
1.7.3. Changing the Eureka Instance ID
1.8. Using the EurekaClient
1.8.1. EurekaClient without Jersey
1.9. Alternatives to the Native Netflix EurekaClient
1.10. Why Is It so Slow to Register a Service?
1.11. Zones
2. Service Discovery: Eureka Server
2.1. How to Include Eureka Server
2.2. How to Run a Eureka Server
2.3. High Availability, Zones and Regions
2.4. Standalone Mode
2.5. Peer Awareness
2.6. When to Prefer IP Address
2.7. Securing The Eureka Server
3. Circuit Breaker: Hystrix Clients
3.1. How to Include Hystrix
3.2. Propagating the Security Context or Using Spring Scopes
3.3. Health Indicator
3.4. Hystrix Metrics Stream
4. Circuit Breaker: Hystrix Dashboard
5. Hystrix Timeouts And Ribbon Clients
5.1. How to Include the Hystrix Dashboard
5.2. Turbine
5.2.1. Clusters Endpoint
5.3. Turbine Stream
6. Client Side Load Balancer: Ribbon
6.1. How to Include Ribbon
6.2. Customizing the Ribbon Client
6.3. Customizing the Default for All Ribbon Clients
6.4. Customizing the Ribbon Client by Setting Properties
6.5. Using Ribbon with Eureka
6.6. Example: How to Use Ribbon Without Eureka
6.7. Example: Disable Eureka Use in Ribbon
6.8. Using the Ribbon API Directly
6.9. Caching of Ribbon Configuration
6.10. How to Configure Hystrix Thread Pools
6.11. How to Provide a Key to Ribbon’s IRule
7. External Configuration: Archaius
8. Router and Filter: Zuul
8.1. How to Include Zuul
8.2. Embedded Zuul Reverse Proxy
8.3. Zuul Http Client
8.4. Cookies and Sensitive Headers
8.5. Ignored Headers
8.6. Management Endpoints
8.6.1. Routes Endpoint
8.6.2. Filters Endpoint
8.7. Strangulation Patterns and Local Forwards
8.8. Uploading Files through Zuul
8.9. Query String Encoding
8.10. Plain Embedded Zuul
8.11. Disable Zuul Filters
8.12. Providing Hystrix Fallbacks For Routes
8.13. Zuul Timeouts
8.14. Rewriting the Location header
8.15. Enabling Cross Origin Requests
8.16. Metrics
8.17. Zuul Developer Guide
8.17.1. The Zuul Servlet
8.17.2. Zuul RequestContext
8.17.3. @EnableZuulProxy vs. @EnableZuulServer
8.17.4. @EnableZuulServer Filters
8.17.5. @EnableZuulProxy Filters
8.17.6. Custom Zuul Filter Examples
How to Write a Pre Filter
How to Write a Route Filter
How to Write a Post Filter
8.17.7. How Zuul Errors Work
8.17.8. Zuul Eager Application Context Loading
9. Polyglot support with Sidecar
10. Retrying Failed Requests
10.1. BackOff Policies
10.2. Configuration
10.2.1. Zuul
11. HTTP Clients
   Next
   

\ No newline at end of file
diff --git a/single/spring-cloud-netflix.html b/single/spring-cloud-netflix.html
index 334def453..b33044aca 100644
--- a/single/spring-cloud-netflix.html
+++ b/single/spring-cloud-netflix.html
@@ -1,6 +1,6 @@
 
       
-   Spring Cloud Netflix
Spring Cloud Netflix
Table of Contents
1. Service Discovery: Eureka Clients
1.1. How to Include Eureka Client
1.2. Registering with Eureka
1.3. Authenticating with the Eureka Server
1.4. Status Page and Health Indicator
1.5. Registering a Secure Application
1.6. Eureka’s Health Checks
1.7. Eureka Metadata for Instances and Clients
1.7.1. Using Eureka on Cloud Foundry
1.7.2. Using Eureka on AWS
1.7.3. Changing the Eureka Instance ID
1.8. Using the EurekaClient
1.8.1. EurekaClient without Jersey
1.9. Alternatives to the Native Netflix EurekaClient
1.10. Why Is It so Slow to Register a Service?
1.11. Zones
2. Service Discovery: Eureka Server
2.1. How to Include Eureka Server
2.2. How to Run a Eureka Server
2.3. High Availability, Zones and Regions
2.4. Standalone Mode
2.5. Peer Awareness
2.6. When to Prefer IP Address
2.7. Securing The Eureka Server
3. Circuit Breaker: Hystrix Clients
3.1. How to Include Hystrix
3.2. Propagating the Security Context or Using Spring Scopes
3.3. Health Indicator
3.4. Hystrix Metrics Stream
4. Circuit Breaker: Hystrix Dashboard
5. Hystrix Timeouts And Ribbon Clients
5.1. How to Include the Hystrix Dashboard
5.2. Turbine
5.2.1. Clusters Endpoint
5.3. Turbine Stream
6. Client Side Load Balancer: Ribbon
6.1. How to Include Ribbon
6.2. Customizing the Ribbon Client
6.3. Customizing the Default for All Ribbon Clients
6.4. Customizing the Ribbon Client by Setting Properties
6.5. Using Ribbon with Eureka
6.6. Example: How to Use Ribbon Without Eureka
6.7. Example: Disable Eureka Use in Ribbon
6.8. Using the Ribbon API Directly
6.9. Caching of Ribbon Configuration
6.10. How to Configure Hystrix Thread Pools
6.11. How to Provide a Key to Ribbon’s IRule
7. External Configuration: Archaius
8. Router and Filter: Zuul
8.1. How to Include Zuul
8.2. Embedded Zuul Reverse Proxy
8.3. Zuul Http Client
8.4. Cookies and Sensitive Headers
8.5. Ignored Headers
8.6. Management Endpoints
8.6.1. Routes Endpoint
8.6.2. Filters Endpoint
8.7. Strangulation Patterns and Local Forwards
8.8. Uploading Files through Zuul
8.9. Query String Encoding
8.10. Plain Embedded Zuul
8.11. Disable Zuul Filters
8.12. Providing Hystrix Fallbacks For Routes
8.13. Zuul Timeouts
8.14. Rewriting the Location header
8.15. Metrics
8.16. Zuul Developer Guide
8.16.1. The Zuul Servlet
8.16.2. Zuul RequestContext
8.16.3. @EnableZuulProxy vs. @EnableZuulServer
8.16.4. @EnableZuulServer Filters
8.16.5. @EnableZuulProxy Filters
8.16.6. Custom Zuul Filter Examples
How to Write a Pre Filter
How to Write a Route Filter
How to Write a Post Filter
8.16.7. How Zuul Errors Work
8.16.8. Zuul Eager Application Context Loading
9. Polyglot support with Sidecar
10. Retrying Failed Requests
10.1. BackOff Policies
10.2. Configuration
10.2.1. Zuul
11. HTTP Clients
2.1.0.BUILD-SNAPSHOT
This project provides Netflix OSS integrations for Spring Boot apps through autoconfiguration
+   Spring Cloud Netflix
Spring Cloud Netflix
Table of Contents
1. Service Discovery: Eureka Clients
1.1. How to Include Eureka Client
1.2. Registering with Eureka
1.3. Authenticating with the Eureka Server
1.4. Status Page and Health Indicator
1.5. Registering a Secure Application
1.6. Eureka’s Health Checks
1.7. Eureka Metadata for Instances and Clients
1.7.1. Using Eureka on Cloud Foundry
1.7.2. Using Eureka on AWS
1.7.3. Changing the Eureka Instance ID
1.8. Using the EurekaClient
1.8.1. EurekaClient without Jersey
1.9. Alternatives to the Native Netflix EurekaClient
1.10. Why Is It so Slow to Register a Service?
1.11. Zones
2. Service Discovery: Eureka Server
2.1. How to Include Eureka Server
2.2. How to Run a Eureka Server
2.3. High Availability, Zones and Regions
2.4. Standalone Mode
2.5. Peer Awareness
2.6. When to Prefer IP Address
2.7. Securing The Eureka Server
3. Circuit Breaker: Hystrix Clients
3.1. How to Include Hystrix
3.2. Propagating the Security Context or Using Spring Scopes
3.3. Health Indicator
3.4. Hystrix Metrics Stream
4. Circuit Breaker: Hystrix Dashboard
5. Hystrix Timeouts And Ribbon Clients
5.1. How to Include the Hystrix Dashboard
5.2. Turbine
5.2.1. Clusters Endpoint
5.3. Turbine Stream
6. Client Side Load Balancer: Ribbon
6.1. How to Include Ribbon
6.2. Customizing the Ribbon Client
6.3. Customizing the Default for All Ribbon Clients
6.4. Customizing the Ribbon Client by Setting Properties
6.5. Using Ribbon with Eureka
6.6. Example: How to Use Ribbon Without Eureka
6.7. Example: Disable Eureka Use in Ribbon
6.8. Using the Ribbon API Directly
6.9. Caching of Ribbon Configuration
6.10. How to Configure Hystrix Thread Pools
6.11. How to Provide a Key to Ribbon’s IRule
7. External Configuration: Archaius
8. Router and Filter: Zuul
8.1. How to Include Zuul
8.2. Embedded Zuul Reverse Proxy
8.3. Zuul Http Client
8.4. Cookies and Sensitive Headers
8.5. Ignored Headers
8.6. Management Endpoints
8.6.1. Routes Endpoint
8.6.2. Filters Endpoint
8.7. Strangulation Patterns and Local Forwards
8.8. Uploading Files through Zuul
8.9. Query String Encoding
8.10. Plain Embedded Zuul
8.11. Disable Zuul Filters
8.12. Providing Hystrix Fallbacks For Routes
8.13. Zuul Timeouts
8.14. Rewriting the Location header
8.15. Enabling Cross Origin Requests
8.16. Metrics
8.17. Zuul Developer Guide
8.17.1. The Zuul Servlet
8.17.2. Zuul RequestContext
8.17.3. @EnableZuulProxy vs. @EnableZuulServer
8.17.4. @EnableZuulServer Filters
8.17.5. @EnableZuulProxy Filters
8.17.6. Custom Zuul Filter Examples
How to Write a Pre Filter
How to Write a Route Filter
How to Write a Post Filter
8.17.7. How Zuul Errors Work
8.17.8. Zuul Eager Application Context Loading
9. Polyglot support with Sidecar
10. Retrying Failed Requests
10.1. BackOff Policies
10.2. Configuration
10.2.1. Zuul
11. HTTP Clients
2.1.0.BUILD-SNAPSHOT
This project provides Netflix OSS integrations for Spring Boot apps through autoconfiguration
 and binding to the Spring Environment and other Spring programming model idioms. With a few
 simple annotations you can quickly enable and configure the common patterns inside your
 application and build large distributed systems with battle-tested Netflix components. The
@@ -837,17 +837,28 @@ The following example adds a filter by using a Spring Configuration file:
public LocationRewriteFilter locationRewriteFilter() {
         return new LocationRewriteFilter();
     }
-}
[Caution]Caution
Use this filter carefully. The filter acts on the Location header of ALL 3XX response codes, which may not be appropriate in all scenarios, such as when redirecting the user to an external URL.

8.15 Metrics

Zuul will provide metrics under the Actuator metrics endpoint for any failures that might occur when routing requests. +}

[Caution]Caution

Use this filter carefully. The filter acts on the Location header of ALL 3XX response codes, which may not be appropriate in all scenarios, such as when redirecting the user to an external URL.

8.15 Enabling Cross Origin Requests

By default Zuul routes all Cross Origin requests (CORS) to the services. If you want instead Zuul to handle these requests it can be done by providing custom WebMvcConfigurer bean:

@Bean
+public WebMvcConfigurer corsConfigurer() {
+    return new WebMvcConfigurer() {
+        public void addCorsMappings(CorsRegistry registry) {
+            registry.addMapping("/path-1/**")
+                    .allowedOrigins("http://allowed-origin.com")
+                    .allowedMethods("GET", "POST");
+        }
+    };
+}

In the example above, we allow GET and POST methods from http://allowed-origin.com to send cross-origin requests to the endpoints starting with path-1. +You can apply CORS configuration to a specific path pattern or globally for the whole application, using /** mapping. +You can customize properties: allowedOrigins,allowedMethods,allowedHeaders,exposedHeaders,allowCredentials and maxAge via this configuration.

8.16 Metrics

Zuul will provide metrics under the Actuator metrics endpoint for any failures that might occur when routing requests. These metrics can be viewed by hitting /actuator/metrics. The metrics will have a name that has the format -ZUUL::EXCEPTION:errorCause:statusCode.

8.16 Zuul Developer Guide

For a general overview of how Zuul works, see the Zuul Wiki.

8.16.1 The Zuul Servlet

Zuul is implemented as a Servlet. For the general cases, Zuul is embedded into the Spring Dispatch mechanism. This lets Spring MVC be in control of the routing. +ZUUL::EXCEPTION:errorCause:statusCode.

8.17 Zuul Developer Guide

For a general overview of how Zuul works, see the Zuul Wiki.

8.17.1 The Zuul Servlet

Zuul is implemented as a Servlet. For the general cases, Zuul is embedded into the Spring Dispatch mechanism. This lets Spring MVC be in control of the routing. In this case, Zuul buffers requests. If there is a need to go through Zuul without buffering requests (for example, for large file uploads), the Servlet is also installed outside of the Spring Dispatcher. By default, the servlet has an address of /zuul. -This path can be changed with the zuul.servlet-path property.

8.16.2 Zuul RequestContext

To pass information between filters, Zuul uses a RequestContext. +This path can be changed with the zuul.servlet-path property.

8.17.2 Zuul RequestContext

To pass information between filters, Zuul uses a RequestContext. Its data is held in a ThreadLocal specific to each request. Information about where to route requests, errors, and the actual HttpServletRequest and HttpServletResponse are stored there. -The RequestContext extends ConcurrentHashMap, so anything can be stored in the context. FilterConstants contains the keys used by the filters installed by Spring Cloud Netflix (more on these later).

8.16.3 @EnableZuulProxy vs. @EnableZuulServer

Spring Cloud Netflix installs a number of filters, depending on which annotation was used to enable Zuul. @EnableZuulProxy is a superset of @EnableZuulServer. In other words, @EnableZuulProxy contains all the filters installed by @EnableZuulServer. The additional filters in the “proxy” enable routing functionality. If you want a “blank” Zuul, you should use @EnableZuulServer.

8.16.4 @EnableZuulServer Filters

@EnableZuulServer creates a SimpleRouteLocator that loads route definitions from Spring Boot configuration files.

The following filters are installed (as normal Spring Beans):

  • Pre filters:

    • ServletDetectionFilter: Detects whether the request is through the Spring Dispatcher. Sets a boolean with a key of FilterConstants.IS_DISPATCHER_SERVLET_REQUEST_KEY.
    • FormBodyWrapperFilter: Parses form data and re-encodes it for downstream requests.
    • DebugFilter: If the debug request parameter is set, sets RequestContext.setDebugRouting() and RequestContext.setDebugRequest() to true. -*Route filters:
    • SendForwardFilter: Forwards requests by using the Servlet RequestDispatcher. The forwarding location is stored in the RequestContext attribute, FilterConstants.FORWARD_TO_KEY. This is useful for forwarding to endpoints in the current application.

  • Post filters:

    • SendResponseFilter: Writes responses from proxied requests to the current response.

  • Error filters:

    • SendErrorFilter: Forwards to /error (by default) if RequestContext.getThrowable() is not null. You can change the default forwarding path (/error) by setting the error.path property.

8.16.5 @EnableZuulProxy Filters

Creates a DiscoveryClientRouteLocator that loads route definitions from a DiscoveryClient (such as Eureka) as well as from properties. A route is created for each serviceId from the DiscoveryClient. As new services are added, the routes are refreshed.

In addition to the filters described earlier, the following filters are installed (as normal Spring Beans):

  • Pre filters:

    • PreDecorationFilter: Determines where and how to route, depending on the supplied RouteLocator. It also sets various proxy-related headers for downstream requests.

  • Route filters:

    • RibbonRoutingFilter: Uses Ribbon, Hystrix, and pluggable HTTP clients to send requests. Service IDs are found in the RequestContext attribute, FilterConstants.SERVICE_ID_KEY. This filter can use different HTTP clients:

      • Apache HttpClient: The default client.
      • Squareup OkHttpClient v3: Enabled by having the com.squareup.okhttp3:okhttp library on the classpath and setting ribbon.okhttp.enabled=true.
      • Netflix Ribbon HTTP client: Enabled by setting ribbon.restclient.enabled=true. This client has limitations, including that it does not support the PATCH method, but it also has built-in retry.
    • SimpleHostRoutingFilter: Sends requests to predetermined URLs through an Apache HttpClient. URLs are found in RequestContext.getRouteHost().

8.16.6 Custom Zuul Filter Examples

Most of the following "How to Write" examples below are included Sample Zuul Filters project. There are also examples of manipulating the request or response body in that repository.

This section includes the following examples:

How to Write a Pre Filter

Pre filters set up data in the RequestContext for use in filters downstream. +The RequestContext extends ConcurrentHashMap, so anything can be stored in the context. FilterConstants contains the keys used by the filters installed by Spring Cloud Netflix (more on these later).

8.17.3 @EnableZuulProxy vs. @EnableZuulServer

Spring Cloud Netflix installs a number of filters, depending on which annotation was used to enable Zuul. @EnableZuulProxy is a superset of @EnableZuulServer. In other words, @EnableZuulProxy contains all the filters installed by @EnableZuulServer. The additional filters in the “proxy” enable routing functionality. If you want a “blank” Zuul, you should use @EnableZuulServer.

8.17.4 @EnableZuulServer Filters

@EnableZuulServer creates a SimpleRouteLocator that loads route definitions from Spring Boot configuration files.

The following filters are installed (as normal Spring Beans):

  • Pre filters:

    • ServletDetectionFilter: Detects whether the request is through the Spring Dispatcher. Sets a boolean with a key of FilterConstants.IS_DISPATCHER_SERVLET_REQUEST_KEY.
    • FormBodyWrapperFilter: Parses form data and re-encodes it for downstream requests.
    • DebugFilter: If the debug request parameter is set, sets RequestContext.setDebugRouting() and RequestContext.setDebugRequest() to true. +*Route filters:
    • SendForwardFilter: Forwards requests by using the Servlet RequestDispatcher. The forwarding location is stored in the RequestContext attribute, FilterConstants.FORWARD_TO_KEY. This is useful for forwarding to endpoints in the current application.

  • Post filters:

    • SendResponseFilter: Writes responses from proxied requests to the current response.

  • Error filters:

    • SendErrorFilter: Forwards to /error (by default) if RequestContext.getThrowable() is not null. You can change the default forwarding path (/error) by setting the error.path property.

8.17.5 @EnableZuulProxy Filters

Creates a DiscoveryClientRouteLocator that loads route definitions from a DiscoveryClient (such as Eureka) as well as from properties. A route is created for each serviceId from the DiscoveryClient. As new services are added, the routes are refreshed.

In addition to the filters described earlier, the following filters are installed (as normal Spring Beans):

  • Pre filters:

    • PreDecorationFilter: Determines where and how to route, depending on the supplied RouteLocator. It also sets various proxy-related headers for downstream requests.

  • Route filters:

    • RibbonRoutingFilter: Uses Ribbon, Hystrix, and pluggable HTTP clients to send requests. Service IDs are found in the RequestContext attribute, FilterConstants.SERVICE_ID_KEY. This filter can use different HTTP clients:

      • Apache HttpClient: The default client.
      • Squareup OkHttpClient v3: Enabled by having the com.squareup.okhttp3:okhttp library on the classpath and setting ribbon.okhttp.enabled=true.
      • Netflix Ribbon HTTP client: Enabled by setting ribbon.restclient.enabled=true. This client has limitations, including that it does not support the PATCH method, but it also has built-in retry.
    • SimpleHostRoutingFilter: Sends requests to predetermined URLs through an Apache HttpClient. URLs are found in RequestContext.getRouteHost().

8.17.6 Custom Zuul Filter Examples

Most of the following "How to Write" examples below are included Sample Zuul Filters project. There are also examples of manipulating the request or response body in that repository.

This section includes the following examples:

How to Write a Pre Filter

Pre filters set up data in the RequestContext for use in filters downstream. The main use case is to set information required for route filters. The following example shows a Zuul pre filter:

public class QueryParamPreFilter extends ZuulFilter {
 	@Override
@@ -976,9 +987,9 @@ The following example shows a Zuul route filter:
 		servletResponse.addHeader("X-Sample", UUID.randomUUID().toString());
 		return null;
 	}
-}
[Note]Note
Other manipulations, such as transforming the response body, are much more complex and computationally intensive.

8.16.7 How Zuul Errors Work

If an exception is thrown during any portion of the Zuul filter lifecycle, the error filters are executed. +}

[Note]Note

Other manipulations, such as transforming the response body, are much more complex and computationally intensive.

8.17.7 How Zuul Errors Work

If an exception is thrown during any portion of the Zuul filter lifecycle, the error filters are executed. The SendErrorFilter is only run if RequestContext.getThrowable() is not null. -It then sets specific javax.servlet.error.* attributes in the request and forwards the request to the Spring Boot error page.

8.16.8 Zuul Eager Application Context Loading

Zuul internally uses Ribbon for calling the remote URLs. +It then sets specific javax.servlet.error.* attributes in the request and forwards the request to the Spring Boot error page.

8.17.8 Zuul Eager Application Context Loading

Zuul internally uses Ribbon for calling the remote URLs. By default, Ribbon clients are lazily loaded by Spring Cloud on first call. This behavior can be changed for Zuul by using the following configuration, which results eager loading of the child Ribbon related Application contexts at application startup time. The following example shows how to enable eager loading:

application.yml.  @@ -1041,17 +1052,17 @@ might result in a YAML document resembling the following:

  password: password
 info:
   description: Spring Cloud Samples
-  url: https://github.com/spring-cloud-samples

10. Retrying Failed Requests

Spring Cloud Netflix offers a variety of ways to make HTTP requests. + url: https://github.com/spring-cloud-samples

To enable the health check request to accept all certificates when using HTTPs set sidecar.accept-all-ssl-certificates to `true.

10. Retrying Failed Requests

Spring Cloud Netflix offers a variety of ways to make HTTP requests. You can use a load balanced RestTemplate, Ribbon, or Feign. No matter how you choose to create your HTTP requests, there is always a chance that a request may fail. When a request fails, you may want to have the request be retried automatically. To do so when using Sping Cloud Netflix, you need to include Spring Retry on your application’s classpath. When Spring Retry is present, load-balanced RestTemplates, Feign, and Zuul automatically retry any failed requests (assuming your configuration allows doing so).

10.1 BackOff Policies

By default, no backoff policy is used when retrying requests. -If you would like to configure a backoff policy, you need to create a bean of type LoadBalancedBackOffPolicyFactory, which is used to create a BackOffPolicy for a given service, as shown in the following example:

@Configuration
+If you would like to configure a backoff policy, you need to create a bean of type LoadBalancedRetryFactory and override the createBackOffPolicy method for a given service, as shown in the following example:
@Configuration
 public class MyConfiguration {
     @Bean
-    LoadBalancedBackOffPolicyFactory backOffPolicyFactory() {
-        return new LoadBalancedBackOffPolicyFactory() {
+    LoadBalancedRetryFactory retryFactory() {
+        return new LoadBalancedRetryFactory() {
             @Override
             public BackOffPolicy createBackOffPolicy(String service) {
                 return new ExponentialBackOffPolicy();
diff --git a/spring-cloud-netflix.xml b/spring-cloud-netflix.xml
index 71e8bc078..80c2b1c7e 100644
--- a/spring-cloud-netflix.xml
+++ b/spring-cloud-netflix.xml
@@ -1614,6 +1614,23 @@ public class ZuulConfig {
 Use this filter carefully. The filter acts on the Location header of ALL 3XX response codes, which may not be appropriate in all scenarios, such as when redirecting the user to an external URL.
 
 
+

+Enabling Cross Origin Requests
+By default Zuul routes all Cross Origin requests (CORS) to the services. If you want instead Zuul to handle these requests it can be done by providing custom WebMvcConfigurer bean:
+@Bean
+public WebMvcConfigurer corsConfigurer() {
+    return new WebMvcConfigurer() {
+        public void addCorsMappings(CorsRegistry registry) {
+            registry.addMapping("/path-1/**")
+                    .allowedOrigins("http://allowed-origin.com")
+                    .allowedMethods("GET", "POST");
+        }
+    };
+}
+In the example above, we allow GET and POST methods from http://allowed-origin.com to send cross-origin requests to the endpoints starting with path-1.
+You can apply CORS configuration to a specific path pattern or globally for the whole application, using /** mapping.
+You can customize properties: allowedOrigins,allowedMethods,allowedHeaders,exposedHeaders,allowCredentials and maxAge via this configuration.
+

 

 Metrics
 Zuul will provide metrics under the Actuator metrics endpoint for any failures that might occur when routing requests.
@@ -1994,6 +2011,7 @@ might result in a YAML document resembling the following:
 info:
   description: Spring Cloud Samples
   url: https://github.com/spring-cloud-samples
+To enable the health check request to accept all certificates when using HTTPs set sidecar.accept-all-ssl-certificates to `true.
 
 
 Retrying Failed Requests
@@ -2006,12 +2024,12 @@ When Spring Retry is present, load-balanced RestTemplates, Fe
 

 BackOff Policies
 By default, no backoff policy is used when retrying requests.
-If you would like to configure a backoff policy, you need to create a bean of type LoadBalancedBackOffPolicyFactory, which is used to create a BackOffPolicy for a given service, as shown in the following example:
+If you would like to configure a backoff policy, you need to create a bean of type LoadBalancedRetryFactory and override the createBackOffPolicy method for a given service, as shown in the following example:
 @Configuration
 public class MyConfiguration {
     @Bean
-    LoadBalancedBackOffPolicyFactory backOffPolicyFactory() {
-        return new LoadBalancedBackOffPolicyFactory() {
+    LoadBalancedRetryFactory retryFactory() {
+        return new LoadBalancedRetryFactory() {
             @Override
             public BackOffPolicy createBackOffPolicy(String service) {
                 return new ExponentialBackOffPolicy();