dpdpdndn 블로그

INFRA-02-compose-lb-nginx-다중인스턴스

NEW2 min read

[INFRA-02] docker-compose.lb.yml + nginx LB — backend 다중 인스턴스

작업 내용 (설계 의도)

변경 사항

근거 TDD: ../TDD.md “nginx LB 설계”·“compose 파일 소유 경계”, ADR-003. FR-1. ⑦ 전용 파일만 생성 — base·override(⑧)·observability(⑤) 무수정, 추가 -f로 병합.

  • docker-compose.lb.yml(신규, ⑦ 소유) — backend 서비스에 deploy.replicas: 3, host 포트 미노출(내부 8080만), healthcheck: /actuator/health. nginx-lb 서비스(80/443 노출, infra/nginx/lb.conf 마운트, depends_on: backend).
  • infra/nginx/lb.conf(신규, ⑦ 소유) — upstream sports_backend { server backend:8080; }(이름 재사용), resolver 127.0.0.11 valid=10s + 변수 proxy_pass로 replica 매 요청 재해석(라운드로빈), proxy_next_upstream error timeout http_502 http_503로 비정상 replica 우회. mcp.conf 무수정.

롤백: -f docker-compose.lb.yml 미적용(오버레이 OFF) → backend 직접 노출 복귀, nginx-lb down.

의존

  • 없음 (wave 1 기반). 런타임 선행: ⑧의 backend 서비스 정의(base compose)가 존재해야 병합 유효.

다이어그램

처리 흐름

sequenceDiagram
    participant C as k6/클라이언트
    participant N as nginx-lb
    participant D as Docker DNS
    participant B as backend replica
    C->>N: HTTP 요청
    N->>D: resolve backend
    D-->>N: replica IP 3종
    N->>B: 라운드로빈 프록시
    B-->>N: 200 (비정상 시 next_upstream)
    N-->>C: 응답

테스트 케이스

  • docker compose -f docker-compose.yml -f docker-compose.lb.yml config가 exit 0으로 병합된다.
  • nginx -t가 lb.conf를 오류 없이 검증한다.
  • 3 replica 기동 후 반복 요청이 3개 인스턴스에 분산된다(access log·host 태그로 확인).
  • replica 1개를 내리면 nginx가 남은 인스턴스로 페일오버하고 5xx가 발생하지 않는다.
  • 오버레이 미적용 시 기존 backend 단일 노출 흐름이 그대로 동작한다(롤백 안전).

그래프 뷰