diff --git a/reference/html/index.html b/reference/html/index.html index ce0d24eb..26274f79 100644 --- a/reference/html/index.html +++ b/reference/html/index.html @@ -157,15 +157,16 @@ $(addBlockSwitches);
  • 3. Spring Cloud LoadBalancer
  • 4. Spring Cloud Circuit Breaker @@ -1413,9 +1414,8 @@ that retrieves available instances from Service Discovery using a

    3.1. Spring Cloud LoadBalancer integrations

    -

    In order to make it easy to use Spring Cloud LoadBalancer, we provide ReactorLoadBalancerExchangeFilterFunction that can be used -with WebClient and BlockingLoadBalancerClient that works with RestTemplate. You can see more information and examples of usage -in the following sections:

    +

    In order to make it easy to use Spring Cloud LoadBalancer, we provide ReactorLoadBalancerExchangeFilterFunction that can be used with WebClient and BlockingLoadBalancerClient that works with RestTemplate. +You can see more information and examples of usage in the following sections:

    -

    3.2. Spring Cloud LoadBalancer Caching

    +

    3.2. Spring Cloud LoadBalancer Caching

    Apart from the basic ServiceInstanceListSupplier implementation that retrieves instances via DiscoveryClient each time it has to choose an instance, we provide two caching implementations.

    @@ -1490,8 +1490,7 @@ to false.

    -Although the basic, non-cached, implementation is useful for prototyping and testing, it’s much less efficient -than the cached versions, so we recommend always using the cached version in production. +Although the basic, non-cached, implementation is useful for prototyping and testing, it’s much less efficient than the cached versions, so we recommend always using the cached version in production. @@ -1499,11 +1498,79 @@ than the cached versions, so we recommend always using the cached version in pro
    -

    3.3. Spring Cloud LoadBalancer Starter

    +

    3.3. Zone-Based Load-Balancing

    +
    +

    To enable zone-based load-balancing, we provide the ZonePreferenceServiceInstanceListSupplier. +We use DiscoveryClient-specific zone configuration (for example, eureka.instance.metadata-map.zone) to pick the zone that the client tries to filter available service instances for.

    +
    +
    + + + + + +
    + + +You can also override DiscoveryClient-specific zone setup by setting the value of spring.cloud.loadbalancer.zone property. +
    +
    +
    + + + + + +
    + + +To determine the zone of a retrieved ServiceInstance, we check the value under the "zone" key in its metadata map. +
    +
    +
    +

    The ZonePreferenceServiceInstanceListSupplier filters retrieved instances and only returns the ones within the same zone. +If the zone is null or there are no instances within the same zone, it returns all the retrieved instances.

    +
    +
    +

    In order to use the zone-based load-balancing approach, you will have to instantiate a ZonePreferenceServiceInstanceListSupplier bean in a custom configuration.

    +
    +
    +

    We use delegates to work with ServiceInstanceListSupplier beans. +We suggest passing a DiscoveryClientServiceInstanceListSupplier delegate in the constructor of ZonePreferenceServiceInstanceListSupplier and, in turn, wrapping the latter with a CachingServiceInstanceListSupplier to leverage LoadBalancer caching mechanism.

    +
    +
    +

    You could use this sample configuration to set it up:

    +
    +
    +
    +
    public class CustomLoadBalancerConfiguration {
+
+    @Bean
+    public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+            ReactiveDiscoveryClient discoveryClient, Environment environment,
+            ApplicationContext context) {
+        DiscoveryClientServiceInstanceListSupplier firstDelegate = new DiscoveryClientServiceInstanceListSupplier(
+                discoveryClient, environment);
+        ZonePreferenceServiceInstanceListSupplier delegate = new ZonePreferenceServiceInstanceListSupplier(firstDelegate,
+                environment);
+        ObjectProvider<LoadBalancerCacheManager> cacheManagerProvider = context
+                .getBeanProvider(LoadBalancerCacheManager.class);
+        if (cacheManagerProvider.getIfAvailable() != null) {
+            return new CachingServiceInstanceListSupplier(delegate,
+                    cacheManagerProvider.getIfAvailable());
+        }
+        return delegate;
+    }
+
+}
    +
    +
    +
    +
    +

    3.4. Spring Cloud LoadBalancer Starter

    We also provide a starter that allows you to easily add Spring Cloud LoadBalancer in a Spring Boot app. -In order to use it, just add org.springframework.cloud:spring-cloud-starter-loadbalancer to your Spring -Cloud dependencies in your build file.

    +In order to use it, just add org.springframework.cloud:spring-cloud-starter-loadbalancer to your Spring Cloud dependencies in your build file.

    @@ -1526,17 +1593,15 @@ and Evictor.
    -If you have both Ribbon and Spring Cloud LoadBalancer int the classpath, in order to maintain -backward compatibility, Ribbon-based implementations will be used by default. In order -to switch to using Spring Cloud LoadBalancer under the hood, -make sure you set the property spring.cloud.loadbalancer.ribbon.enabled to false. +If you have both Ribbon and Spring Cloud LoadBalancer int the classpath, in order to maintain backward compatibility, Ribbon-based implementations will be used by default. +In order to switch to using Spring Cloud LoadBalancer under the hood, make sure you set the property spring.cloud.loadbalancer.ribbon.enabled to false.
    -

    3.4. Passing Your Own Spring Cloud LoadBalancer Configuration

    +

    3.5. Passing Your Own Spring Cloud LoadBalancer Configuration

    You can also use the @LoadBalancerClient annotation to pass your own load-balancer client configuration, passing the name of the load-balancer client and the configuration class, as follows:

    @@ -1545,7 +1610,7 @@ make sure you set the property spring.cloud.loadbalancer.ribbon.enabled 
    @Configuration
