GATEWAY API (1) - 게이트웨이가 서비스를 찾지 못하는 이유 (503 Service Unavailable)

 

1. 현상 (PROBLEM)

GATEWAY → EUREKA → SERVICE 구조 구축 후, 유레카 대시보드를 통해 모든 인스턴스가 정상적으로 등록된 것을 확인했습니다.

Eureka 대시보드 상에서 REMITRO-GATEWAY(8080)와 REMITRO-MEMBER(8081)가 모두 UP 상태임을 확인할 수 있다.

 

하지만 포스트맨으로 게이트웨이(8080)를 통해 회원가입 API를 호출했을 때, 기대와 달리 500 INTERNAL_ERROR가 발생했습니다.

서비스가 살아있는데 500이 뜨는 이유를 확인하기 위해 로그를 추적한 결과 다음 메시지를 발견했습니다.

 

java.lang.IllegalStateException: No servers available for service: remitro-member

(원래 로드밸런싱 실패 시 503이 떠야 하지만, 내부 필터 예외 처리 과정에서 500으로 래핑 되어 출력되었습니다.)

 

2. 원인 분석 (ANALYSIS)

시스템이 로드밸런싱 실패(503)가 아닌 500 에러를 반환한 이유는 핸들러의 예외 처리 로직에 있었습니다.

private GatewayErrorCode resolveErrorCode(Throwable throwable) {
   // ...
   // 1. 특정 HTTP 상태 코드 예외 처리 (404, 401 등)
   // 2. DownStream 통신 오류 체크 (WebClientException 등)
   if (isDownstreamException(throwable)) {
      return GatewayErrorCode.DOWNSTREAM_UNAVAILABLE;
   }
   // 3. 그 외에는 모두 500으로 귀결
   return GatewayErrorCode.INTERNAL_ERROR;
}

 

제 핸들러는 NOT_FOUND, UNAUTHORIZED, 그리고 실제 통신 단계인 DownStream 예외를 제외하면 모두 500 에러를 뱉도록 설계했습니다. 로드밸런서 부재로 발생한 IllegalStateException은 통신 시도조차 못 한 단계의 에러였기에 500으로 래핑 된 것이었습니다.

 

로그에 찍힌 "No servers available"이라는 문구는 게이트웨이가 요청을 보낼 대상을 찾지 못할 때 발생합니다.

저는 여기서 두 가지 가능성을 검토했습니다.

• 실제 서비스가 죽었는가? 유레카 대시보드에서 서비스가 UP 상태인 것을 이미 확인했으므로 통과했습니다.
• 서비스는 살아있는데 왜 못 찾는가? 서비스 목록은 유레카로부터 가져왔으나, 그 목록 중 하나를 선택하여 실제 요청을 보낼 선택자(LoadBalancer)가 작동하지 않고 있다는 결론에 도달했습니다.

단순히 통신 에러(ConnectException)가 아니라 '사용 가능한 서버가 없다'는 메시지는, 게이트웨이가 내부적으로 인스턴스 리스트를 뒤졌지만 유효한 하나를 고르는 로직 단계에서 실패했음을 의미하기 때문입니다.

 

① Spring Cloud LoadBalancer 의존성 부재: 

Spring Cloud 2020 버전 이후로 기존에 사용되던 Netflix-Ribbon이 삭제되었습니다.

게이트웨이가 유레카에서 목록을 가져오더라도, 실제로 요청을 분산 처리할 로드밸런서 라이브러리가 없으면 요청을 전달할 수 없습니다.

 

② 서비스 ID 대소문자 매칭 실패: 

위 대시보드 이미지에서 보이듯 유레카는 등록 시 기본적으로 hostname과 appName을 대문자로 저장하는 규약을 가집니다. 반면 Gateway yml 설정은 소문자를 사용하다 보니 이 사이에서 매칭 불일치가 발생한 것이었습니다.

 

3. 해결 (RESOLUTION)

이 문제를 해결하기 위해 두 가지 작업을 수행했습니다.

 

Step 1. LoadBalancer 의존성 추가: build.gradle에 로드밸런서 라이브러리를 추가했습니다.

implementation 'org.springframework.cloud:spring-cloud-starter-loadbalancer'

 

Step 2. 대소문자 매핑 허용: 게이트웨이가 서비스 ID를 찾을 때 대소문자를 구분하지 않도록 설정했습니다.

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
          lower-case-service-id: true # 소문자 매핑 허용

 

더불어, 향후 동일한 문제가 발생했을 때 로그를 뒤지지 않고 응답 코드만으로도 상황을 식별할 수 있도록, 핸들러 로직에 해당 예외 메시지를 키워드로 체크하여 503(DOWNSTREAM_UNAVAILABLE)을 반환하는 코드를 보강했습니다.

 

 

전역 예외 핸들러는 클라이언트에게 깔끔한 응답을 주는 기능도 있지만, 개발자가 오류를 신속하게 추적하고 모니터링할 수 있도록 분류할 수 있어야 한다고 생각합니다.

또한, 게이트웨이가 유레카로부터 정보를 가져와 로드밸런서를 거쳐 내부 서비스로 전달하는 전체적인 동작 흐름을 직접 설정하며, MSA 환경에서 각 컴포넌트 간의 통신 규약과 기본적인 인프라 설정이 전체 시스템의 가용성에 얼마나 영향을 미치는지 배우는 계기가 되었습니다.