전체 메뉴

테마

Chapter 22

운영

Spring Boot 4.1.1 서비스에 요청 ID와 MDC 로그, 제한된 Actuator 상태·지표를 붙이고, 멀티 스테이지 Dockerfile·Compose·GitHub Actions·스모크 테스트로 패키징과 자동 검증을 구성합니다.

난이도
중급 심화
예상 학습
160분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 22입니다. 예제 코드는 공개 저장소 spring-boot-curriculum에서 확인할 수 있습니다.

Learning goals

오늘 배울 내용

  • MDC로 요청 로그를 묶고 입력 정제와 정리 보장하기
  • Actuator 엔드포인트를 필요한 범위만 노출하고 닫힌 경로 테스트하기
  • 멀티 스테이지 Dockerfile과 비루트 실행·헬스 체크 구성하기
  • Compose에서 DB 준비 순서와 볼륨 데이터 유지 이해하기
  • GitHub Actions 잡과 스모크 테스트 결과를 숫자와 실패 경로로 검증하기
  1. 요청 관측
  2. Actuator 상태·지표
  3. 멀티 스테이지 이미지
  4. Compose 실행
  5. CI 잡 분리
  6. 스모크 테스트
이 Chapter의 진행 흐름

기능을 만들고 테스트까지 마쳤다면, 이제 서버가 살아 있는지 보고, 같은 모양으로 띄우고, 바뀔 때마다 자동으로 확인해야 합니다. 이 Chapter는 운영의 세 가지 기본을 다룹니다.

  • 관측(예제 ch31-logging-actuator): 요청마다 번호를 붙인 로그, Actuator로 여는 상태와 지표.
  • 패키징(예제 ch32-docker): 멀티 스테이지 Dockerfile과 PostgreSQL을 함께 띄우는 compose.
  • 자동 검증(예제 ch33-cicd): GitHub Actions의 잡 분리, 이미지 빌드, 스모크 테스트.

세 가지에는 같은 교훈이 흐릅니다. “초록색 표시나 정상 기동”은 증거가 아니고, 직접 센 건수와 실패하는 경로를 직접 본 것만 믿을 수 있습니다.

이 Chapter에서 만드는 것

만드는 것 설명
RequestIdFilter 요청마다 번호를 정해 MDC에 넣고 응답 헤더로 돌려줌
Actuator 설정 health, info, metrics, loggers만 열고 나머지는 닫음
HealthIndicator, Micrometer 카운터 의존 시스템 상태와 주문 지표
멀티 스테이지 Dockerfile 빌드 도구를 이미지에 남기지 않고 층 캐시를 쓰는 이미지
docker-compose.yml 앱과 PostgreSQL, DB 준비 후 앱 시작, 볼륨
build.yml, image.yml 잡 분리, 이미지 빌드 후 스모크 테스트
smoke-test.sh 응답 본문과 DB 갱신까지 확인하는 점검 스크립트

ch31 테스트 15건, ch32 테스트 3건이 통과했고, 저장소 CI(PR #13)는 build 422건 통과/19건 SKIPPED/실패 0건, oracle 38건 통과, 이미지 스모크 테스트 통과였습니다.

직접 실행해 확인한 결과

확인 결과
ch31 test 15건 통과
ch32 test 3건 통과
ch31 실행: 요청 번호, 헤더 정제, Actuator 노출 X-Request-Id 반환, evil INFO forged → evilINFOforged, /actuator/env·beans 404, orders.placed 카운트 3
ch32 이미지 빌드 → 실행 빌드 성공(첫 시도는 Gradle 배포판 내려받기 중 네트워크 오류로 실패, 재시도 성공), 14초 안에 healthy, 사용자 uid=10001(app)
스모크 테스트 readiness UP, /hello ok, /visits ok (1 -> 2), SMOKE TEST PASSED
층 캐시 문자열 하나를 바꾼 뒤 재빌드: 의존성·로더·스냅샷 층은 CACHED, 애플리케이션 층만 다시 만들어짐

compose(PostgreSQL + 볼륨)와 GitHub Actions 실행, actionlint는 재검증에서 다시 실행하지 않았습니다. 해당 절의 결과는 원고 작성 시의 기록입니다.

사전 지식

  • Chapter 02의 설정 우선순위, Chapter 20의 통합 테스트.
  • Docker 사용 경험이 있으면 좋습니다.
  • 코드는 examples/ch31-logging-actuator, examples/ch32-docker, examples/ch33-cicd입니다.

확인 환경

Docker 컨테이너(JDK 21.0.11), Spring Boot 4.1.1, Micrometer 1.17.1, Docker Engine 29.5.2, Compose 5.1.4, GitHub Actions ubuntu-latest입니다. Windows와 macOS는 확인하지 못했습니다.

예제 코드

대상 링크
ch31 ch31-logging-actuator/
ch32 ch32-docker/
ch33 ch33-cicd/
요청 번호 필터 RequestIdFilter.java
설정 application.yml
상태 표시기 StockHealthIndicator.java
Actuator 테스트 ActuatorTests.java
Dockerfile Dockerfile
compose docker-compose.yml
설정 application.yml
스모크 테스트 smoke-test.sh
이미지 워크플로 image.yml
빌드 워크플로 build.yml

요청 하나의 로그를 번호로 따라가기

서버에 문제가 생겼다는 문의가 오면 먼저 로그를 봅니다. 그런데 요청이 동시에 여러 개 들어오는 서버의 로그는 한 줄 한 줄이 섞여 있어서, 어느 줄이 그 사용자의 요청인지 알 수 없습니다. 요청마다 번호를 붙여 로그를 묶으면 이 문제가 풀립니다.

필터가 번호를 정하고, 패턴이 꺼내 쓴다

필터가 요청마다 번호를 정해 MDC에 넣고, 로그 패턴이 %X{requestId}로 꺼내 씁니다.

logging:
  level:
    root: INFO
    com.jqdom.curriculum.ch31: DEBUG
  pattern:
    console: "%d{HH:mm:ss.SSS} %-5level [%X{requestId:-none}] %logger{20} - %msg%n"
  • %X{requestId:-none}: MDC의 requestId를 꺼내 쓰고, 없으면 none을 씁니다. 요청 밖의 로그는 [none]으로 보입니다.
  • 우리 패키지만 DEBUG로 낮춰 라이브러리 로그가 늘어나지 않게 했습니다.

주문 하나를 요청한 JAR의 실제 로그입니다. (패키지 이름을 바꾸기 전에 실행한 기록이라 로거 이름 약어는 현재 패키지와 다를 수 있습니다.)

08:12:19.720 DEBUG [9d1ee26c] c.d.c.c.OrderController - order requested item=book quantity=2
08:12:19.721 INFO  [9d1ee26c] c.d.c.c.OrderController - order created item=book quantity=2

번호가 같은 줄만 모으면 한 요청의 흐름입니다.

번호를 응답으로도 돌려준다

번호는 응답 헤더(X-Request-Id)로도 돌려줍니다. 사용자가 문의할 때 번호를 알려 줄 수 있고, 운영자는 그 번호로 로그를 검색합니다. 클라이언트가 같은 헤더를 보내면 그 값을 쓰고, 없으면 8자리를 만듭니다. 앞단(게이트웨이 등)에서 이미 번호를 붙였다면 그것을 이어 쓸 수 있다는 뜻입니다. 여러 서버를 건너는 분산 추적은 이 예제에서 다루지 않았습니다.

따라 하기

./gradlew :examples:ch31-logging-actuator:bootRun
curl -i -X POST http://localhost:8080/orders -H 'Content-Type: application/json' -d '{"item":"book","quantity":2}'
curl -i -X POST http://localhost:8080/orders -H 'Content-Type: application/json' -H 'X-Request-Id: my-req-1' -d '{"item":"pen","quantity":1}'
HTTP/1.1 201   X-Request-Id: 67956699              (서버가 번호를 정함)
HTTP/1.1 201   X-Request-Id: my-req-1              (클라이언트가 보낸 값이 그대로 돌아옴)

서버 로그에서 같은 번호끼리 묶입니다.

01:19:10.345 DEBUG [67956699] c.j.c.c.OrderController - order requested item=book quantity=2
01:19:10.345 INFO  [67956699] c.j.c.c.OrderController - order created item=book quantity=2
01:19:10.447 DEBUG [my-req-1] c.j.c.c.OrderController - order requested item=pen quantity=1

자주 하는 실수

실수 증상 해결
로그 패턴에 %X{requestId}가 없음 번호가 로그에 안 나옴 패턴에 추가
요청 밖의 로그가 [none]이어서 이상하다고 생각 정상 동작 :-none 기본값의 의미
응답 헤더로 번호를 돌려주지 않음 사용자 문의와 로그를 잇기 어려움 X-Request-Id 헤더 반환

확인 문제

  1. MDC는 무엇이고 왜 스레드마다 값이 다른가요?
  2. 요청 번호를 응답 헤더로도 돌려주는 이유는 무엇인가요?

답: 1) 로그 출력에 붙는 스레드별 맥락 값이며, 요청이 각자 다른 스레드에서 처리되므로 값도 다릅니다. 2) 사용자가 문의할 때 번호를 알려 주면 운영자가 그 요청의 로그만 찾을 수 있기 때문입니다.

