🚨 Spring Cloud + Docker 환경에서 FeignClient 호출 시 UnknownHostException 해결기

MSA 환경에서 Auth-Service → User-Service로 회원정보를 전달하려는 과정에서 다음과 같은 예외를 맞닥뜨렸습니다:

feign.RetryableException: user-service executing POST http://user-service:8082/internal/users
Caused by: java.net.UnknownHostException: user-service

이 글에서는 위 오류의 원인과 해결 방법을 기록합니다.

---

🧩 문제 상황 요약

• Auth-Service → User-Service로 FeignClient를 통해 HTTP 요청 전송
• 에러: java.net.UnknownHostException: user-service
• Docker Compose로 각 서비스를 컨테이너화한 상태

🔧 Docker Compose 구성 예시 (초기 버전)

services:
  app:  # ❌ 문제의 원인
    container_name: user-service-app
    build:
      context: .
    ports:
      - "8082:8082"
    networks:
      - msa-net

⚠️ 문제 원인

Spring Cloud의 @FeignClient(name = "user-service")는 내부 네트워크에서 user-service라는 DNS 이름을 찾습니다.
하지만 Docker에서 해당 컨테이너는 user-service-app이라는 이름으로 존재하므로, DNS name mismatch로 인해 UnknownHostException이 발생한 것입니다.

 

---

✅ 해결 방법

1. Docker Compose에서 container_name 및 service 이름을 FeignClient와 동일하게 설정

 

services:
  user-service:
    container_name: user-service  # ✅ FeignClient와 동일하게 맞춤
    build:
      context: .
    ports:
      - "8082:8082"
    networks:
      - msa-net

 

 

2. FeignClient에서 name 속성과 일치

@FeignClient(name = "user-service")
public interface UserClient {
    @PostMapping("/internal/users")
    void createUserProfile(@RequestBody CreateUserProfileRequest request);
}

 

---

🔄 대체 해결책 (Eureka 사용 시)

만약 Eureka로 서비스 레지스트리를 사용하고 있다면, url 설정 없이 다음처럼만 작성해도 됩니다:

@FeignClient(name = "user-service")

이 경우 Spring Cloud LoadBalancer + Eureka가 자동으로 인스턴스를 찾아줍니다. 단, 모든 서비스가 Eureka에 잘 등록되어 있어야 하고, Eureka hostname은 설정에 맞춰 사용해야 합니다.

 

📌 요약

항목올바른 설정

Docker Compose service 이름	user-service
Docker Compose container_name	user-service (선택적이나 일치 권장)
FeignClient name	user-service
Eureka instanceId (선택)	user-service

---

🧠 교훈

• MSA + Docker 환경에서는 FeignClient name과 Docker DNS 이름이 반드시 일치해야 함
• Docker Compose의 service 이름이 DNS 역할을 하므로, 이를 중심으로 이름 정리 필요
• 에러 메시지가 DNS 문제인지 아닌지 UnknownHostException으로 빠르게 파악하는 습관이 중요