Spring Cloud Eureka Client: Setup, Config and Load Balancing

<!-- pom.xml: -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>   <!-- match your Spring Boot version -->
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</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-actuator</artifactId>
    </dependency>
</dependencies>

@SpringBootApplication
@EnableDiscoveryClient   // optional: auto-configured when the starter is on the classpath
public class UserServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(UserServiceApplication.class, args);
    }
}

server:
  port: 8081

spring:
  application:
    name: user-service            # registry key, shown upper-case (USER-SERVICE) on the dashboard

eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
    register-with-eureka: true            # default: true
    fetch-registry: true                  # default: true
    registry-fetch-interval-seconds: 30   # default: refresh local cache every 30s

  instance:
    prefer-ip-address: true               # register the IP instead of the hostname
    lease-renewal-interval-in-seconds: 30     # default: heartbeat every 30s
    lease-expiration-duration-in-seconds: 90  # default: server may evict after 90s without heartbeat
    instance-id: ${spring.application.name}:${server.port}
    # Each instance needs a unique id. If you run with server.port=0 (random port),
    # use ${spring.application.name}:${random.value} instead.

# What happens on startup:
# 1. Application starts -> the Eureka registration component fires
# 2. POST /eureka/apps/USER-SERVICE            (registers this instance)
# 3. Server stores: host, port, health URL, status UP, metadata
# 4. Every 30s: PUT /eureka/apps/USER-SERVICE/{instance-id}   (heartbeat)
# 5. On graceful shutdown: DELETE /eureka/apps/USER-SERVICE/{instance-id}

# 1. Look in the client log for:
#    DiscoveryClient_USER-SERVICE/user-service:8081 - registration status: 204

# 2. Ask the server for the registry as JSON:
curl -H "Accept: application/json" http://localhost:8761/eureka/apps/USER-SERVICE

# 3. List all registered applications:
curl -H "Accept: application/json" http://localhost:8761/eureka/apps

# 4. Ask the client itself what it can see (via DiscoveryClient):
#    GET http://localhost:8081/debug/instances   (endpoint from the DiscoveryService example below)

# application.yml
eureka:
  client:
    healthcheck:
      enabled: true                       # propagate Actuator health to Eureka
  instance:
    health-check-url-path: /actuator/health
    status-page-url-path: /actuator/info

management:
  endpoints:
    web:
      exposure:
        include: health,info
  endpoint:
    health:
      show-details: when-authorized       # avoid exposing details publicly

// ── Custom health indicator that can mark the instance DOWN: ──────────
@Component
public class PaymentGatewayHealthIndicator implements HealthIndicator {

    private final PaymentGatewayClient gateway;

    public PaymentGatewayHealthIndicator(PaymentGatewayClient gateway) {
        this.gateway = gateway;
    }

    @Override
    public Health health() {
        return gateway.isReachable()
            ? Health.up().build()
            : Health.down().withDetail("gateway", "unreachable").build();
        // DOWN here -> Eureka status DOWN after the next status update
    }
}

// ── Option 1: @LoadBalanced RestTemplate ─────────────────────────────
@Configuration
public class AppConfig {

    @Bean
    @LoadBalanced   // instructs Spring Cloud LoadBalancer to intercept
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }

    @Bean
    @Qualifier("external")   // plain RestTemplate for non-Eureka URLs
    public RestTemplate externalRestTemplate() {
        return new RestTemplate();
    }
}

@Service
@RequiredArgsConstructor
public class OrderService {

    private final RestTemplate restTemplate;   // the @LoadBalanced one (only unqualified bean of this type)

    public UserResponse getUser(Long id) {
        // "user-service" is the spring.application.name of the target.
        // LoadBalancer resolves it to a real host:port via Eureka.
        return restTemplate.getForObject(
            "http://user-service/api/users/" + id,
            UserResponse.class
        );
    }
}

// ── Option 2: @LoadBalanced WebClient (non-blocking, needs spring-boot-starter-webflux): ──
@Configuration
public class WebClientConfig {

    @Bean
    @LoadBalanced
    public WebClient.Builder webClientBuilder() {
        return WebClient.builder();
    }
}

@Service
@RequiredArgsConstructor
public class OrderReactiveService {

    private final WebClient.Builder webClientBuilder;

    public Mono<UserResponse> getUser(Long id) {
        return webClientBuilder.build()
            .get()
            .uri("http://user-service/api/users/" + id)
            .retrieve()
            .bodyToMono(UserResponse.class);
    }
}

