Spring Cloud Ribbon discovery server filtering
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
src Corrected the typo in assert message Jun 11, 2016
.coveralls.yml Extended readme Nov 16, 2015
.java-version Initial source code commit Nov 15, 2015
.travis.yml Initial source code commit Nov 15, 2015
LICENSE Initial source code commit Nov 15, 2015
build.gradle Corrected the typo in assert message Jun 11, 2016
gradle.properties [Gradle Release Plugin] - new version commit: '2.1.1-SNAPSHOT'. Jun 11, 2016
gradlew Initial source code commit Nov 15, 2015
gradlew.bat Corrected the typo in assert message Jun 11, 2016


Spring Cloud Ribbon Discovery Server filter

A Spring Cloud Ribbon extension for filtering the server list.

Build Status Coverage Status


Allows to specify the criteria based on which the Ribbon load balanced servers lists will be chosen during runtime. It will affect the list of servers provided for instance through Eureka and allow to filter them based on presence of specific settings.


Add the Spring Cloud starter to your project:



The extension specifies a custom Ribbon rule - DiscoveryEnabledRule an abstract class through which you can provide your own filtering logic, currently it's only implementation is MetadataAwareRule that match the specified attribute against the registered service instance metadata map. The API allows to specify the expected attributes through RibbonFilterContextHolder at runtime.

The extension defines the glue code to perform the server filtering, but it's up to specific use case how exactly this is going to be used.


Let's consider situation when you have deployed multiple versions of the same application (by branching your codebase) overtime and you deploy and run them in your system simultaneously. You need to route your versioned requests towards correct services. A simple approach would be to prefix the name of your service like for instance recommendations-v1.0 or recommendations-v1.1 etc. This is going to work, but does not provide a very flexible solution. A more general approach would be to facilitate the metadata associated with your discovery service and add logic for filtering the services.

      version: 1.1
      variant: A

To route the Ribbon request towards services with specific metadataMap entries you need to populate the thread bound RibbonFilterContext:

                .add("version", "1.1")
                .add("variant", "A");

You can place such code in your application logic or in some more convenient place like for instance RestTemplate's ClientHttpRequestInterceptor for more generic approaches.

You may also provide your own custom logic, the only requirement is to implement and register instance of DiscoveryEnabledRule in your Spring application context.


Due to lack of proper abstraction in Spring Cloud, this extension is targeting only Netflix Eureka, it's not going to work if you will use Consul or Zookeeper as your Spring Cloud enabled discovery services.


You can disable the extension through ribbon.filter.metadata.enabled property.

ribbon.filter.metadata.enabled=true # true by default


Apache 2.0