-@LoadBalancerClient(value = "stores", configuration = StoresLoadBalancerClientConfiguration.class)
+@LoadBalancerClient(value = "stores", configuration = CustomLoadBalancerConfiguration.class)
 public class MyConfiguration {
 
     @Bean
@@ -1559,6 +1624,25 @@ public class MyConfiguration {
    +

    You can use this feature to instantiate different implementations of ServiceInstanceListSupplier or ReactorLoadBalancer, +either written by you, or provided by us as alternatives (for example ZonePreferenceServiceInstanceListSupplier) to override the default setup.

    +
    +
    +

    You can see an example of a custom cofiguration here.

    +
    +
    + + + + + +
    + + +The annotation value arguments (stores in the example above) specifies the service id of the service that we should send the requests to with the given custom configuration. +
    +
    +

    You can also pass multiple configurations (for more than one load-balancer client) through the @LoadBalancerClients annotation, as the following example shows:

    diff --git a/reference/html/spring-cloud-commons.html b/reference/html/spring-cloud-commons.html index ce0d24eb..26274f79 100644 --- a/reference/html/spring-cloud-commons.html +++ b/reference/html/spring-cloud-commons.html @@ -157,15 +157,16 @@ $(addBlockSwitches);
  • 3. Spring Cloud LoadBalancer
  • 4. Spring Cloud Circuit Breaker @@ -1413,9 +1414,8 @@ that retrieves available instances from Service Discovery using a

    3.1. Spring Cloud LoadBalancer integrations

    -

    In order to make it easy to use Spring Cloud LoadBalancer, we provide ReactorLoadBalancerExchangeFilterFunction that can be used -with WebClient and BlockingLoadBalancerClient that works with RestTemplate. You can see more information and examples of usage -in the following sections:

    +

    In order to make it easy to use Spring Cloud LoadBalancer, we provide ReactorLoadBalancerExchangeFilterFunction that can be used with WebClient and BlockingLoadBalancerClient that works with RestTemplate. +You can see more information and examples of usage in the following sections:

      @@ -1432,7 +1432,7 @@ in the following sections:

    -

    3.2. Spring Cloud LoadBalancer Caching

    +

    3.2. Spring Cloud LoadBalancer Caching

    Apart from the basic ServiceInstanceListSupplier implementation that retrieves instances via DiscoveryClient each time it has to choose an instance, we provide two caching implementations.

    @@ -1490,8 +1490,7 @@ to false.

    -Although the basic, non-cached, implementation is useful for prototyping and testing, it’s much less efficient -than the cached versions, so we recommend always using the cached version in production. +Although the basic, non-cached, implementation is useful for prototyping and testing, it’s much less efficient than the cached versions, so we recommend always using the cached version in production. @@ -1499,11 +1498,79 @@ than the cached versions, so we recommend always using the cached version in pro
    -

    3.3. Spring Cloud LoadBalancer Starter

    +

    3.3. Zone-Based Load-Balancing

    +
    +

    To enable zone-based load-balancing, we provide the ZonePreferenceServiceInstanceListSupplier. +We use DiscoveryClient-specific zone configuration (for example, eureka.instance.metadata-map.zone) to pick the zone that the client tries to filter available service instances for.

    +
    +
    + + + + + +
    + + +You can also override DiscoveryClient-specific zone setup by setting the value of spring.cloud.loadbalancer.zone property. +
    +
    +
    + + + + + +
    + + +To determine the zone of a retrieved ServiceInstance, we check the value under the "zone" key in its metadata map. +
    +
    +
    +

    The ZonePreferenceServiceInstanceListSupplier filters retrieved instances and only returns the ones within the same zone. +If the zone is null or there are no instances within the same zone, it returns all the retrieved instances.

    +
    +
    +

    In order to use the zone-based load-balancing approach, you will have to instantiate a ZonePreferenceServiceInstanceListSupplier bean in a custom configuration.

    +
    +
    +

    We use delegates to work with ServiceInstanceListSupplier beans. +We suggest passing a DiscoveryClientServiceInstanceListSupplier delegate in the constructor of ZonePreferenceServiceInstanceListSupplier and, in turn, wrapping the latter with a CachingServiceInstanceListSupplier to leverage LoadBalancer caching mechanism.

    +
    +
    +

    You could use this sample configuration to set it up:

    +
    +
    +
    +
    public class CustomLoadBalancerConfiguration {
+
+    @Bean
+    public ServiceInstanceListSupplier discoveryClientServiceInstanceListSupplier(
+            ReactiveDiscoveryClient discoveryClient, Environment environment,
+            ApplicationContext context) {
+        DiscoveryClientServiceInstanceListSupplier firstDelegate = new DiscoveryClientServiceInstanceListSupplier(
+                discoveryClient, environment);
+        ZonePreferenceServiceInstanceListSupplier delegate = new ZonePreferenceServiceInstanceListSupplier(firstDelegate,
+                environment);
+        ObjectProvider<LoadBalancerCacheManager> cacheManagerProvider = context
+                .getBeanProvider(LoadBalancerCacheManager.class);
+        if (cacheManagerProvider.getIfAvailable() != null) {
+            return new CachingServiceInstanceListSupplier(delegate,
+                    cacheManagerProvider.getIfAvailable());
+        }
+        return delegate;
+    }
+
+}
    +
    +
    +
    +
    +

    3.4. Spring Cloud LoadBalancer Starter

    We also provide a starter that allows you to easily add Spring Cloud LoadBalancer in a Spring Boot app. -In order to use it, just add org.springframework.cloud:spring-cloud-starter-loadbalancer to your Spring -Cloud dependencies in your build file.

    +In order to use it, just add org.springframework.cloud:spring-cloud-starter-loadbalancer to your Spring Cloud dependencies in your build file.

    @@ -1526,17 +1593,15 @@ and Evictor.
    -If you have both Ribbon and Spring Cloud LoadBalancer int the classpath, in order to maintain -backward compatibility, Ribbon-based implementations will be used by default. In order -to switch to using Spring Cloud LoadBalancer under the hood, -make sure you set the property spring.cloud.loadbalancer.ribbon.enabled to false. +If you have both Ribbon and Spring Cloud LoadBalancer int the classpath, in order to maintain backward compatibility, Ribbon-based implementations will be used by default. +In order to switch to using Spring Cloud LoadBalancer under the hood, make sure you set the property spring.cloud.loadbalancer.ribbon.enabled to false.
    -

    3.4. Passing Your Own Spring Cloud LoadBalancer Configuration

    +

    3.5. Passing Your Own Spring Cloud LoadBalancer Configuration

    You can also use the @LoadBalancerClient annotation to pass your own load-balancer client configuration, passing the name of the load-balancer client and the configuration class, as follows:

    @@ -1545,7 +1610,7 @@ make sure you set the property spring.cloud.loadbalancer.ribbon.enabled 
    @Configuration
-@LoadBalancerClient(value = "stores", configuration = StoresLoadBalancerClientConfiguration.class)
+@LoadBalancerClient(value = "stores", configuration = CustomLoadBalancerConfiguration.class)
 public class MyConfiguration {
 
     @Bean
@@ -1559,6 +1624,25 @@ public class MyConfiguration {
    +

    You can use this feature to instantiate different implementations of ServiceInstanceListSupplier or ReactorLoadBalancer, +either written by you, or provided by us as alternatives (for example ZonePreferenceServiceInstanceListSupplier) to override the default setup.

    +
    +
    +

    You can see an example of a custom cofiguration here.

    +
    +
    + + + + + +
    + + +The annotation value arguments (stores in the example above) specifies the service id of the service that we should send the requests to with the given custom configuration. +
    +
    +

    You can also pass multiple configurations (for more than one load-balancer client) through the @LoadBalancerClients annotation, as the following example shows: