A Guide to Spring Cloud LoadBalancer

Posted on 2025-08-01 Edited on 2025-08-22 In Microservices , Spring Cloud

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.

Next, I will use a simple example application to show it in action.

1. Create Project and Add Dependencies

Using Gradle

1. Create a Java application with the gradle init command.

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

2. Gradle configuration

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

1. Create a Java application with mvn command.

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

2. Maven configuration

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

The spring configuration is the same as the Eureka client spring configuration.

application.yml

spring:
  application:
    name: spring-cloud-load-balancer
server:
  # configure the service to use a random port number
  port: 0

# Eureka client
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

# Actuator
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

[3] Client-Side Load-Balancing with Spring Cloud LoadBalancer - Spring Guides

[4] Dynamic Load Balancing in Distributed Systems with Spring Boot and Eureka - Meduim