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" 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: 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
Maven
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