// ── Option 3: DiscoveryClient — manual instance resolution: ───────────
@Service
@RequiredArgsConstructor
public class DiscoveryService {

    private final DiscoveryClient discoveryClient;

    public List<String> listInstances() {
        List<ServiceInstance> instances =
            discoveryClient.getInstances("user-service");

        return instances.stream()
            .map(i -> i.getInstanceId() + " -> " + i.getUri())
            .toList();
    }
}

@RestController
@RequiredArgsConstructor
class DiscoveryDebugController {
    private final DiscoveryService discoveryService;

    @GetMapping("/debug/instances")
    public List<String> instances() { return discoveryService.listInstances(); }
}

// ── Default: RoundRobinLoadBalancer ──────────────────────────────────
// Requests to "user-service" are sent to instances in rotation:
//   Request 1 -> 172.18.0.5:8081
//   Request 2 -> 172.18.0.6:8081
//   Request 3 -> 172.18.0.5:8081  (back to first)

// ── Override to RandomLoadBalancer for a specific service: ────────────
@Configuration
@LoadBalancerClient(
    name = "user-service",           // applies only to user-service calls
    configuration = RandomLBConfig.class
)
public class AppLoadBalancerConfig { }

// NOTE: no @Configuration here, and keep it outside component-scanned packages
public class RandomLBConfig {

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

// ── Override globally (all services): ────────────────────────────────
@Configuration
@LoadBalancerClients(defaultConfiguration = RandomLBConfig.class)
public class GlobalLoadBalancerConfig { }

// ── Built-in zone preference (no code): application.yml of the CALLER ─
// spring:
//   cloud:
//     loadbalancer:
//       zone: us-east-1a
//       configurations: zone-preference
//
// and in each TARGET instance:
// eureka:
//   instance:
//     metadata-map:
//       zone: us-east-1a

// ── Custom load balancer (only for rules the built-ins cannot express) ─
public class ZoneAwareLoadBalancer implements
        ReactorServiceInstanceLoadBalancer {

    private final ObjectProvider<ServiceInstanceListSupplier> supplier;
    private final String serviceId;
    private final String currentZone;

    public ZoneAwareLoadBalancer(ObjectProvider<ServiceInstanceListSupplier> supplier,
                                 String serviceId,
                                 String currentZone) {
        this.supplier = supplier;
        this.serviceId = serviceId;
        this.currentZone = currentZone;
    }

    @Override
    public Mono<Response<ServiceInstance>> choose(Request request) {
        return supplier.getIfAvailable(NoopServiceInstanceListSupplier::new)
            .get(request)
            .next()
            .map(instances -> {
                if (instances.isEmpty()) {
                    return new EmptyResponse();
                }
                List<ServiceInstance> sameZone = instances.stream()
                    .filter(i -> currentZone.equals(
                        i.getMetadata().get("zone")))
                    .toList();
                List<ServiceInstance> pool =
                    sameZone.isEmpty() ? instances : sameZone;
                return new DefaultResponse(
                    pool.get(ThreadLocalRandom.current()
                        .nextInt(pool.size())));
            });
    }
}

# ── Publishing metadata from a client instance (application.yml): ────
eureka:
  instance:
    metadata-map:
      zone: us-east-1a          # used by zone-preference load balancing
      version: "@project.version@"   # filled in by Maven at build time
      team: payments            # ownership tag
      weight: "80"              # custom traffic weight for canary (strings only)

// ── Reading metadata in another service: ──────────────────────────────
@Service
@RequiredArgsConstructor
public class MetadataAwareService {

    private final DiscoveryClient discoveryClient;

    public Optional<ServiceInstance> findCanaryInstance(String serviceName) {
        return discoveryClient.getInstances(serviceName).stream()
            .filter(i -> "canary".equals(i.getMetadata().get("track")))
            .findFirst();
    }

    public void printAllMetadata(String serviceName) {
        discoveryClient.getInstances(serviceName).forEach(instance -> {
            System.out.println("Instance: " + instance.getInstanceId());
            instance.getMetadata()
                .forEach((k, v) -> System.out.println("  " + k + "=" + v));
        });
    }
}

// ── Adding metadata at runtime (after the application is ready): ─────
@Component
@RequiredArgsConstructor
public class RuntimeMetadataPublisher {

    private final ApplicationInfoManager applicationInfoManager;

    @EventListener(ApplicationReadyEvent.class)
    public void publish() {
        applicationInfoManager.registerAppMetadata(Map.of(
            "startedAt", Instant.now().toString(),
            "feature.search", "enabled"
        ));
        // sent to the Eureka Server with the next instance info replication
    }
}