직접 해 보기

  1. 주문을 두 개 동시에 보내고 로그를 번호로 나눠 보세요.
  2. 클라이언트가 X-Request-Id를 보내면 같은 값이 응답에 돌아오는지 확인하세요.
  3. 자신의 서비스 로그에 요청을 구분할 값이 있는지 점검하세요.

헤더 정제, MDC 정리, 구조화 로그

요청 번호를 로그에 넣는 구조에는 위험이 두 가지 따라옵니다. 클라이언트가 보낸 값을 그대로 로그에 쓰는 위험과 스레드가 재사용되며 번호가 남는 위험입니다. 이 절은 두 가지를 막는 코드와, 같은 로그를 JSON으로 내보내는 방법을 다룹니다.

헤더 값은 그대로 로그에 쓰지 않는다

클라이언트가 보낸 헤더 값이 그대로 로그에 들어가면, 줄바꿈이 섞인 값으로 가짜 로그 줄을 만들 수 있습니다. 필터에서 허용한 문자(영문, 숫자, ., _, -)만 남기고 64자로 자릅니다.

String cleaned = value.replaceAll("[^A-Za-z0-9._-]", "");

테스트에서 evil\r\nINFO forged line을 보내 보니 로그에는 [evilINFOforgedline]만 나타났고 가짜 줄은 생기지 않았습니다. 사용자 입력은 로그로 들어가기 전에도 입력으로 취급합니다.

요청이 끝나면 번호를 반드시 지운다

서블릿 컨테이너는 스레드를 재사용합니다. MDC를 지우지 않으면 다음 요청이 같은 스레드에서 실행될 때 이전 요청의 번호가 로그에 남습니다. 필터는 finally에서 MDC.remove를 합니다. 테스트가 요청 밖에서 로그를 찍어 번호가 [none]인 것을 확인하고, 이 MDC.remove 줄을 지우면 그 테스트가 실패합니다.

같은 로그를 JSON으로

로그 수집 시스템에 보낼 때는 줄글보다 JSON 한 줄이 다루기 쉽습니다. 설정 하나로 바꿀 수 있습니다.

--logging.structured.format.console=logstash
{"@timestamp":"2026-10-17T08:12:28.922863741Z","@version":"1","message":"order created item=pen quantity=1","logger_name":"com.jqdom.curriculum.ch31.OrderController","thread_name":"http-nio-8080-exec-1","level":"INFO","level_value":20000,"requestId":"10e02bc1"}
  • MDC에 넣은 requestId가 자동으로 JSON 필드가 됩니다. 번호를 패턴에 따로 적을 필요가 없습니다.
  • logger_name의 패키지는 개명 전 실행 기록입니다.
  • logstash 형식 하나만 확인했고, 다른 형식(ecs, gelf)은 확인하지 않았습니다.

따라 하기

curl -i -X POST http://localhost:8080/orders -H 'Content-Type: application/json' \
  -H 'X-Request-Id: evil INFO forged' -d '{"item":"pen","quantity":1}'
HTTP/1.1 201   X-Request-Id: evilINFOforged

공백이 제거되어 허용 문자(영문, 숫자, ., _, -)만 남았습니다. 줄바꿈(\r\n)도 같은 규칙으로 제거되므로 가짜 로그 줄을 만들 수 없습니다.

자주 하는 실수

실수 증상 해결
헤더를 정제 없이 MDC에 넣음 가짜 로그 줄 허용 문자만 남기고 길이 제한
MDC.remove를 finally가 아닌 곳에서 호출 예외 시 번호 누수 finally에서 제거
스레드가 재사용된다는 점을 잊음 다음 요청 로그에 이전 번호 요청 종료 시 반드시 제거

확인 문제

  1. 로그 주입(가짜 로그 줄)은 어떻게 막나요?
  2. 서블릿 컨테이너가 스레드를 재사용하면 MDC에서 어떤 일이 생길 수 있나요?

답: 1) 외부 입력을 허용 문자만 남기도록 정제합니다. 2) 지우지 않은 값이 다음 요청에 남아 다른 요청의 번호가 로그에 찍힙니다.

직접 해 보기

  1. evil\r\nINFO forged line을 직접 보내 로그에 가짜 줄이 생기지 않는지 확인하세요.
  2. MDC.remove를 지우고 어떤 테스트가 어떤 모양으로 실패하는지 보세요(아래 “로깅과 Actuator의 자주 만나는 오류” 절).
  3. 구조화 로그로 바꿨을 때 줄글 패턴 설정은 어떻게 되는지 확인해 보세요.

Actuator로 상태와 지표 열기

서버가 살아 있는지, 주문이 몇 건 들어왔는지를 로그를 뒤져 세고 있다면 운영이라고 부르기 어렵습니다. Actuator는 서버의 상태와 지표를 HTTP로 보여 줍니다.

필요한 것만 연다

기본으로는 health만 열려 있어서, 필요한 것만 명시해 열었습니다.

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,loggers

/actuator/env와 /actuator/beans는 열지 않았고, 요청하면 404입니다. 환경 변수와 빈 목록에는 민감한 정보가 들어 있을 수 있기 때문입니다.

내 시스템의 상태를 health에 넣는다

HealthIndicator를 구현하면 재고 시스템 같은 의존 대상의 상태가 /actuator/health의 구성 요소가 됩니다. 빈 이름에서 접미사를 뺀 stock이 구성 요소 이름입니다.

상황 HTTP 응답
재고 시스템 정상 200 status: UP, components.stock.status: UP
재고 시스템 중단 503 status: DOWN, components.stock.status: DOWN

구성 요소 하나만 DOWN이어도 전체가 DOWN이 되고 상태 코드가 503이 됩니다. 로드밸런서나 오케스트레이터가 이 코드를 보고 트래픽을 돌릴 수 있습니다. show-details: always는 학습 확인용이고, 외부에 열린 서버에서는 세부 정보를 제한해야 합니다. (실제 JAR 응답에서 stock 구성 요소는 캡처가 잘려 보지 못했고, 테스트로 확인했습니다.)

지표를 세고, 로그 레벨을 바꾼다

