API Gateway، Service Discovery و ConfigAPI Gateway, Service Discovery & Config

The moment you migrate from a monolith to microservices, three new and unforgiving questions land on the table — questions that simply did not exist in the monolithic world:

1. Should the client talk to dozens of different services directly? How would it even know each one's address?
2. How does Service A find Service B's address when, at any instant, three instances of B may be spinning up or dying?
3. How is configuration (DB connection strings, feature flags, rate caps) managed across 40 services without redeploying 40 times?

This chapter answers exactly these three operational pains: the API Gateway (the entry doorway), Service Discovery (the live phone book of services), and Centralized Config (the control room for settings). Together these are the nervous system of a microservice architecture. If domain logic is the heart of the system, these are the veins and nerves keeping that heart alive.

Why didn't the monolith have these pains?

In a monolith, when the "Order" module wanted to call the "User" module, it was just a plain method call inside the same JVM: userService.findById(id). There was no address, because everything lived in one process. Configuration was a single application.yml. And the client knew exactly one address: the monolith itself.

Microservices break this convenience — and hand you scalability and team autonomy in return. But that simple method call is now a network call over TCP, and the network is unreliable, slow, and variable. Addresses have become dynamic because in Kubernetes a Pod dies at any moment and comes back with a new IP. These three tools exist precisely to fill that gap.

Here's the big picture. Bird's-eye topology of a microservice platform / نمای کلی توپولوژی یک پلتفرم میکروسرویس:

flowchart TD
  Client[Mobile / Web / Partner] --> GW[API Gateway]
  GW -->|discovery| Reg[(Service Registry)]
  GW --> Order[Order Service]
  GW --> User[User Service]
  GW --> Pay[Payment Service]
  Order -. register .-> Reg
  User -. register .-> Reg
  Pay -. register .-> Reg
  Cfg[Config Server] -. config .-> Order
  Cfg -. config .-> User
  Cfg -. config .-> Pay
  Cfg --> Git[(Git repo)]
  Order --> OrderDB[(Order DB)]
  User --> UserDB[(User DB)]

The three key actors on this map — the Gateway, the Registry, and the Config Server — are the subject of this chapter. We'll take them one at a time, from the lowest layer (finding services) up to the highest (the edge doorway).

Part 1: Service Discovery — the live phone book of services

Suppose the Order service wants to call Payment. What's its address? If you hardcode http://192.168.4.11:8080, that's a disaster waiting to happen: tomorrow that Pod dies, the IP changes, three fresh instances come up. Hardcoding an address in a dynamic world makes no sense.

Concept: Registry, Registration, and Resolution

Build the three terms from scratch:

• Service Registry: a live database holding "service name → list of current healthy addresses". Examples: Eureka, Consul, etcd (under Kubernetes).
• Registration: the act by which an instance, on startup, registers itself with a name and address, then periodically sends a "heartbeat" to say "I'm still alive".
• Resolution (Discovery): the act by which a consumer translates a logical name (payment-service) into a real address.

Client-side vs server-side discovery

This distinction is a favorite interview question. There are two fundamental models:

Client-side discovery: the consumer itself pulls the list of addresses from the registry, picks one (load balancing), and calls it directly. Netflix Eureka + Spring Cloud LoadBalancer is exactly this model. Upside: one fewer network hop and precise control over the selection algorithm. Downside: every client must carry discovery and load-balancing logic (a library dependency, and awkward for polyglot stacks).

Server-side discovery: the client only hits one fixed address (a load balancer or gateway), and that intermediary uses the registry to route to the right instance. A Kubernetes Service is exactly this: you hit one stable DNS name and kube-proxy spreads the load across the Pods behind the scenes. Upside: the client needs no logic. Downside: one extra hop and one extra piece of infrastructure.

Client-side vs server-side discovery / مقایسهٔ کشف سمت‌کلاینت و سمت‌سرور:

flowchart LR
  subgraph ClientSide[Client-side discovery]
    C1[Consumer] -->|1 ask| R1[(Registry)]
    C1 -->|2 pick & call| P1[Provider instance]
  end
  subgraph ServerSide[Server-side discovery]
    C2[Consumer] -->|call fixed name| LB[Load Balancer / Service]
    LB -->|route| P2[Provider instance]
    LB -.-> R2[(Registry)]
  end

