[스프링] 4. Docker로 마이크로서비스 배포하기

마이크로서비스를 로컬에서 하나씩 실행하면 포트 충돌, 환경 차이, 실행 순서 문제가 끝없이 발생한다. Docker와 Docker Compose는 이런 문제를 컨테이너라는 격리된 환경으로 해결한다. 4개의 서비스를 한 번에 띄우고, 네트워크까지 자동으로 연결하는 방법을 알아본다.

컨테이너가 마이크로서비스에 적합한 이유

Docker 컨테이너는 애플리케이션과 그 실행 환경을 함께 패키징하는 기술이다. JDK 버전, 라이브러리, 설정 파일을 모두 포함해서 하나의 이미지로 만든다.

마이크로서비스에서 컨테이너가 특히 빛나는 이유가 있다.

• 환경 일치 : "내 컴퓨터에서는 되는데"가 사라진다. 개발, 테스트, 운영 환경이 동일한 이미지를 쓴다.
• 격리 : 각 서비스가 독립된 파일 시스템, 네트워크, 프로세스 공간에서 돌아간다. user-service의 Java 17과 다른 서비스의 Java 21이 충돌하지 않는다.
• 경량성 : VM과 달리 OS를 통째로 올리지 않는다. 호스트 OS의 커널을 공유하므로 시작 시간이 빠르고 리소스 사용이 적다.

왼쪽의 VM은 Guest OS 전체를 포함해서 무겁다. 오른쪽의 컨테이너는 앱과 라이브러리만 담고 Host OS의 커널을 공유하므로 가볍다.

Dockerfile — 이미지 빌드 설계도

Dockerfile은 컨테이너 이미지를 어떻게 만들 것인지 정의하는 파일이다. 각 명령이 하나의 레이어를 만들고, 이 레이어들이 쌓여서 최종 이미지가 된다.

실습의 Spring Boot 서비스 Dockerfile은 멀티스테이지 빌드를 사용한다.

멀티스테이지 빌드의 원리

하나의 Dockerfile에 빌드 단계와 실행 단계를 분리하는 기법이다. 빌드에 필요한 도구는 빌드 단계에만 존재하고, 최종 이미지에는 실행에 필요한 최소한의 파일만 포함된다.

주황 영역의 빌드 스테이지에는 JDK, Gradle, 소스 코드가 모두 포함된다. 초록 영역의 실행 스테이지에는 JRE와 빌드된 JAR만 들어간다. 이 분리 덕분에 최종 이미지의 크기가 크게 줄어든다. JDK 이미지는 500MB 이상이지만, JRE 이미지는 200MB 정도다.

실습의 Dockerfile을 분석하면 각 명령의 의미가 보인다.

# 빌드 스테이지 — JDK로 소스 빌드
FROM eclipse-temurin:17-jdk-jammy AS builder
WORKDIR /app
COPY gradlew .
COPY gradle gradle
COPY build.gradle .
COPY settings.gradle .
COPY src src
RUN chmod +x ./gradlew
RUN ./gradlew clean bootJar

FROM ... AS builder로 이 스테이지에 builder라는 이름을 붙인다. Gradle Wrapper와 소스 코드를 복사한 뒤 빌드를 실행한다.

# 실행 스테이지 — JRE로 애플리케이션 실행
FROM eclipse-temurin:17-jre-jammy
WORKDIR /app
COPY --from=builder /app/build/libs/*.jar app.jar
EXPOSE 8081
ENV JAVA_OPTS="-Xms256m -Xmx512m -XX:+UseG1GC"
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

COPY --from=builder로 빌드 스테이지에서 JAR 파일만 가져온다. EXPOSE는 문서화 용도이고, ENTRYPOINT가 컨테이너 시작 시 실행할 명령이다.

Docker Compose — 멀티 컨테이너 오케스트레이션

Docker Compose는 여러 컨테이너를 하나의 YAML 파일로 정의하고 한 번에 관리하는 도구다. 실습에서는 Nginx + 3개 Spring Boot 서비스, 총 4개의 컨테이너를 Docker Compose로 관리한다.

services:
  api-gateway:
    build:
      context: ./nginx
      dockerfile: Dockerfile
    ports:
      - "80:80"
    depends_on:
      - user-service
      - order-service
      - payment-service

  user-service:
    build:
      context: ./user-service
      dockerfile: Dockerfile
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - SERVER_PORT=8081

  order-service:
    build:
      context: ./order-service
      dockerfile: Dockerfile
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - SERVER_PORT=8082

  payment-service:
    build:
      context: ./payment-service
      dockerfile: Dockerfile
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - SERVER_PORT=8083

networks:
  microservices-network:
    driver: bridge

핵심 설정을 하나씩 살펴본다.

ports vs 노출 안 함

api-gateway만 ports: "80:80"을 선언한다. 호스트의 80번 포트를 컨테이너의 80번 포트에 매핑하는 것이다. 나머지 서비스에는 ports 설정이 없다.

이것이 바로 API Gateway 패턴의 핵심이다. 외부에서 접근할 수 있는 것은 Gateway뿐이고, 백엔드 서비스는 Docker 네트워크 내부에서만 접근 가능하다.

depends_on

api-gateway가 depends_on으로 세 서비스를 지정한다. Docker Compose가 백엔드 서비스를 먼저 시작한 뒤에 Gateway를 시작한다.

단, 이것은 컨테이너의 시작 순서만 보장한다. 서비스가 실제로 요청을 받을 준비가 되었는지까지는 확인하지 않는다. 그래서 healthcheck가 필요하다.

environment

환경 변수로 Spring Boot의 프로파일과 포트를 주입한다. SPRING_PROFILES_ACTIVE=docker는 application.yml의 docker 프로파일을 활성화시킨다. 코드 변경 없이 환경에 따라 설정을 바꿀 수 있는 12-Factor App 원칙이다.

Docker 네트워크 — 서비스 간 통신

Docker Compose는 기본적으로 같은 Compose 파일의 서비스를 하나의 네트워크에 연결한다. 실습에서는 microservices-network라는 bridge 네트워크를 명시적으로 정의한다.

이 네트워크 안에서 각 컨테이너는 서비스 이름을 DNS 이름으로 사용할 수 있다. Nginx 설정의 server user-service:8081에서 user-service가 IP 주소가 아닌 이름인 이유가 바로 이것이다.

외부에서는 80번 포트를 통해 Gateway에만 접근할 수 있다. 보라색 네트워크 영역 안에서는 서비스 이름으로 자유롭게 통신하지만, 이 통신은 외부에 노출되지 않는다.

헬스체크 — 서비스 상태 확인

컨테이너가 떠 있다고 해서 애플리케이션이 정상인 것은 아니다. Java 프로세스가 살아 있어도 Spring Boot가 초기화를 끝내지 않았을 수 있다. 헬스체크는 애플리케이션이 실제로 요청을 처리할 수 있는 상태인지를 주기적으로 확인한다.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8081/actuator/health"]
  interval: 30s
  timeout: 10s
  retries: 3

30초마다 Actuator의 health 엔드포인트에 요청을 보내고, 10초 안에 응답이 없으면 실패로 간주한다. 3번 연속 실패하면 컨테이너를 unhealthy 상태로 표시한다.

Nginx의 헬스체크는 좀 더 단순하다.

HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
    CMD curl -f http://localhost/health || exit 1

이 /health 엔드포인트는 Nginx 설정에서 직접 정의한 것이다. return 200으로 즉시 응답하므로 Nginx 프로세스가 정상 동작하는지만 확인한다.

자주 하는 실수