주문이 만들어질 때와 거절될 때 Micrometer 카운터를 올립니다.

Counter.builder("orders.placed").tag("result", "created").register(registry);
  • 테스트가 요청 세 번(성공 둘, 재고 중단 후 거절 하나) 뒤 카운터의 증가분을 확인하고, /actuator/metrics/orders.placed?tag=result:created로 같은 값을 읽을 수 있는 것도 확인합니다.
  • http.server.requests는 따로 코드를 쓰지 않아도 자동으로 측정됩니다.
  • /actuator/loggers로는 서버를 다시 띄우지 않고 로그 레벨을 바꿀 수 있습니다. 테스트에서 OrderController의 유효 레벨이 DEBUG인 것을 읽고, WARN으로 바꾼 뒤 다시 읽어 확인하고, 마지막에 원래대로 되돌립니다.

보안상 주의

Actuator 엔드포인트에는 인증을 붙이지 않았습니다. 특히 loggers의 쓰기 기능은 인증 없이 외부에 열면 안 됩니다. Chapter 21의 규칙으로 /actuator/**를 보호하는 방법은 이 예제에서 확인하지 않았습니다.

따라 하기

curl -s http://localhost:8080/actuator/health
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/actuator/env
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/actuator/beans
curl -s http://localhost:8080/actuator/metrics/orders.placed
{"components":{"diskSpace":{...,"status":"UP"},"livenessState":{"status":"UP"},"ping":{"status":"UP"},"readinessState":{"status":"UP"},"ssl":{...,"status":"UP"},"stock":{"details":{"reason":"stock service reachable"},"status":"UP"}},"groups":["liveness","readiness"],"status":"UP"}
404
404
{"availableTags":[{"tag":"result","values":["rejected","created"]}],"measurements":[{"statistic":"COUNT","value":3.0}],"name":"orders.placed"}

stock이 직접 만든 HealthIndicator의 결과이고, 노출하지 않은 env와 beans는 404입니다. orders.placed의 값 3은 “요청 하나의 로그를 번호로 따라가기”와 “헤더 정제, MDC 정리, 구조화 로그” 절에서 보낸 주문 세 건의 합입니다(이번 실행에서는 거절된 주문이 없으므로 rejected 태그는 값 목록에만 있고 개수는 0입니다).

자주 하는 실수

실수 증상 해결
exposure.include: "*" env, beans가 200으로 열림 필요한 것만 명시
의존 시스템 상태를 health에 넣지 않음 장애가 있어도 UP HealthIndicator 구현
loggers 쓰기를 인증 없이 공개 외부에서 로그 레벨 변경 가능 인증·네트워크 제한

확인 문제

  1. 구성 요소 하나가 DOWN이면 전체 health의 상태 코드는 무엇인가요?
  2. env와 beans를 닫아 두는 이유는 무엇인가요?

답: 1) 전체가 DOWN이 되고 상태 코드는 503입니다. 2) 설정 값과 내부 구조 같은 민감한 정보가 드러나기 때문입니다.

직접 해 보기

  1. /actuator/env가 404인지 직접 확인하세요.
  2. 재고 시스템을 중단 상태로 만들고 /actuator/health의 상태 코드를 확인하세요.
  3. 카운터에 태그를 하나 더 달아 값을 구분해 보세요.

로깅과 Actuator의 자주 만나는 오류

로깅과 Actuator의 실수는 서버가 정상으로 동작하면서 정보가 새거나 틀리는 모양입니다. 오류도 없고 서버도 멀쩡해서 테스트가 없으면 놓칩니다. 아래는 이 예제를 한 군데씩 바꿔 테스트를 돌려 얻은 결과이며, 바꾼 코드는 되돌렸고 저장소에는 올리지 않았습니다.

1. 다른 요청의 번호가 로그에 남는다

필터에서 MDC.remove(MDC_KEY)를 지웠습니다. 스레드가 재사용되므로 이전 요청의 번호가 다음 요청의 로그에 붙습니다.

mdcIsClearedAfterTheRequest(CapturedOutput)
Expecting actual:
  "14:13:49.888 INFO  [d034b535] o.s.t.c.s.AnnotationConfigContextLoaderUtils - Could not detect default configuration classes ...

요청과 무관한 테스트 시작 로그에 이전 요청 번호 [d034b535]가 찍혔습니다. 번호로 요청을 추적하는 시스템에서는 다른 사용자의 요청을 내 요청으로 착각하게 되는 위험한 모양입니다. 오류도 없으므로 요청이 끝난 뒤의 로그에 번호가 남지 않는지 보는 테스트로 고정해 둡니다. 15건 중 1건이 실패했습니다.

2. 헤더 값이 로그에 그대로 들어간다

sanitize(incoming) 호출을 incoming으로 바꿨습니다. 클라이언트가 보낸 X-Request-Id에 줄바꿈이나 특수 문자가 있으면 로그에 그대로 찍혀 가짜 로그 줄을 만들 수 있습니다.

unsafeHeaderCharactersAreStrippedBeforeTheyReachTheLog(CapturedOutput)
Expecting actual: "14:14:59.591 INFO  [none] o.s.t.c.s.AnnotationConfigContextLoaderUtils - ...

테스트는 위험한 문자를 포함한 헤더를 보내고 그것이 걸러지는지 확인하며, 걸러지지 않으면 실패합니다. 이 실험에서는 정제를 뺀 코드가 테스트에 걸리는 것까지만 확인했습니다. 가짜 로그 줄 주입은 일반적으로 알려진 유형입니다.

3. 필요 이상으로 열린 엔드포인트

management.endpoints.web.exposure.include를 "*"로 바꾸면 노출하지 않기로 한 엔드포인트가 열립니다.

endpointsThatWereNotExposedAreNotFound()
AssertionError: Status expected:<404> but was:<200>

“404여야 하는데 200”이 증상입니다. env, beans 같은 엔드포인트는 설정 값과 내부 구조를 보여 주므로 필요한 것만 명시해서 엽니다. 이것도 서버가 정상으로 떠서, 노출되지 않아야 할 경로를 요청하는 테스트가 없으면 놓칩니다.

증상 가장 먼저 볼 것
요청과 무관한 로그에 이전 번호 필터의 finally에서 MDC 제거
로그에 이상한 줄이 끼어듦 헤더 값 정제
열면 안 되는 /actuator/...가 200 exposure.include

직접 해 보기

  1. 세 가지 중 하나를 재현하고 원래대로 되돌려 보세요.
  2. 닫혀 있어야 하는 엔드포인트 목록을 만들고 모두 404인지 확인하는 테스트를 써 보세요.
  3. Chapter 21의 “조용히 열리는 오류”와 이 절의 3번을 비교해 보세요.

멀티 스테이지 Dockerfile

“내 컴퓨터에서는 되는데요”는 서버에 올리는 순간 자주 나오는 말입니다. JDK 버전, 환경 변수, 같이 떠야 하는 데이터베이스가 사람마다 다르기 때문입니다. 컨테이너는 앱과 실행 환경을 한 덩어리로 묶어 이 차이를 줄입니다. 이 절은 Spring Boot 앱을 이미지로 만드는 Dockerfile을 읽습니다.

두 단계로 나눈다

FROM eclipse-temurin:21-jdk-jammy AS build
WORKDIR /w
COPY . .
RUN ./gradlew :examples:ch32-docker:bootJar --no-daemon --no-build-cache -x test \
 && mkdir /extracted \
 && java -Djarmode=tools -jar examples/ch32-docker/build/libs/ch32-docker-0.0.1-SNAPSHOT.jar extract --layers --destination /extracted

FROM eclipse-temurin:21-jre-jammy
WORKDIR /app
RUN useradd --system --uid 10001 --no-create-home app
USER app
COPY --from=build /extracted/dependencies/ ./
COPY --from=build /extracted/spring-boot-loader/ ./
COPY --from=build /extracted/snapshot-dependencies/ ./
COPY --from=build /extracted/application/ ./

코드 읽기

  • 앞 단계(build)는 JDK와 Gradle로 JAR를 만들고 층별로 풉니다. 뒤 단계에는 JRE와 결과물만 복사하므로 JDK와 Gradle은 최종 이미지에 남지 않습니다. 완성된 이미지의 크기는 아래 “따라 하기”에서 봅니다.
  • extract --layers: JAR를 의존성, 로더, 스냅샷 의존성, 애플리케이션 층으로 풉니다. 코드만 바뀌면 변하지 않은 의존성 층은 캐시를 재사용합니다. 자주 바뀌는 application 층을 마지막에 복사한 것도 같은 이유입니다(Docker는 앞 층이 바뀌면 뒤 층 캐시를 쓰지 못합니다).
  • -x test: 이미지 빌드에서는 테스트를 건너뜁니다. 테스트는 CI의 build 잡이 따로 합니다(아래 “GitHub Actions: 잡 분리와 이미지 잡” 절).
  • useradd ... --uid 10001 + USER app: root가 아닌 사용자로 실행합니다. 실행 중인 컨테이너에서 id를 확인했더니 uid=10001(app)이었습니다.

헬스 체크: curl에 기대지 않기

HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 \
  CMD bash -c 'exec 3<>/dev/tcp/127.0.0.1/8080 && printf "GET /actuator/health/liveness HTTP/1.0\r\n\r\n" >&3 && grep -q "\"UP\"" <&3' || exit 1

HEALTHCHECK는 bash의 /dev/tcp로 직접 요청을 보내 응답에 "UP"이 있는지 봅니다. eclipse-temurin:21-jre-jammy 이미지에는 curl(7.81.0)이 들어 있는 것을 확인했습니다(2026-10-17). 그래도 이 방식을 쓴 것은 더 작은 실행 이미지로 바꾸면 curl이 사라질 수 있기 때문입니다. 다만 이 방식도 bash는 있어야 합니다. 앱이 뜨고 나면 컨테이너 상태가 healthy로 바뀌는 것을 확인했습니다. --start-period는 기동 중의 실패를 세지 않는 유예 시간입니다.

도구가 이미지에 있는지는 docker run --rm <이미지> sh -c 'which curl'로 바로 확인할 수 있으니 짐작하지 말고 확인하세요. 처음에 이 부분을 잘못 알았다가 바로잡은 경위는 아래 “Docker에서 자주 만나는 문제” 절에서 다룹니다.

따라 하기

저장소 루트에서 실행합니다.

docker build -f examples/ch32-docker/Dockerfile -t ch32-docker:local .
docker run -d --name ch32-app -p 18085:8080 ch32-docker:local
docker inspect --format '{{.State.Health.Status}}' ch32-app
docker exec ch32-app id
curl http://localhost:18085/hello
healthy                       (기동 후 약 14초)
uid=10001(app) gid=999(app) groups=999(app)
{"message":"hello from container"}

재검증에서 확인한 값입니다. 최종 이미지는 317MB였고, 같은 머신의 eclipse-temurin:21.0.11_10-jdk-jammy는 442MB, ...-jre-jammy는 286MB였습니다. 이 비교는 이미지 크기만 본 것이며 JDK 단일 이미지로 앱을 만들어 비교하지는 않았습니다.

빌드는 첫 시도에서 컨테이너 안 Gradle 배포판 내려받기 중 네트워크 오류로 실패했고, 같은 명령을 다시 실행하자 성공했습니다. 빌드가 가끔만 실패하면 재실행으로 재현되는지부터 확인합니다(아래 “Docker에서 자주 만나는 문제” 절의 3번).

층 캐시 확인

VisitController의 문자열 하나를 바꾸고 다시 빌드한 결과입니다.

단계 결과
최종 이미지의 useradd, dependencies, spring-boot-loader, snapshot-dependencies 복사 CACHED
application 복사 다시 수행

주석 한 줄만 추가한 경우에는 클래스 파일이 같아서 application 층까지 모두 CACHED였습니다. 캐시는 파일 내용 기준으로 판단된다는 점이 보입니다.

자주 하는 실수

실수 증상 해결
한 층에 모든 것을 복사 코드만 바뀌어도 전부 다시 만들어짐 층 분리, 자주 바뀌는 층을 마지막에
root로 실행 컨테이너 탈출 시 위험 증가 USER app
헬스 체크에 curl이 있다고 단정 이미지가 달라지면 실패 도구 존재를 확인하고 사용
빌드 도구를 최종 이미지에 남김 이미지가 커지고 공격 면 증가 멀티 스테이지

확인 문제

  1. 멀티 스테이지 빌드로 최종 이미지에서 빠지는 것은 무엇인가요?
  2. 코드만 바뀌었을 때 어느 층만 다시 만들어지나요?

답: 1) JDK와 Gradle 같은 빌드 도구입니다. 2) 애플리케이션 층입니다(의존성 층은 캐시를 재사용합니다).

직접 해 보기

  1. 소스 한 줄만 바꾸고 다시 빌드해 어떤 층이 캐시를 재사용하는지 출력으로 확인하세요.
  2. USER app 줄을 지우면 id가 어떻게 달라지는지 확인하세요.
  3. JDK 이미지로 같은 앱을 만들어 docker image ls로 크기를 비교해 보세요(이 Chapter는 기본 이미지 크기만 비교했습니다).

compose와 데이터 유지

앱만으로는 서비스가 되지 않습니다. 데이터베이스가 같이 떠야 합니다. docker compose는 여러 컨테이너를 파일 하나로 묶어 띄웁니다. 핵심은 시작 순서와 데이터가 어디에 남는가입니다.

앱은 DB가 준비된 뒤에 시작한다

app:
  depends_on:
    db:
      condition: service_healthy

depends_on만 쓰면 DB 컨테이너가 “떴다”는 사실만 기다립니다. DB가 접속을 받을 수 있는 상태(pg_isready)가 된 뒤에 앱을 시작하려면 service_healthy 조건이 필요합니다. 실행 로그에서 db가 Healthy가 된 다음에 app이 Starting으로 넘어가는 것을 확인했습니다.

설정은 환경 변수로 덮어쓴다

앱의 기본 DataSource는 인메모리 H2이고, 컨테이너에서는 환경 변수가 이를 덮어씁니다(Chapter 02의 우선순위).

environment:
  SPRING_DATASOURCE_URL: jdbc:postgresql://db:5432/app
  SPRING_DATASOURCE_USERNAME: app
  SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD 환경 변수를 지정하세요}
  • 접속 주소의 호스트가 localhost가 아니라 서비스 이름 db입니다. compose 네트워크 안에서는 서비스 이름이 주소입니다.
  • 비밀번호는 파일에 적지 않고 실행할 때 환경 변수로 받습니다. ${변수:?메시지} 형태라 지정하지 않으면 compose가 시작하지 않습니다. 실제로 DB_PASSWORD 없이 docker compose config를 실행하자 required variable DB_PASSWORD is missing a value로 멈췄습니다.

데이터는 컨테이너 밖에 남는다

방문 수를 세는 /visits로 데이터가 어디에 남는지 확인했습니다. compose 네트워크의 다른 컨테이너에서 요청한 결과입니다.

시점 GET /visits 결과
처음 두 번 {"visits":1}, {"visits":2}
앱 컨테이너만 재시작 {"visits":3}
docker compose down 후 다시 up {"visits":4}

앱을 다시 만들어도, 컨테이너를 모두 내렸다 올려도 숫자가 이어졌습니다. DB 데이터가 이름 있는 볼륨(db-data)에 있기 때문입니다. docker compose down -v는 볼륨까지 지웁니다. 이 확인에서는 마지막 정리에만 썼고 지운 뒤의 값은 읽지 않았습니다.

이 절의 확인 범위

/visits는 조회와 갱신을 한 트랜잭션에 묶었을 뿐 동시 요청에서의 정확성은 검증하지 않았습니다. 호스트에서 localhost로 호출하는 확인은 이 환경에서 못 하고 같은 compose 네트워크의 다른 컨테이너에서 서비스 이름으로 호출했습니다. 메모리 제한 같은 자원 설정은 하지 않았습니다. 이 절의 compose 결과(방문 수 1, 2, 3, 4)는 원고 작성 시의 기록이며 재검증에서 다시 실행하지 않았습니다.

자주 하는 실수

실수 증상 해결
depends_on만 사용 DB 준비 전에 앱이 접속을 시도해 실패 condition: service_healthy
접속 호스트를 localhost로 지정 앱 컨테이너 안에서 DB를 못 찾음 서비스 이름(db)
비밀번호를 compose 파일에 적음 저장소에 비밀 노출 ${DB_PASSWORD:?...}로 환경 변수 요구
볼륨 없이 down 데이터 사라짐 이름 있는 볼륨

확인 문제

  1. depends_on만 쓰면 무엇을 기다리나요?
  2. 컨테이너를 내렸다 올려도 데이터가 남는 이유는 무엇인가요?

답: 1) 컨테이너가 “떴다”는 사실만 기다립니다. 2) 데이터가 컨테이너 밖의 이름 있는 볼륨에 저장되기 때문입니다.

직접 해 보기

  1. condition: service_healthy를 지우고 앱이 DB보다 먼저 떠서 어떻게 되는지 보세요.
  2. DB_PASSWORD 없이 docker compose config를 실행해 메시지를 확인하세요.
  3. 볼륨 없이 down/up을 하면 값이 어떻게 되는지 확인하세요(주의: 데이터가 사라집니다).

Docker에서 자주 만나는 문제

컨테이너 문제는 컨테이너 안에서 무슨 일이 났는지를 먼저 봐야 합니다. 이 절은 예제를 검증하면서 실제로 겪은 것과, CI에서 쓰는 점검 명령을 증상별로 정리합니다.

1. 컨테이너가 시작하지 않는다: 포트 충돌

처음 up을 했을 때 앱 컨테이너가 시작되지 않았습니다. 이 PC에는 8080을 쓰는 다른 서버가 이미 떠 있었습니다(어느 프로세스인지는 확인하지 않았습니다).

Error response from daemon: failed to set up container networking: ... Bind for ...

Bind for ...가 나오면 포트 번호가 겹친 것입니다. 포트 매핑을 "${APP_PORT:-8080}:8080"으로 바꿔 환경 변수로 호스트 포트를 정할 수 있게 하면 재설정만으로 해결됩니다. 이 절의 compose 검증은 APP_PORT를 18080으로 바꾼 실행에서 얻은 값이고, 파일의 기본값은 8080입니다.

2. 떠 있는데 healthy가 아니다

HEALTHCHECK 결과는 컨테이너 상태에서 읽습니다. 이 저장소의 CI도 같은 방식으로 기다립니다.

docker inspect --format '{{.State.Health.Status}}' <컨테이너>   # starting / healthy / unhealthy
docker logs <컨테이너> | tail -50

starting은 기동 중이라 정상일 수 있습니다(--start-period 안). unhealthy면 docker logs로 앱이 정말 떴는지 먼저 봅니다. 헬스 체크 명령 자체가 틀린 경우(도구가 없거나 경로가 다름)에도 unhealthy가 되므로, 컨테이너 안에서 그 명령을 직접 실행해 봅니다.

3. 빌드가 한 번 실패했다가 다시 하면 된다

이미지 빌드가 중간에 한 번 실패했다가 같은 명령에서 성공한 적이 있습니다. 그 시점에 빌드 두 개가 동시에 돌고 있었다는 것만 알고 원인은 확인하지 못했습니다. 이런 일시적 실패는 CI에서 로그에 남기고 재실행하되, 같은 문제가 반복되면 원인을 찾습니다.

4. 설명이 틀렸던 것: JRE 이미지와 curl

처음에는 “JRE 이미지에는 curl이 없다”고 알고 있었습니다. 확인해 보니 eclipse-temurin:21-jre-jammy에는 curl이 들어 있었습니다(/usr/bin/curl, 7.81.0-1ubuntu1.30). 확인하지 않은 말을 쓰면 안 되는 사례여서 남겨 둡니다. 같은 문구가 저장소의 Dockerfile 주석에도 있어 별도 PR로 정정했습니다.

증상 가장 먼저 볼 것
Bind for ... failed 호스트 포트 충돌, APP_PORT
unhealthy docker logs, 헬스 체크 명령을 직접 실행
빌드가 가끔만 실패 동시 빌드, 재실행으로 재현되는지

재검증에서 겪은 일

재검증에서도 위 3번과 4번이 그대로 나타났습니다. 이미지를 빌드할 때 컨테이너 안 Gradle 배포판 내려받기가 네트워크 오류로 한 번 실패했다가 같은 명령으로 성공했고(3번과 같은 모양), eclipse-temurin:21-jre-jammy 이미지에서 which curl은 /usr/bin/curl을 돌려주어 4번의 정정이 재검증 환경에서도 맞았습니다.

직접 해 보기

  1. 8080을 쓰는 프로세스를 하나 띄우고 포트 충돌을 재현해 보세요.
  2. docker inspect로 헬스 상태가 starting에서 healthy로 바뀌는 시점을 지켜보세요.
  3. 자신의 문서에 “~가 없다”고 단정한 문장이 있다면 명령으로 확인해 보세요.

GitHub Actions: 잡 분리와 이미지 잡

푸시할 때마다 빌드가 돌고 초록색 표시가 뜨면 안심하게 됩니다. 하지만 초록색은 “워크플로가 오류 없이 끝났다”는 뜻일 뿐, 테스트가 실제로 돌았다는 뜻이 아닙니다. 이 절은 워크플로를 잡 단위로 나누고, 컨테이너 이미지를 빌드해 실제로 띄워 본 뒤 성공으로 보도록 만든 구성을 읽습니다.

잡을 나누면 실패한 곳이 보인다

build.yml은 잡 세 개로 이뤄져 있습니다.

잡 하는 일
build 전체 Gradle 빌드와 테스트 (Oracle이 필요한 테스트는 건너뜀)
oracle Oracle 컨테이너를 띄워 Oracle 테스트만 실행
frontend React 프로젝트 두 개에 같은 단계(npm ci, 테스트, 빌드)를 행렬(matrix)로 실행
strategy:
  fail-fast: false
  matrix:
    project:
      - examples/ch21-react-basics
      - examples/ch22-react-rest/frontend

fail-fast: false는 한 프로젝트가 실패해도 다른 프로젝트의 결과를 끝까지 보기 위한 설정입니다. (Chapter 14의 React 프로젝트 두 개입니다.)

워크플로에서 손본 것

예제 저장소의 PR #13에서 기존 워크플로에 세 가지를 더했습니다. 같은 브랜치에서 새 실행이 시작되면 이전 실행을 취소하는 concurrency(main은 취소하지 않음), 멈춘 잡이 러너를 오래 쓰지 않도록 하는 timeout-minutes, 그리고 액션 버전 올리기입니다. 이전 실행 로그에 setup-java v4 is deprecated 경고가 있어 checkout, setup-java, setup-gradle, setup-node, upload-artifact를 그 시점의 최신 메이저 버전으로 올렸고, 올린 뒤의 로그에서 사용 중단 경고가 없는 것을 확인했습니다. Gradle 자체가 출력하는 “Gradle 10과 호환되지 않는 기능” 경고는 그대로 남아 있습니다.

이미지 잡: 빌드하고, 띄우고, 확인한다

image.yml은 ch32의 이미지를 빌드하고, 컨테이너를 띄우고, 스모크 테스트가 통과해야 끝납니다.

on:
  pull_request:
    paths:
      - 'examples/ch32-docker/**'
      - 'examples/ch33-cicd/**'
      - '.dockerignore'
      - '.github/workflows/image.yml'

steps:
  - uses: docker/build-push-action@v7
    with:
      context: .
      file: examples/ch32-docker/Dockerfile
      load: true
      push: false
      tags: ch32-docker:ci
      cache-from: type=gha
      cache-to: type=gha,mode=max
  - run: docker run -d --name app -p 8080:8080 ch32-docker:ci
  - run: examples/ch33-cicd/smoke-test.sh http://localhost:8080 90
  • paths: 이미지와 관련 없는 변경에서는 이 잡을 돌리지 않습니다.
  • push: false, load: true: 레지스트리에 올리지 않고 러너의 Docker에 바로 올려 실행해 봅니다.
  • 층 캐시는 GitHub Actions 캐시(type=gha)에 저장합니다. 확인한 실행은 첫 실행이라 캐시를 재사용한 효과는 확인하지 못했습니다.

스모크 테스트가 확인하는 것

smoke-test.sh는 컨테이너가 떴다는 사실이 아니라 요청을 처리할 수 있는지를 봅니다.

  1. readiness 프로브가 UP이 될 때까지 기다립니다(제한 시간 안에 안 되면 실패).
  2. /hello의 본문이 예상과 같은지 확인합니다. 200만 보면 오류 페이지도 통과하기 때문입니다.
  3. 데이터베이스를 거치는 /visits를 두 번 불러 값이 정확히 1 늘었는지 확인합니다.

실제 CI 로그입니다.

readiness UP after about 4s
/hello ok
/visits ok (1 -> 2)
SMOKE TEST PASSED

로컬에서도 같은 스크립트를 썼습니다. 컨테이너를 띄워 통과하는 것을 확인했고, 존재하지 않는 주소를 주면 SMOKE TEST FAILED: readiness가 6초 안에 UP이 되지 않았습니다로 비정상 종료하는 것도 확인했습니다. 실패하는 경로를 직접 본 스크립트만 CI에서 믿을 수 있습니다. if: failure()로 실패했을 때 컨테이너 로그를 남기고, 이미지는 docker save로 파일을 만들어 아티팩트로 올렸습니다(보관 3일).

초록색 표시 대신 로그의 건수를 센다

PR #13의 build 잡 로그에서 테스트 결과를 줄 단위로 세었습니다.

잡 통과 건너뜀 실패
build 422 19 0
oracle 38 0 0

그 직전 실행의 346건에 PR #13까지 새로 추가된 예제 테스트 76건을 더한 값(422)과 맞습니다. 건너뛴 19건은 Oracle이 필요한 테스트이고 oracle 잡이 따로 실행합니다. build 잡 안에서 PostgreSQL 컨테이너 테스트 3건이 건너뛰지 않고 PASSED로 나온 것도 로그에서 확인했습니다. 숫자가 기대와 맞지 않으면 성공 표시가 있어도 원인을 찾아야 합니다.

로컬에서 같은 스모크 테스트 실행

이미지를 띄운 뒤 examples/ch33-cicd/smoke-test.sh를 실행했습니다.

readiness UP after about 0s
/hello ok
/visits ok (1 -> 2)
SMOKE TEST PASSED

자주 하는 실수

실수 증상 해결
초록색 표시만 보고 완료로 판단 건너뛴 테스트를 놓침 로그의 통과·건너뜀·실패 건수 확인
스모크 테스트가 200만 확인 오류 페이지도 통과 응답 본문과 DB 갱신까지 확인
paths 필터 없이 이미지 잡 실행 관련 없는 변경에도 빌드 paths로 제한
fail-fast 기본값 한 프로젝트 실패 시 나머지 결과를 못 봄 fail-fast: false

확인 문제

  1. 잡을 나누면 얻는 이점은 무엇인가요?
  2. 이미지 잡은 어떤 단계를 통과해야 성공으로 보나요?

답: 1) 실패했을 때 어디서 실패했는지 보입니다. 2) 이미지 빌드, 기동, 스모크 테스트까지 모두 통과해야 성공입니다.

직접 해 보기

  1. 자신의 CI 로그에서 통과/건너뜀/실패 건수를 세어 보세요.
  2. 스모크 테스트의 /hello 본문 확인을 빼고 오류 페이지가 통과하는지 가짜 서버로 시험해 보세요(아래 “CI에서 자주 만나는 실패” 절).
  3. paths 필터를 빼면 어떤 변경에서도 이미지 잡이 도는지 확인하세요.

CI에서 자주 만나는 실패

CI에서는 실패 모양이 로컬과 다르고 다시 돌려 보기도 오래 걸립니다. 이 절은 이 저장소에서 실제로 겪은 실패 하나와, 같은 종류의 실수를 로컬에서 재현해 얻은 메시지를 다룹니다.

1. 한 잡만 빨갛다: 테스트끼리 테이블을 지운다

이 커리큘럼의 첫 CI 실행에서 oracle 잡이 실패했습니다. 실패한 잡의 로그만 따로 볼 때는 gh run view <run-id> --log-failed를 씁니다.

OracleJsonColumnTests > recordRoundTripsThroughOracleJsonColumn() FAILED
    ScriptStatementFailedException: Failed to execute SQL script statement #1 ...: CREATE TABLE products ( ... )
        java.sql.SQLSyntaxErrorException: ORA-00955: name is already used by an existing object
OracleJsonTests > jsonValueExtractsScalar() FAILED
    ### Cause: java.sql.SQLSyntaxErrorException: ORA-00942: table or view "CURRICULUM"."PRODUCTS" does not exist

같은 테스트가 “이미 있다(ORA-00955)“와 “없다(ORA-00942)“를 번갈아 말하는 것이 단서입니다. 두 모듈이 같은 products 테이블 이름을 쓰고 있었고, Gradle이 두 모듈의 테스트를 병렬로 돌리면서 한쪽이 만들고 지우는 사이에 다른 쪽이 접근했습니다. 로컬에서는 한 모듈씩 돌려서 통과했기 때문에 CI에서만 드러났습니다. 테이블 이름을 모듈마다 다르게 하고, Oracle 잡에는 --no-parallel을 줬습니다. 병렬 실행이 원인이라는 설명은 --no-parallel 적용 후 통과한 결과에 근거합니다. Chapter 11에서 본 Oracle 오류 코드와 이어지는 이야기입니다. CI에서만 실패하고 로컬에서는 통과한다면 병렬 실행, 환경 변수 유무, 실행 순서를 먼저 의심합니다.

2. 워크플로 파일 자체의 실수

워크플로가 아예 시작하지 않거나 의도와 다르게 도는 문제는 GitHub에 올리기 전에 actionlint로 잡을 수 있습니다. build.yml에 실수를 하나씩 넣어 돌렸습니다(actionlint 1.7.7).

build.yml:21:5: unexpected key "timeout-minute" for "job" section. expected one of "concurrency", "container", ..., "timeout-minutes" ...
build.yml:22:0: could not parse as YAML: yaml: line 22: did not find expected '-' indicator [syntax-check]
build.yml:20:14: label "ubuntu-lastest" is unknown. available labels are "windows-latest", ... "ubuntu-latest", ...

각각 키 이름 오타, 들여쓰기 오류, 러너 이름 오타입니다. ${{ matrix.project }}의 project를 projet으로 틀린 경우는 actionlint가 알려 주지 못했습니다. 식 안의 이름 오류는 실행해 봐야 드러납니다. 도구가 모든 것을 잡아 주지는 않습니다.

원본 build.yml에도 actionlint가 알림 두 개를 냈습니다.

build.yml:60:9: shellcheck reported issue in this script: SC2129:style: Consider using { cmd1; cmd2; } >> file instead of individual redirects
build.yml:74:9: shellcheck reported issue in this script: SC2034:warning: i appears unused. Verify use (or export if used externally)

앞의 것은 >> "$GITHUB_ENV"를 여러 번 쓴 스타일 지적이고, 뒤의 것은 반복 변수 i를 쓰지 않았다는 경고입니다. 둘 다 동작에는 영향이 없어 이 예제는 고치지 않았습니다. 경고가 “있으면 안 되는 오류”는 아니라는 사례입니다.

3. 스모크 테스트가 실패하는 모양

smoke-test.sh가 실패 원인을 구분해서 알려 주는지, JDK의 HttpServer로 만든 가짜 서버로 상황을 만들어 확인했습니다.

서버가 하는 일 스크립트 출력
모두 정상 readiness UP after about 0s … SMOKE TEST PASSED
/hello가 200이지만 본문이 오류 JSON SMOKE TEST FAILED: /hello 응답이 예상과 다릅니다
/hello가 404 curl: (22) The requested URL returned error: 404 뒤에 SMOKE TEST FAILED: /hello ...
/visits 값이 늘지 않음 SMOKE TEST FAILED: /visits가 1씩 늘지 않았습니다 (first=1, second=1)
서버가 아예 없음 SMOKE TEST FAILED: readiness가 4초 안에 UP이 되지 않았습니다

두 번째 줄이 중요합니다. 본문을 확인하지 않고 200만 봤다면 오류 페이지가 통과했을 겁니다. 세 번째 경우는 curl -f가 4xx/5xx를 실패로 만들기 때문에 curl: (22)가 먼저 나옵니다. CI 로그에서 이 숫자(22)를 보면 “서버가 4xx/5xx를 돌려줬다”는 뜻입니다. 마지막 경우는 컨테이너가 시작하지 못했거나 포트가 다른 것이므로, 이미지 잡이 if: failure()로 남기는 컨테이너 로그를 먼저 봅니다.

증상 가장 먼저 볼 것
한 잡만 실패, 로컬은 통과 gh run view <id> --log-failed, 병렬 실행과 공유 자원
워크플로가 시작하지 않음 actionlint의 키·들여쓰기·러너 이름
초록색인데 건수가 이상함 로그에서 PASSED/SKIPPED 건수
스모크 테스트 실패 마지막 SMOKE TEST FAILED 사유, curl: (22)는 4xx/5xx

직접 해 보기

  1. gh run view <run-id> --log-failed로 최근 실패한 실행의 로그를 읽어 보세요.
  2. 워크플로의 키 이름을 일부러 틀리고 actionlint로 확인하세요.
  3. 가짜 서버로 스모크 테스트의 실패 경로를 하나 더 만들어 보세요.

한계와 다음 단계

운영 Chapter를 마무리하며 만든 것과 다루지 않은 것을 정리합니다.

만든 것

  • 요청 번호 로그, 입력 정제, MDC 정리, 구조화 로그(ch31).
  • 필요한 것만 연 Actuator, 사용자 정의 health, 지표와 로그 레벨 변경(ch31).
  • 멀티 스테이지 이미지, compose, 볼륨(ch32).
  • 잡 분리, 이미지 빌드, 스모크 테스트(ch33).

한계와 확인하지 않은 것

영역 항목 상태
관측 ELK 같은 로그 수집, Prometheus 같은 지표 수집 연동 다루지 않음
관측 분산 추적, 비동기 스레드에서의 MDC 전달 다루지 않음
관측 Actuator 엔드포인트 인증 붙이지 않음
관측 logstash 외 구조화 형식(ecs, gelf) 확인하지 않음
패키징 레지스트리 푸시, 이미지 취약점 점검, 멀티 아키텍처, 쿠버네티스 다루지 않음
패키징 JDK 단일 이미지와의 크기 비교, 자원 제한 하지 않음
패키징 macOS, Windows 확인하지 않음
CI/CD 배포 잡, secrets, Environments 승인 만들지 않음 (CD의 절반이 비어 있음)
CI/CD 포크 PR의 권한 제한 확인하지 않음
CI/CD Docker 층 캐시의 재사용 효과 첫 실행이라 비교하지 못함
CI/CD 액션을 커밋 해시로 고정 하지 않음 (메이저 태그만 사용)

이 Chapter의 일관된 교훈

영역 믿으면 안 되는 것 대신 믿을 것
관측 서버가 정상으로 떴다 닫혀야 하는 것이 닫혀 있는지 직접 시험
패키징 컨테이너가 떠 있다 healthy 상태와 데이터 유지 확인
CI 초록색 표시 로그의 건수와 실패 경로를 직접 본 스크립트

Chapter 21의 “조용히 열리는 오류”, Chapter 20의 “SKIPPED는 통과가 아니다”와 같은 이야기입니다.

재검증에서 다시 확인한 범위

항목 재검증
ch31 테스트·실행, ch32 테스트·이미지 빌드·기동, 스모크 테스트 직접 실행
compose + PostgreSQL + 볼륨 다시 실행하지 않음
GitHub Actions 실행, actionlint 다시 실행하지 않음(원고 작성 시 기록)
macOS, Windows 확인하지 않음

직접 해 보기

  1. 위 표에서 가장 걸리는 항목 하나를 골라 보완 계획을 세워 보세요.
  2. 자신의 CI에 스모크 테스트를 추가한다면 무엇을 확인할지 목록을 만들어 보세요.
  3. 이 Chapter의 세 교훈 중 자신의 프로젝트에서 가장 취약한 것을 고르세요.

용어와 참고 자료

Chapter 22의 용어를 모았습니다.

용어

용어 설명 나온 곳
MDC 스레드별로 값을 붙여 두고 로그 패턴에서 꺼내 쓰는 로깅 기능입니다. 요청 하나의 로그를 번호로 따라가기
요청 번호(requestId) 요청 하나를 구분하려고 로그와 응답 헤더에 붙이는 값입니다. 요청 하나의 로그를 번호로 따라가기
로그 주입 사용자 입력에 줄바꿈 등을 넣어 가짜 로그 줄을 만드는 공격 유형입니다. 헤더 정제, MDC 정리, 구조화 로그
구조화 로그 로그 한 줄을 JSON 같은 정해진 구조로 내보내는 형식입니다. 헤더 정제, MDC 정리, 구조화 로그
Actuator 서버의 상태와 지표를 HTTP 엔드포인트로 보여 주는 Spring Boot 모듈입니다. Actuator로 상태와 지표 열기
HealthIndicator health 응답의 구성 요소 하나를 만드는 인터페이스입니다. Actuator로 상태와 지표 열기
Micrometer 지표를 모으는 라이브러리로, 카운터와 타이머를 제공합니다. Actuator로 상태와 지표 열기
이미지(image) 컨테이너를 만드는 읽기 전용 틀입니다. 앱과 실행 환경이 들어 있습니다. 멀티 스테이지 Dockerfile
멀티 스테이지 빌드 빌드용 단계와 실행용 단계를 나눠 실행 이미지에는 결과물만 담는 방식입니다. 멀티 스테이지 Dockerfile
층(layer) 이미지를 이루는 변경 단위입니다. 바뀌지 않은 층은 캐시가 재사용됩니다. 멀티 스테이지 Dockerfile
헬스 체크 컨테이너가 정상인지 주기적으로 확인하는 명령입니다. 멀티 스테이지 Dockerfile
볼륨(volume) 컨테이너가 사라져도 남는 데이터 저장소입니다. compose와 데이터 유지
compose 여러 컨테이너를 파일 하나로 정의해 함께 띄우는 도구입니다. compose와 데이터 유지
워크플로 저장소의 이벤트에 반응해 실행되는 자동화 절차를 정의한 파일입니다. GitHub Actions: 잡 분리와 이미지 잡
잡(job) 같은 러너에서 실행되는 스텝의 묶음입니다. 잡끼리는 기본으로 병렬 실행됩니다. GitHub Actions: 잡 분리와 이미지 잡
행렬(matrix) 같은 잡을 입력 값만 바꿔 여러 번 실행하는 설정입니다. GitHub Actions: 잡 분리와 이미지 잡
아티팩트 실행이 끝난 뒤에도 내려받을 수 있게 저장한 결과 파일입니다. GitHub Actions: 잡 분리와 이미지 잡
스모크 테스트 배포된 것이 기본적으로 동작하는지 빠르게 확인하는 최소한의 점검입니다. GitHub Actions: 잡 분리와 이미지 잡
actionlint GitHub Actions 워크플로 파일의 문법 오류를 점검하는 도구입니다. CI에서 자주 만나는 실패

참고 자료

직접 해보기

  1. ./gradlew :examples:ch31-logging-actuator:bootRun으로 서버를 켜고 주문 요청을 세 번 보내 보세요. 헤더 없이 한 번, X-Request-Id: my-req-1을 붙여 한 번, X-Request-Id: evil INFO forged를 붙여 한 번입니다. 응답 헤더의 번호와 로그의 [...] 번호가 같은지, 마지막 값이 evilINFOforged로 정제되어 돌아오는지 확인합니다.
  2. 필터의 finally에서 MDC.remove를 지우고 테스트를 실행해 mdcIsClearedAfterTheRequest가 어떤 메시지로 실패하는지 읽어 보세요. 되돌린 뒤 management.endpoints.web.exposure.include를 "*"로 바꿔 endpointsThatWereNotExposedAreNotFound가 “404여야 하는데 200”으로 실패하는 것도 확인하고 다시 되돌립니다.
  3. 저장소 루트에서 docker build -f examples/ch32-docker/Dockerfile -t ch32-docker:local .로 이미지를 만들고 컨테이너를 띄운 뒤, docker inspect --format '{{.State.Health.Status}}' ch32-app이 healthy로 바뀌는지, docker exec ch32-app id가 uid=10001(app)인지 보세요. 이어서 VisitController의 문자열 하나만 바꿔 다시 빌드하고 어느 층이 CACHED로 나오는지 확인합니다.
  4. DB_PASSWORD 없이 docker compose config를 실행해 required variable DB_PASSWORD is missing a value 메시지를 확인하세요. condition: service_healthy를 지우면 앱이 DB보다 먼저 떠서 어떻게 되는지도 시험해 봅니다.
  5. 컨테이너를 띄운 상태에서 examples/ch33-cicd/smoke-test.sh http://localhost:8080 90을 실행해 SMOKE TEST PASSED를 확인하고, 존재하지 않는 주소를 넘겨 SMOKE TEST FAILED로 끝나는 실패 경로도 직접 보세요. 자신의 CI 로그에서 통과·건너뜀·실패 건수를 세어 보는 것으로 마무리합니다.

이번 장의 정리

  • 요청 번호는 필터가 정해 MDC에 넣고, 로그 패턴 %X{requestId:-none}과 응답 헤더 X-Request-Id로 드러냅니다. 클라이언트가 보낸 값은 허용 문자(영문, 숫자, ., _, -)만 남기고 64자로 잘라 가짜 로그 줄을 막습니다.
  • 서블릿 컨테이너는 스레드를 재사용하므로 MDC 값은 finally에서 반드시 지웁니다. --logging.structured.format.console=logstash 설정 하나로 같은 로그를 JSON으로 내보내면 requestId가 자동으로 필드가 됩니다.
  • Actuator는 health, info, metrics, loggers만 명시해 열고 env, beans는 404로 둡니다. HealthIndicator로 넣은 구성 요소 하나만 DOWN이어도 전체가 503이 되며, loggers의 쓰기 기능은 인증 없이 외부에 열면 안 됩니다.
  • 로깅과 Actuator의 실수는 서버가 정상으로 뜬 채 정보가 새는 모양이라, 번호 누수·헤더 미정제·과다 노출을 각각 실패하는 테스트로 고정해 둡니다.
  • 멀티 스테이지 Dockerfile은 JDK와 Gradle을 빌드 단계에만 두고 실행 이미지에는 JRE와 결과물만 담습니다. 자주 바뀌는 application 층을 마지막에 복사해 캐시를 살리고, uid 10001 사용자와 bash /dev/tcp 헬스 체크로 실행합니다.
  • compose는 condition: service_healthy로 DB가 준비된 뒤 앱을 시작하고, 서비스 이름 db로 접속하며, 이름 있는 볼륨 db-data로 데이터를 남깁니다. 비밀번호는 ${DB_PASSWORD:?...}로 실행할 때 받습니다. 컨테이너 문제는 Bind for ...면 포트 충돌, unhealthy면 docker logs와 헬스 체크 명령 직접 실행 순서로 좁힙니다.
  • GitHub Actions는 build, oracle, frontend 잡을 나누고, 이미지 잡은 빌드·기동·스모크 테스트를 모두 통과해야 성공으로 봅니다. 스모크 테스트는 200만 보지 않고 /hello 본문과 /visits 값이 1 늘었는지까지 확인합니다.
  • 초록색 표시 대신 로그의 건수(build 422건 통과·19건 건너뜀·0건 실패)를 직접 셉니다. CI에서만 실패하면 병렬 실행, 환경 변수, 실행 순서를 먼저 의심하고, 워크플로 파일은 actionlint로 점검하되 식 안의 이름 오류는 잡지 못한다는 점을 기억합니다.

다음 Chapter 23 종합 프로젝트 1: 설계와 백엔드에서는 지금까지 배운 것을 게시판 하나에 모아, 코드를 쓰기 전에 범위와 모듈 규칙부터 고정합니다.

FAQ

자주 묻는 질문

MDC 값을 요청이 끝난 뒤 지워야 하는 이유는 무엇인가요?

서버 스레드는 다음 요청에 재사용될 수 있으므로 지우지 않으면 이전 요청 번호가 다른 요청의 로그에 섞일 수 있습니다.

Actuator 엔드포인트를 모두 열면 안 되나요?

환경과 빈, 설정 같은 민감한 운영 정보가 노출될 수 있습니다. 필요한 health·info·metrics·loggers만 명시하고 나머지가 닫혔는지 확인합니다.

멀티 스테이지 Dockerfile의 장점은 무엇인가요?

빌드 도구와 소스는 빌드 단계에 두고 실행 이미지에는 필요한 결과와 런타임만 남겨 이미지 범위와 공격 면을 줄입니다.

스모크 테스트는 200 응답만 보면 되나요?

이 예제는 readiness와 본문뿐 아니라 DB 값이 실제로 1에서 2로 바뀌는지도 확인합니다. 핵심 기능의 결과까지 검사해야 합니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토