Implementation with Eureka (Netflix)

Eureka comes from the Spring Cloud Netflix project. You run a Eureka Server that plays the registry role, and clients register themselves with it. The default port is 8761.

Server:

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

# application.yml — Eureka Server
server:
  port: 8761
eureka:
  client:
    register-with-eureka: false   # the server doesn't register itself
    fetch-registry: false
  server:
    enable-self-preservation: true   # defaults to true — important! explained below

A consumer service registers automatically just by having the dependency and the server URL:

# application.yml — an ordinary service
spring:
  application:
    name: payment-service     # this name is the discovery key
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8761/eureka/
  instance:
    prefer-ip-address: true
    lease-renewal-interval-in-seconds: 30    # heartbeat every 30s (default)
    lease-expiration-duration-in-seconds: 90 # evict after 90s of no heartbeat

Now Order can call Payment by its logical name (not its IP), provided it has a load-balanced RestClient/WebClient, which we build in the next section.

Implementation with Consul (HashiCorp)

Beyond discovery, Consul offers a key/value store (for config) and active health checking. A key difference from Eureka: Eureka relies only on heartbeats (AP in CAP terms — availability over consistency), whereas Consul runs real health checks (HTTP/TCP/script) and, being Raft-based, leans toward stronger consistency (CP). Default port 8500.

spring:
  application:
    name: payment-service
  cloud:
    consul:
      host: localhost
      port: 8500
      discovery:
        health-check-path: /actuator/health
        health-check-interval: 10s
        prefer-ip-address: true

Kubernetes: discovery with no library at all

On Kubernetes, discovery is baked into the platform. When you create a Service, Kubernetes gives it a stable DNS name: payment-service.default.svc.cluster.local. Any call to that name is spread by kube-proxy (via iptables or IPVS) across the healthy Pods behind the Service — that is, server-side discovery + load balancing, free and language-agnostic.

apiVersion: v1
kind: Service
metadata:
  name: payment-service
spec:
  selector:
    app: payment
  ports:
    - port: 80
      targetPort: 8080

Now from inside any other Pod you simply hit http://payment-service/api/.... No Eureka, no discovery library.

Comparing four discovery approaches:

Part 2: Client-side load balancing with Spring Cloud LoadBalancer

When the registry tells you "Payment has three instances: A, B, C", you now have to pick one. That choice is load balancing.

For years, Spring's default was Netflix Ribbon. Ribbon is now deprecated, and its official successor is Spring Cloud LoadBalancer — lighter, reactive-friendly, and a core part of Spring Cloud. If you still see Ribbon in some code, know that it's legacy.

The default algorithm is Round Robin (in turn: A, B, C, A, B, C…). A RandomLoadBalancer is also available. The switch that turns it on is an annotation called @LoadBalanced on your WebClient/RestClient builder:

@Configuration
public class HttpClientConfig {

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

@Service
public class PaymentClient {

  private final WebClient webClient;

  public PaymentClient(WebClient.Builder builder) {
    // 'payment-service' is a logical name, not a real host —
    // LoadBalancer resolves it to a healthy instance
    this.webClient = builder.baseUrl("http://payment-service").build();
  }

