A Guide to Spring Cloud LoadBalancer

Spring Cloud LoadBalancer is a client-side load balancing library within the Spring Cloud ecosystem, designed for Spring Boot applications to distribute traffic among multiple instances of a service.

In this post, I will cover common uses of Spring Cloud LoadBalancer. This post is based on Java 21, Spring Boot 3.5.3, and Spring Cloud 2025.0.0.

1. Create Project and Add Dependencies

Using Gradle

$ mkdir spring-cloud-load-balancer && cd spring-cloud-load-balancer
$ gradle --configuration-cache \
init --use-defaults \
--type java-application \
--package com.taogen.springcloud

app/build.gradle.kts

plugins {
java
id("org.springframework.boot") version "3.5.3"
// Use the Spring Dependency Management plugin to manage Spring Cloud dependencies.
id("io.spring.dependency-management") version "1.1.7"
}

extra["springCloudVersion"] = "2025.0.0"

java {
toolchain {
languageVersion = JavaLanguageVersion.of(21)
}
}

repositories {
mavenCentral()
}

dependencies {
implementation("org.springframework.cloud:spring-cloud-starter-loadbalancer")
implementation("org.springframework.cloud:spring-cloud-starter-netflix-eureka-client")
implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.springframework.boot:spring-boot-starter-actuator")
testImplementation("org.springframework.boot:spring-boot-starter-test")
testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

dependencyManagement {
imports {
mavenBom("org.springframework.cloud:spring-cloud-dependencies:${property("springCloudVersion")}")
}
}

tasks.withType<Test> {
useJUnitPlatform()
}

Using Maven

$ mvn -B archetype:generate \
-DgroupId=com.taogen.springcloud \
-DartifactId=spring-cloud-load-balancer \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DarchetypeVersion=1.5

pom.xml

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>com.taogen.springcloud</groupId>
<artifactId>spring-cloud-load-balancer</artifactId>
<version>1.0-SNAPSHOT</version>

<name>spring-cloud-load-balancer</name>

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.release>21</maven.compiler.release>
<java.version>21</java.version>
<spring-boot.version>3.5.3</spring-boot.version>
<spring-cloud.version>2025.0.0</spring-cloud.version>
</properties>

<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>${spring-cloud.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>

Using Spring Initializr

Go to https://start.spring.io/

Project Metadata

  • Group: com.taogen.springcloud
  • Artifact: spring-cloud-load-balancer

Add dependencies

  • Cloud LoadBalancer
  • Eureka Discovery Client
  • Spring Web
  • Spring Boot Actuator

2. Spring Configuration

It’s the same as the Eureka client spring configuration.

application.yml

spring:
application:
name: spring-cloud-load-balancer
eureka:
instance:
preferIpAddress: true
instanceId: ${spring.application.name}:${vcap.application.instance_id:${spring.application.instance_id:${random.value}}}
client:
registerWithEureka: true
fetchRegistry: true
serviceUrl:
defaultZone: http://localhost:8761/eureka/
healthcheck:
enabled: true
server:
# configure the service to use a random port number
port: 0
management:
endpoints:
web:
exposure:
include: health,info,beans

3. The Application

1. Spring Boot application entry point

SpringCloudLoadBalancerApplication.java

package com.taogen.springcloud;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringCloudLoadBalancerApplication {
public static void main(String[] args) {
SpringApplication.run(SpringCloudLoadBalancerApplication.class, args);
}
}

2. Define a load-balanced restTemplate with @LoadBalanced

RestTemplateConfig.java

package com.taogen.springcloud;

import org.springframework.cloud.client.loadbalancer.LoadBalanced;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class RestTemplateConfig {
@Bean
@LoadBalanced
public RestTemplate loadBalancedRestTemplate() {
return new RestTemplate();
}
}

3. Using the load-balanced restTemplate

package com.taogen.springcloud;  

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;

@RestController
@RequestMapping("/")
public class MyController {

@Autowired
private RestTemplate loadBalancedRestTemplate;

@GetMapping("/callEurekaClient2UsingClientLoadBalancer")
public String callEurekaClient2UsingClientLoadBalancer() {
String serviceUrl = "http://eureka-client-2/greeting";
return loadBalancedRestTemplate.getForObject(serviceUrl, String.class);
}
}

4. Start and Verification

1. Starting a Eureka server and two instances of Eureka-Client-2. And write a greeting API in Eureka-Client-2. For using Eureka, you can refer to A Guide to Spring Cloud Netflix Eureka.

The greeting API in Eureka Client 2

@RestController  
@RequestMapping("/")
public class MyController {
@Value("${spring.application.name}")
private String applicationName;

@GetMapping("/greeting")
public String greeting(){
System.out.println("greeting method is called");
return "Hello from " + applicationName + new Date();
}
}

Starting two instances of Eureka-Client-2 with the following command. Running the command in two terminal tabs to start two instances.

Gradle

./gradlew bootRun

Maven

mvn spring-boot:run

2. Running the main() method in the SpringCloudLoadBalancerApplication to start this Spring Cloud LoadBalancer application.

3. Request the /callEurekaClient2UsingClientLoadBalancer endpoint to see the result of using a client-side load balancer to call Eureka client 2 instances.

5. LoadBalancer Client

Spring RestTemplate as a LoadBalancer Client

@Configuration
public class MyConfiguration {
@Bean
@LoadBalanced
public RestTemplate loadBalancedRestTemplate() {
return new RestTemplate();
}
}
@Autowired
private RestTemplate loadBalancedRestTemplate;

public String doSomething() {
String serviceUrl = "http://{eureka-client-service-id}/{endpoint}";
String response = loadBalancedRestTemplate.getForObject(serviceUrl, String.class);
}

Spring RestClient as a LoadBalancer Client

@Configuration
public class MyConfiguration {
@Bean
@LoadBalanced
RestClient.Builder restClientBuilder() {
return RestClient.builder();
}
}
@Autowired
private RestClient.Builder restClientBuilder;

public String doSomething() {
String serviceUrl = "http://{eureka-client-service-id}/{endpoint}";
return restClientBuilder.build().get().uri(URI.create(serviceUrl)).retrieve().body(String.class);
}

Spring WebFlux WebClient as a LoadBalancer Client

@Configuration
public class MyConfiguration {
@Bean
@LoadBalanced
public WebClient.Builder loadBalancedWebClientBuilder() {
return WebClient.builder();
}
}
@Autowired
private WebClient.Builder webClientBuilder;

public Mono<String> doSomething() {
String serviceUrl = "http://{eureka-client-service-id}/{endpoint}";
return webClientBuilder.build().get().uri(serviceUrl)
.retrieve().bodyToMono(String.class);
}

References

[1] Spring Microservices in Action, Second Edition

[2] Spring Cloud LoadBalancer Documentation