sayu.day

· 4분 읽기

컨테이너 배포 실무: Docker 멀티스테이지 빌드와 Helm 환경별 Values 관리

#backend#devops#docker#helm

컨테이너 배포는 크게 두 단계로 나뉩니다. 좋은 이미지를 만드는 일과, 그 이미지를 환경마다 올바른 설정으로 배포하는 일입니다. 앞 단계가 부실하면 보안과 빌드 속도가 무너지고, 뒤 단계가 부실하면 환경 간 drift로 배포 사고가 납니다. 이 글은 Docker 멀티스테이지 빌드로 이미지를 다듬는 기준과 Helm values 오버라이드로 환경별 설정을 관리하는 구조를 하나의 실무 흐름으로 정리합니다.

이미지 만들기: 멀티스테이지 빌드

멀티스테이지의 목적은 단순한 이미지 크기 축소가 아닙니다.

  • 런타임 공격 표면 축소
  • 빌드 캐시 효율 개선
  • 배포 속도와 일관성 향상

기본 패턴

FROM golang:1.23 AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/server ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=builder /out/server /server
USER nonroot:nonroot
ENTRYPOINT ["/server"]

핵심은 "빌드 도구를 런타임 이미지에 남기지 않는 것"입니다. 컴파일러, 패키지 매니저, 소스코드는 builder 스테이지에 두고, 런타임 스테이지에는 실행에 필요한 산출물만 복사합니다.

캐시 최적화 규칙

레이어 캐시는 변경이 생긴 지점부터 아래로 모두 무효화됩니다. 자주 바뀌지 않는 것을 위로 올리는 것이 원칙입니다.

  • 의존성 파일(go.mod, package-lock)을 먼저 복사합니다.
  • 소스 복사는 그다음에 합니다.
  • --mount=type=cache로 패키지 캐시를 활용합니다.

베이스 이미지 선택 기준

  • scratch: 정적 바이너리가 가능할 때
  • distroless: 보안 우선, 셸이 불필요할 때
  • alpine/slim: 디버깅이나 호환성이 필요할 때

환경별로 배포하기: Helm values 오버라이드

이미지가 준비되면 다음 문제는 설정입니다. 환경(dev/int/stage/prod)이 늘어날수록 값 파일이 복제되고 drift가 생깁니다. 핵심은 공통값과 환경값의 경계를 명확히 두는 것입니다.

권장 구조

  • values.application.yaml: 앱 공통
  • values.infra.yaml: 인프라 공통
  • <env>/values.*.yaml: 환경별 오버라이드

병합 순서

오버라이드는 뒤 파일이 앞 파일을 덮습니다.

helm template my-service \
  -f values.infra.yaml \
  -f values.application.yaml \
  -f int/values.infra.yaml \
  -f int/values.application.yaml \
  ./int

운영 규칙

  • 공통 파일에는 "모든 환경에서 진짜 공통"인 값만 둡니다.
  • 환경 파일에는 차이값만 기록합니다.
  • 시크릿은 values에 직접 저장하지 않고 외부 secret store와 연동합니다.

자주 하는 실수 체크리스트

빌드 단계에서 점검할 항목입니다.

  • 런타임 이미지에 빌드 도구나 소스코드가 남아 있지 않은가
  • latest 태그에 고정해 재현성을 해치고 있지 않은가
  • 멀티스테이지인데도 불필요한 파일을 복사하고 있지 않은가
  • 의존성 파일 복사 후 소스 복사라는 캐시 순서를 지키고 있는가

배포 설정 단계에서 점검할 항목입니다.

  • 환경별 파일에 공통값을 복사해 drift를 만들고 있지 않은가
  • 병합 순서를 팀마다 다르게 쓰고 있지 않은가
  • 실환경 적용 전 helm template 검증을 생략하지 않았는가
  • 시크릿을 values 파일에 직접 넣고 있지 않은가

정리

  • 좋은 Dockerfile의 기준은 "작다"가 아니라 "예측 가능하고 안전하다"입니다. 멀티스테이지, 캐시 순서, 최소 런타임 이미지를 기본 규칙으로 둡니다.
  • Helm values 전략의 핵심은 파일 개수가 아니라 규칙 일관성입니다. 병합 순서와 값 경계를 고정하면 GitOps 운영 안정성이 크게 올라갑니다.
  • 빌드와 배포 설정은 별개의 작업이 아니라 하나의 파이프라인입니다. 두 단계의 규칙을 함께 문서화해 두어야 환경이 늘어나도 흔들리지 않습니다.