Netflix Ribbon: a client side load balancer that is now in maintenance mode

The problem Ribbon solves for Java services that call other services

A service that calls another service has to decide which host to talk to, what to do when that host is slow or down, and how to avoid hammering it. Ribbon puts those decisions in the client. It is a client side IPC library, which means the calling process holds the server list, picks a server, and applies retries and fallbacks locally instead of delegating all of that to a proxy or a hardware load balancer.

The README lists four capabilities: load balancing, fault tolerance, multiple protocol support (HTTP, TCP, UDP) in an asynchronous and reactive model, and caching and batching. The audience is Java teams running many instances of a service in a cloud environment, where the set of healthy hosts changes and a static address in a config file goes stale.

Ribbon is not a general HTTP client. It is a layer that decides where a call goes and what happens when it fails. That distinction matters when you compare it with anything else.

Modules, server lists and the load balancer chain

The repository is split into modules, and the README gives each one a different level of attention. ribbon-core and ribbon-loadbalancer are described as deployed at scale in production. ribbon-eureka is also deployed at scale, and it supplies a dynamic server list from Eureka. ribbon-transport, ribbon-evcache, ribbon-guice and the top level ribbon module are listed as not used. ribbon-httpclient is deprecated and being replaced by ribbon. That is an unusual situation: the aggregating module is the one Netflix says it does not use.

The mechanism visible in the README is a chain. A ServerList provides candidate hosts, either from a static configuration or from Eureka. A ServerListFilter narrows that list, and the example uses ZoneAffinityServerListFilter to prefer hosts in the same zone. An IRule picks one, and the example uses AvailabilityFilteringRule. LoadBalancerBuilder assembles these into a ZoneAwareLoadBalancer. The README also shows a simpler path, where ClientOptions.create().withConfigurationBasedServerList("localhost:8080,localhost:8088") supplies a fixed list, and a separate path where LoadBalancerCommand wraps an arbitrary call, including a plain HttpURLConnection.

That last example is the clearest statement of scope. Ribbon can load balance a call it does not itself perform. You supply a LoadBalancerExecutable, receive a Server, and build the URL yourself.

The higher level API is template based. You create an HttpResourceGroup, then a template with a method, a URI template and a fallback provider. An annotation based variant lets you declare an interface with @Http and @Var and call Ribbon.from(MovieService.class) to get an implementation. Both return reactive types such as Observable.

Installing Ribbon from Maven Central and making a first call

The README does not describe a build from source. It points to Maven Central for binaries and gives a Maven dependency snippet. Note that the version in that snippet is 2.2.2, which is older than the releases listed on the repository, so treat it as an illustration of the coordinates rather than a version recommendation.

<dependency>
    <groupId>com.netflix.ribbon</groupId>
    <artifactId>ribbon</artifactId>
    <version>2.2.2</version>
</dependency>

With the dependency in place, the smallest useful setup is a resource group with a fixed list of servers. The README shows this fragment, which registers three retries against the next server and two hosts.

HttpResourceGroup httpResourceGroup = Ribbon.createHttpResourceGroup("movieServiceClient",
            ClientOptions.create()
                    .withMaxAutoRetriesNextServer(3)
                    .withConfigurationBasedServerList("localhost:8080,localhost:8088"));

Requests are then declared as templates. The README example binds a GET to a URI template with a userId placeholder and attaches a fallback provider.

HttpRequestTemplate<ByteBuf> recommendationsByUserIdTemplate = httpResourceGroup.newTemplateBuilder("recommendationsByUserId", ByteBuf.class)
            .withMethod("GET")
            .withUriTemplate("/users/{userId}/recommendations")
            .withFallbackProvider(new RecommendationServiceFallbackHandler())

What you should see is a client that alternates between localhost:8080 and localhost:8088, retries on the next server up to three times, and routes to the fallback handler when the call still fails. If you prefer an interface, the README shows the annotation route: declare a method with @Http(method = HttpMethod.GET, uri = "/users/{userId}/recommendations"), call Ribbon.from(MovieService.class), and the call returns a RibbonRequest whose observe() gives an Observable.

