Build High‑Availability Microservices with Spring Cloud Gateway and Nacos Load Balancing

1. Introduction: The pain of single‑point failure

Imagine an application with only one service instance that crashes under traffic, returning a 502 Bad Gateway error. The solution is multi‑instance deployment with load balancing, using Nacos for service discovery and Spring Cloud Gateway as the API gateway.

2. Environment preparation

Technical stack and versions

JDK 8 or 11 (recommended 11)

Spring Boot 2.7.x

Spring Cloud 2021.0.8

Spring Cloud Alibaba 2021.0.5.0

Nacos Server 2.2.0+

Project structure

Standard Maven parent‑child project:

spring-cloud-nacos-lb-demo (parent)
├── api-gateway (gateway module, jar)
├── service-provider (service provider module, jar)
└── pom.xml (parent pom)

Parent pom core dependencies

Dependency management locks versions for Spring Boot, Spring Cloud and Spring Cloud Alibaba.

<!-- trimmed pom.xml snippet showing properties and dependencyManagement for Spring Boot, Spring Cloud, and Spring Cloud Alibaba -->

3. Core concept: What is “dual instance”?

In microservice architecture, “dual instance” can be deployed in two modes. Both rely on the triple service name + host IP + port to distinguish instances.

Mode 1: Multiple instances on a single machine (development/testing)

Description: Run several processes of the same service on one host, each listening on a different port.

Purpose: Maximize resource usage, save cost, and simplify local testing.

Example: Instance 1: 192.168.1.100:8081, Instance 2: 192.168.1.100:8082.

Reliability: Low – a host failure makes all instances unavailable.

Mode 2: Multiple instances on multiple machines (production)

Description: Deploy the service on different physical or virtual machines.

Purpose: True high availability, disaster recovery, horizontal scaling.

Example: Instance 1 on Server A: 192.168.1.101:8080, Instance 2 on Server B: 192.168.1.102:8080.

Reliability: High – failure of one server does not affect the other.

The following diagram shows how Gateway balances requests in both modes:

4. Hands‑on: Five steps to implement Gateway + Nacos load balancing

Step 1 – Build two service‑provider instances

Create the service-provider module and add Spring Boot Web and Nacos discovery dependencies. <!-- service-provider/pom.xml snippet --> Write a simple controller that returns the port number.

@SpringBootApplication
@RestController
public class ServiceProviderApplication {
    @Value("${server.port}")
    private String port;

    @GetMapping("/hello")
    public String sayHello(@RequestParam String name) {
        return "Hello, " + name + ". I'm from port: " + port;
    }

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

Create two configuration files application-instance1.yml (port 8081) and application-instance2.yml (port 8082) with the same spring.application.name and Nacos address.

server:
  port: 8081
spring:
  application:
    name: service-provider
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848

Run the module twice with different active profiles (instance1, instance2).

Step 2 – Configure the gateway

Add spring-cloud-starter-gateway, Nacos discovery and LoadBalancer dependencies to the api-gateway module. <!-- api-gateway/pom.xml snippet --> Configure api-gateway/application.yml to register the gateway itself and define a manual route:

server:
  port: 9999
spring:
  application:
    name: api-gateway
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
    gateway:
      discovery:
        locator:
          enabled: false
      routes:
        - id: service-provider-route
          uri: lb://service-provider
          predicates:
            - Path=/api/**
          filters:
            - StripPrefix=1

Step 3 – Start and verify

Ensure Nacos Server is running (default localhost:8848, user nacos / nacos). Start the two provider instances and the gateway. In the Nacos console you should see the service-provider service with two healthy instances and the api-gateway service.

Step 4 – Test the load balancer

Send repeated requests to http://localhost:9999/api/hello?name=you. The responses will alternate between port 8081 and port 8082, confirming round‑robin distribution.

Step 5 – Observe the result

The gateway automatically distributes traffic across the two backend instances, achieving high availability.

5. Principle analysis: What happens behind lb://

Service registration: Providers register name, IP and port to Nacos.

Service discovery: Gateway uses Nacos Discovery Client to pull the service list.

Load balancing: Spring Cloud LoadBalancer selects an instance from the cached list using the lb:// protocol (default round‑robin).

Request forwarding: Gateway forwards the request to the chosen instance.

Response: The instance returns the result to the gateway, which forwards it to the client.

6. Advanced usage: Smarter load balancing

Option 1 – Weight‑based balancing (production)

Adjust instance weights in the Nacos console to control traffic distribution (e.g., 0.2 for port 8081 and 0.8 for port 8082).

Option 2 – Custom load‑balancing strategy

Define a configuration class that provides a RandomLoadBalancer bean to replace the default round‑robin algorithm.

package com.yourcompany.gateway.config;

import org.springframework.cloud.client.ServiceInstance;
import org.springframework.cloud.loadbalancer.core.*;
import org.springframework.context.annotation.*;
import org.springframework.core.env.Environment;

@Configuration
public class LoadBalancerConfig {
    @Bean
    ReactorLoadBalancer<ServiceInstance> randomLoadBalancer(Environment env,
            LoadBalancerClientFactory factory) {
        String serviceId = env.getProperty(LoadBalancerClientFactory.PROPERTY_NAME);
        return new RandomLoadBalancer(factory.getLazyProvider(serviceId, ServiceInstanceListSupplier.class), serviceId);
    }
}

Apply it to a specific service with

@LoadBalancerClient(value = "service-provider", configuration = LoadBalancerConfig.class)

.

7. Conclusion

This tutorial demonstrates how to achieve automatic client‑side load balancing with Spring Cloud Gateway and Nacos. By understanding the lb:// protocol and Nacos as a service registry, you can build highly available microservices, scale horizontally, and fine‑tune traffic with weights or custom strategies.