  public Mono<PaymentResult> charge(ChargeRequest req) {
    return webClient.post()
        .uri("/api/charge")
        .bodyValue(req)
        .retrieve()
        .bodyToMono(PaymentResult.class);
  }
}

The key point: http://payment-service looks like a fake URL, but LoadBalancer takes that host, asks the registry (Eureka/Consul/k8s) for the list of instances, picks one round-robin, and substitutes the host.

You can change the algorithm per-service and tune the cache:

spring:
  cloud:
    loadbalancer:
      cache:
        enabled: true
        ttl: 35s          # how long the instance list is cached
      health-check:
        interval: 25s
      # internal retry on a different instance on failure
      retry:
        enabled: true

Part 3: The API Gateway with Spring Cloud Gateway

Now the top layer: the edge. External clients shouldn't talk to 40 services directly. You need a single entry point.

Why a gateway? Cross-cutting concerns

Without a gateway, every service has to implement its own auth, rate limiting, logging, CORS, and TLS termination — duplication and inconsistency. The gateway centralizes these cross-cutting concerns:

• Routing: dispatch a request to the right service based on path/host/header.
• Authentication/Authorization at the edge: validate JWTs before they reach services.
• Rate limiting & throttling: protect against a flood of requests.
• Simple aggregation and request/response transformation.
• Observability: one place to start traces and collect ingress metrics.

Installation: the new artifact names (very important)

As of Spring Cloud 2025.0.0, the Gateway module and starter names changed to clarify the two gateway styles (server vs proxy-exchange) and the two web stacks (WebFlux vs WebMVC):

WebFlux or WebMVC? The WebFlux flavor (on Netty, non-blocking) is the classic, optimal choice for a gateway whose job is mostly network I/O and proxying, since it sustains high concurrency with few threads. The WebMVC flavor (on a servlet/Tomcat, blocking) suits teams that aren't comfortable with the reactive model or whose code is blocking. For a pure gateway, WebFlux is more common.

The three core Gateway concepts: Route, Predicate, Filter

• Route: the basic unit of routing. It has an id, a target uri, a set of predicates, and a set of filters.
• Predicate: the condition "does this request match this route?" Like "if the path starts with /api/orders" or "if a header equals something."
• Filter: the work performed on a matched request/response — before (pre) or after (post) it goes to the target service.

Request lifecycle inside the gateway / چرخهٔ عمر یک درخواست در gateway:

flowchart LR
  Req[Incoming request] --> Match{Predicate match?}
  Match -->|no| Next[Try next route]
  Match -->|yes| Pre[Pre-filters]
  Pre --> Proxy[Proxy to target service]
  Proxy --> Post[Post-filters]
  Post --> Resp[Response to client]

Defining a route with YAML

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: orders-route
              uri: lb://order-service      # lb:// means use LoadBalancer + registry
              predicates:
                - Path=/api/orders/**
                - Method=GET,POST
              filters:
                - StripPrefix=1            # /api/orders/5 -> /orders/5
                - name: CircuitBreaker
                  args:
                    name: ordersCb
                    fallbackUri: forward:/fallback/orders
            - id: users-route
              uri: lb://user-service
              predicates:
                - Path=/api/users/**
              filters:
                - AddRequestHeader=X-Gateway, edge

Notice uri: lb://order-service — the lb:// prefix means that instead of a fixed host, the gateway uses Spring Cloud LoadBalancer and the registry to resolve the name. This is where all three tools of the chapter meet: Gateway + Discovery + LoadBalancer.

Defining routes with the Java DSL (for dynamic logic)

Sometimes you need more programmatic logic:

@Configuration
public class GatewayRoutes {

  @Bean
  public RouteLocator routes(RouteLocatorBuilder builder) {
    return builder.routes()
      .route("orders-route", r -> r
          .path("/api/orders/**")
          .filters(f -> f
              .stripPrefix(1)
              .circuitBreaker(c -> c.setName("ordersCb")
                  .setFallbackUri("forward:/fallback/orders"))
              .retry(rc -> rc.setRetries(2)))
          .uri("lb://order-service"))
      .route("users-route", r -> r
          .path("/api/users/**")
          .uri("lb://user-service"))
      .build();
  }
}

Common predicates and filters:

Rate Limiting: protecting the backend

The gateway must protect backend services from a flood of requests. The RequestRateLimiter filter does this, and its default implementation is RedisRateLimiter, which uses the Token Bucket algorithm. It requires spring-boot-starter-data-redis-reactive (because the counter must be shared across all gateway instances — and Redis is that shared state).

spring:
  cloud:
    gateway:
      server:
        webflux:
          routes:
            - id: orders-route
              uri: lb://order-service
              predicates:
                - Path=/api/orders/**
              filters:
                - name: RequestRateLimiter
                  args:
                    redis-rate-limiter.replenishRate: 10    # 10 tokens/sec refilled
                    redis-rate-limiter.burstCapacity: 20    # burst ceiling: 20
                    redis-rate-limiter.requestedTokens: 1   # cost per request
                    key-resolver: "#{@userKeyResolver}"

replenishRate is the steady allowed rate (requests per second); burstCapacity is the maximum momentary requests allowed (the bucket size). The KeyResolver decides what the rate is counted against — user, IP, API key:

@Bean
KeyResolver userKeyResolver() {
  // count the rate per-user; fall back to IP if no user
  return exchange -> {
    String user = exchange.getRequest().getHeaders().getFirst("X-User-Id");
    if (user != null) return Mono.just(user);
    String ip = exchange.getRequest().getRemoteAddress()
                        .getAddress().getHostAddress();
    return Mono.just(ip);
  };
}

Authentication at the edge

The common, correct pattern: the gateway validates the JWT at the edge (signature, expiry, issuer, audience) and only forwards valid requests to the back. Backend services can lower their guard somewhat — but, a warning, they must not blindly place absolute trust in the gateway (the zero-trust principle). The gateway typically injects identity into a header like X-User-Id or relays the token.

Token relay through the gateway / انتقال توکن از میان gateway:

sequenceDiagram
  participant C as Client
  participant G as API Gateway
  participant A as Auth Server (OIDC)
  participant S as Order Service
  C->>G: GET /api/orders (Bearer JWT)
  G->>A: Validate signature via JWKS
  A-->>G: Keys / OK
  G->>G: Check exp, iss, aud, scopes
  G->>S: Forward + relay token / inject X-User-Id
  S-->>G: 200 orders
  G-->>C: 200 orders

With Spring Security on the gateway as an OAuth2 Resource Server:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          # gateway fetches public keys from JWKS and verifies the signature
          issuer-uri: https://auth.example.com/realms/prod
  cloud:
    gateway:
      server:
        webflux:
          default-filters:
            - TokenRelay=      # relay the original token to backend services

@Configuration
@EnableWebFluxSecurity
public class EdgeSecurity {

  @Bean
  SecurityWebFilterChain security(ServerHttpSecurity http) {
    return http
        .csrf(ServerHttpSecurity.CsrfSpec::disable)
        .authorizeExchange(ex -> ex
            .pathMatchers("/api/public/**").permitAll()
            .anyExchange().authenticated())
        .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
        .build();
  }
}

The BFF Pattern — a Backend for each Frontend

A single shared gateway for all clients has a problem: a mobile app's needs differ from the web's and a business partner's. Mobile wants small payloads and few round-trips (battery and weak networks), the web wants more fields, the partner wants a stable, versioned contract. If one gateway tries to please everyone, it fills up with if client == mobile.

BFF: one tailored backend per client type / یک backend سفارشی برای هر نوع کلاینت:

flowchart TD
  Mobile[Mobile app] --> MBFF[Mobile BFF]
  Web[Web SPA] --> WBFF[Web BFF]
  Partner[Partner API] --> PBFF[Partner BFF]
  MBFF --> Order[Order Service]
  MBFF --> User[User Service]
  WBFF --> Order
  WBFF --> User
  WBFF --> Catalog[Catalog Service]
  PBFF --> Order

Each BFF owns the aggregation and client-specific shaping — exactly the work you must not put in the shared gateway. A BFF has a clear owner: the team that owns that frontend. The difference between a BFF and a gateway: a gateway is generic cross-cutting policy; a BFF is the experience logic of one specific client.

Part 4: Centralized Config with Spring Cloud Config

The final pillar: configuration. In a monolith, one application.yml was enough. With 40 services × 3 environments (dev/stage/prod), scattered config becomes a nightmare. The key question: how do I change one flag across all services without a rebuild and redeploy?

Architecture: Config Server + backend

Spring Cloud Config is two pieces: a Config Server that serves configuration from a backend (usually Git, or Vault, filesystem, S3), and Config Clients (the services) that fetch their configuration from the server on startup.

Server:

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

# Config Server — serves from a Git repo
server:
  port: 8888
spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/acme/config-repo
          default-label: main
          search-paths: '{application}'   # folder per service name

Files in the repo follow a naming convention: payment-service.yml, payment-service-prod.yml, and a global application.yml for values shared by all services.

The client: from bootstrap to spring.config.import

# client — application.yml
spring:
  application:
    name: payment-service
  config:
    import: "optional:configserver:http://localhost:8888"
  profiles:
    active: prod

optional: means that if the Config Server is unavailable, the app comes up with local config instead of crashing — good for dev. But in prod you might drop optional: so that if config doesn't arrive, the app deliberately refuses to start (fail-fast instead of booting with wrong config).

Profiles: one codebase, many environments

A profile is Spring's mechanism for "same app, different config per environment". With payment-service-prod.yml you layer prod-specific values over the base payment-service.yml. Precedence matters: more specific (profile-specific) values override more general ones, and environment variables / command-line arguments override all of them.

Live refresh: the heart of it

The whole point of centralized config is being able to change a setting without a restart. The mechanism:

1. Mark the bean you want refreshed with @RefreshScope. On refresh, this bean is rebuilt and reads the new values.
2. POST to /actuator/refresh on that instance. This publishes a RefreshScopeRefreshedEvent, and @RefreshScope beans are rebuilt and @ConfigurationProperties are rebound.

@RefreshScope
@Component
public class PricingConfig {
  @Value("${pricing.discount-percent:0}")
  private int discountPercent;   // new value after refresh

  public int discountPercent() { return discountPercent; }
}

# refreshes only this one instance
curl -X POST http://payment-1:8080/actuator/refresh

But there's a problem: if you have 20 instances of payment-service, do you curl 20 times? This is where Spring Cloud Bus comes in.

Spring Cloud Bus: refresh all instances at once

Spring Cloud Bus connects all instances through a message broker (Kafka or RabbitMQ) onto one shared "bus". A single POST to /actuator/busrefresh on one instance is enough: that instance publishes a RefreshRemoteApplicationEvent onto the broker, and all subscribed instances receive it and refresh themselves.

Broadcast config refresh over the bus / پخش refresh تنظیمات روی bus:

flowchart TD
  Ops[Ops: POST /actuator/busrefresh] --> S1[payment-1]
  S1 -->|publish RefreshRemoteApplicationEvent| Broker[(Kafka / RabbitMQ)]
  Broker --> S1
  Broker --> S2[payment-2]
  Broker --> S3[payment-3]
  S1 --> Cfg[(Config Server -> Git)]
  S2 --> Cfg
  S3 --> Cfg

# client with the bus on kafka
spring:
  cloud:
    bus:
      enabled: true
    stream:
      kafka:
        binder:
          brokers: kafka:9092
management:
  endpoints:
    web:
      exposure:
        include: busrefresh, refresh, health

A more mature architecture: a webhook from Git (on each push) hits the Config Server, which in turn triggers busrefresh — meaning a commit to the config repo automatically propagates to all services. True GitOps for config.

Managing secrets

Putting a DB password as plain text in Git is a security disaster. Three approaches:

1. Encryption in the Config Server: the Config Server can encrypt values; in the repo the value is stored as {cipher}AQB..., and the server decrypts it when serving. The /encrypt and /decrypt endpoints exist for this.

# in the repo, the password is stored encrypted
spring:
  datasource:
    password: '{cipher}AQBvJ8x...k9'

2. HashiCorp Vault as the backend: instead of Git, you keep secrets in Vault, which provides rotation, time-bounded leases, and audit. Spring Cloud Config/Vault integrates it.

3. Platform secrets (on k8s): you use a Kubernetes Secret (and, better, a solution like External Secrets Operator or Sealed Secrets), delivered to the Pod as env vars or mounted files. On k8s this is usually cleaner than hand-encrypting in Git.

Putting it all together: one full request

Let's trace a complete request from client to database and see where each of the three tools plays its part.

End-to-end request across all three pillars / یک درخواست سرتاسری از میان هر سه ستون:

sequenceDiagram
  participant C as Client
  participant G as Gateway
  participant R as Registry
  participant O as Order Service
  participant Cfg as Config Server
  C->>G: GET /api/orders (JWT)
  G->>G: Validate JWT, check rate limit
  G->>R: Resolve lb://order-service
  R-->>G: order-2 @ 10.1.4.7:8080
  G->>O: GET /orders (relay token)
  Note over O,Cfg: On startup O had pulled its config
  O->>O: Apply @RefreshScope values
  O-->>G: 200 orders
  G-->>C: 200 orders

The temporal order: the Config Server handed the service its config when it started; the service registered itself in the Registry; now the user's request reaches the Gateway, where it is authenticated and rate-limited; the Gateway asks the Registry for Order's live address, load-balances, relays the token, and the response comes back. This coordinated dance is what makes a microservice platform actually run.

Senior lens: anti-patterns and production lessons