For a dynamic list rather than a hardcoded one, the README builds a ZoneAwareLoadBalancer with DiscoveryEnabledNIWSServerList("MyVIP:7001"), AvailabilityFilteringRule and ZoneAffinityServerListFilter. That path requires Eureka and is considerably more setup than the fixed list above.

Maintenance mode is the real constraint, not the API

The README states that Ribbon is in maintenance mode, and it does not hedge. Large external feature requests would not be prioritized internally, though complete pull requests would be reviewed and accepted. The stated reason is that Netflix moved to a componentized RPC architecture and started building on gRPC for multi-language support and composability through request interceptors. The last push to the repository was on 2021-08-05, and the most recent release, v2.4.8, is described as being based on 2.4.4 with upgraded build and CI configurations. That is a build maintenance release, not a feature release.

The practical consequence is that the module you depend on determines your risk. If you use ribbon-loadbalancer or ribbon-eureka, you are on code Netflix says is deployed at scale in production. If you use ribbon-transport for HTTP, TCP or UDP over RxNetty, or the top level ribbon module that ties in Hystrix, you are on code the README lists as not used. Choosing the wrong artifact is the failure mode here, and the README is the only place that tells you.

A second limitation is documentation. The README shows fragments with a truncated final line in the Eureka example, and it does not document rollback, upgrade paths between the 2.4 and 2.7 release lines, or how the internal Netflix HTTP client wrapper differs from the open source one. Anyone planning a migration has to read the source.

Ribbon compared with delegating load balancing to the platform

The alternative approach is to push load balancing out of the client. A service mesh sidecar or a platform load balancer keeps the server list centrally, so every language gets the same behaviour without a per-language client library. Ribbon does the opposite: each JVM holds the list and applies its own rules, which is why zone affinity and availability filtering can be tuned per service in Java code.

The trade-off is language reach. Ribbon is Java, and the README's own account of why Netflix moved on names multi-language support as one of the two reasons. A polyglot fleet cannot reuse a Java client side balancer in a Go or Python service.

Within Java, the README also points at where Netflix went: a gRPC based RPC solution with load balancing and discovery interceptors intended to reach feature parity with Ribbon and Eureka. Those interceptors were Netflix-internal at the time of writing. So the honest comparison is not Ribbon versus another library you can install today; it is Ribbon versus moving the balancing concern to gRPC interceptors or to the platform, and the README argues for the latter.

Licence and the cost of staying on a maintenance branch

Ribbon is Apache-2.0, and the README carries the standard Apache 2.0 notice with copyright Netflix, Inc. Apache-2.0 permits commercial use, modification and redistribution, and it includes a patent grant. It does not impose copyleft obligations on your code. That is a permissive arrangement, and it is the reason a maintenance-mode library can sit in a production dependency tree for years without a licensing problem. This is a description of the licence text, not legal advice; have your own counsel review anything that matters.

The upgrade cost is a different question. The releases listed on the repository jump from the 2.4 line (v2.4.8, 2021-08-05) back to the 2.7 line (v2.7.17, 2019-05-29, and v2.7.16, 2019-05-23). Those are separate branches, and the README does not explain how to move between them. If you pin a 2.4.x version you get the newer build and CI configuration; if you are on 2.7.x you are on a line whose last release predates it. Either way, the cost you are carrying is that fixes come from you or from other users, not from the maintainer's roadmap.

Editorial conclusion

Adopt Ribbon only if you are maintaining an existing Java service that already depends on ribbon-loadbalancer or ribbon-eureka and you need to keep it building. Do not start a new RPC client on it: the README states the project is in maintenance mode, lists ribbon and ribbon-transport as not used internally, and says the team is building on gRPC instead. Before committing, verify which module you actually need, since the README gives each one a different level of attention, and check the Maven Central coordinates for the version you intend to pin.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes