레이블이 Docker/K8s인 게시물을 표시합니다. 모든 게시물 표시
레이블이 Docker/K8s인 게시물을 표시합니다. 모든 게시물 표시

목요일

Docker 멀티스테이지 빌드 캐시 최적화하기

🔍 검색 키워드: Docker 멀티스테이지 빌드, Dockerfile 캐시 성능, Docker 레이어 캐싱, 빌드 시간 단축

Docker 멀티스테이지 빌드 캐시 최적화하기

증상

Dockerfile로 이미지를 빌드할 때마다 다음과 같은 문제가 발생한다:

$ docker build -t myapp:latest .
  Step 3/10 : RUN npm install    # 매번 30초 이상 소요
  Step 4/10 : RUN npm run build  # 매번 60초 이상 소요
  ...
  real    2m 15s

코드는 조금만 바뀌었는데도 빌드 시간이 계속 길어진다. CI/CD 파이프라인에서 빌드만 몇 분씩 걸려서 배포 속도가 느리다. 특히 npm, pip 같은 의존성 설치 단계가 매번 전부 다시 실행된다.

원인

Docker는 각 RUN, COPY, ADD 단계를 하나의 레이어로 취급하고, 파일이 변경되면 그 이후의 모든 레이어를 다시 빌드한다. 예를 들어:

FROM node:18
  COPY . /app              # 레이어1: 모든 파일 복사
  WORKDIR /app
  RUN npm install          # 레이어2: 의존성 설치 (레이어1 변경되면 캐시 무효)
  RUN npm run build        # 레이어3: 빌드 (레이어2 변경되면 캐시 무효)

코드를 한 줄만 바꿔서 COPY . /app을 실행하면 npm install, npm run build가 모두 다시 실행된다. 즉, 캐시를 제대로 활용하지 못한다.

멀티스테이지 빌드를 사용하면서도 각 스테이지 간 의존성이 꼬여 있으면 캐시 효율이 떨어진다.

해결방법

1. 의존성 파일을 먼저 복사 (핵심!)

FROM node:18 AS builder
  
  WORKDIR /app
  
  # package.json, package-lock.json만 먼저 복사
  COPY package*.json ./
  
  # 의존성 설치 (코드 변경 시 캐시 유지)
  RUN npm ci
  
  # 이제 코드 복사
  COPY . .
  
  # 빌드
  RUN npm run build
  
  # 런타임 스테이지
  FROM node:18-alpine
  
  WORKDIR /app
  
  # 의존성만 복사 (빌드 아티팩트 불필요)
  COPY --from=builder /app/node_modules ./node_modules
  COPY --from=builder /app/dist ./dist
  COPY package*.json ./
  
  EXPOSE 3000
  CMD ["node", "dist/index.js"]

캐시 효과:

  • package.json 불변 → npm install 캐시 유지
  • 코드만 변경 → COPY . . 부터만 재실행
  • 빌드 시간 30초 → 5초

2. Docker Buildkit으로 고급 캐싱 활용

// syntax=docker/dockerfile:1.4
  
  FROM node:18 AS builder
  
  WORKDIR /app
  
  COPY package*.json ./
  
  // --mount=type=cache로 npm cache 디렉토리 보존
  RUN --mount=type=cache,target=/root/.npm \
      npm ci --prefer-offline
      
      COPY . .
      RUN npm run build
      
      FROM node:18-alpine
      
      WORKDIR /app
      
      COPY --from=builder /app/node_modules ./node_modules
      COPY --from=builder /app/dist ./dist
      COPY package*.json ./
      
      EXPOSE 3000
      CMD ["node", "dist/index.js"]

빌드 명령:

DOCKER_BUILDKIT=1 docker build -t myapp:latest .

효과:

  • npm cache가 빌드 간에 유지되어 더 빠름
  • 오프라인 설치 최적화

3. 불필요한 파일 제외 (.dockerignore)

.git
  .gitignore
  node_modules
  npm-debug.log
  .env
  .env.local
  dist
  build
  coverage
  .DS_Store
  README.md

효과:

  • COPY . . 시 변경되지 않은 파일이 많으면 해시 계산이 더 오래 걸림
  • .dockerignore로 제외하면 캐시 재계산 범위 축소

4. 여러 스테이지에서 캐시 공유

// syntax=docker/dockerfile:1.4
  
  FROM node:18 AS dependencies
  
  WORKDIR /app
  COPY package*.json ./
  
  RUN --mount=type=cache,target=/root/.npm \
      npm ci
      
      // 빌드 스테이지1
      FROM dependencies AS builder1
      
      COPY . .
      RUN npm run build
      
      // 빌드 스테이지2 (테스트)
      FROM dependencies AS tester
      
      COPY . .
      RUN npm test
      
      // 최종 스테이지
      FROM node:18-alpine
      
      WORKDIR /app
      
      COPY --from=builder1 /app/dist ./dist
      COPY --from=dependencies /app/node_modules ./node_modules
      COPY package*.json ./
      
      EXPOSE 3000
      CMD ["node", "dist/index.js"]

5. 번들 사이즈 최소화 (캐시 영향 없지만 이미지 크기 감소)

FROM node:18 AS builder
  
  WORKDIR /app
  COPY package*.json ./
  RUN npm ci
  
  COPY . .
  RUN npm run build
  
  // 크기 최소화: dependencies만 복사, devDependencies 제외
  FROM node:18-alpine
  
  WORKDIR /app
  
  COPY --from=builder /app/dist ./dist
  
  // 본번 의존성만 설치 (devDependencies 없음)
  COPY package*.json ./
  RUN npm ci --omit=dev
  
  EXPOSE 3000
  CMD ["node", "dist/index.js"]

정리표

문제 원인 해결법
npm install 매번 재실행 COPY . . 후 RUN npm install package.json만 먼저 복사
캐시가 가끔만 작동 불필요 파일 포함 시 해시 변경 .dockerignore 작성
빌드 시간 여전히 길다 npm cache 미보존 Buildkit + --mount=cache 활용
이미지 크기 커짐 devDependencies 포함 npm ci --omit=dev
멀티스테이지 간 캐시 미공유 각 스테이지가 독립적 dependencies AS 공용 스테이지 생성

TIP: docker build --progress=plain으로 상세 로그 확인, docker image history myapp:latest로 각 레이어 크기 확인 가능. 캐시 강제 무효화는 docker build --no-cache 또는 COPY . . --chown=node:node 같은 타임스탐프 변경 명령으로.

수요일

Kubernetes CrashLoopBackOff 원인과 해결 — 재시작 대기 시간(10초~300초)과 kubectl logs --previous

🔍 검색 키워드: Kubernetes CrashLoopBackOff 원인, CrashLoopBackOff 재시작 대기 시간, kubectl logs --previous, restartPolicy Always 백오프, maxContainerRestartPeriod 설정, 쿠버네티스 파드 계속 재시작

요약: CrashLoopBackOff는 컨테이너가 시작 직후 계속 종료되어 kubelet이 재시작 간격을 점점 늘리는 중이라는 상태 표시이며, 그 자체가 원인은 아닙니다. kubectl describe로 컨테이너 상태와 재시작 횟수를 보고, kubectl logs --previous로 직전에 죽은 컨테이너의 로그를 확인해 실제 원인을 찾아야 합니다.

CrashLoopBackOff는 무엇을 뜻하나요?

Kubernetes 공식 문서(Pod Lifecycle)는 이 상태를 "백오프 지연 메커니즘이 현재 적용 중이며, 컨테이너가 실패와 재시작을 반복하는 크래시 루프에 있음을 나타낸다"는 취지로 설명합니다. 같은 문서는 CrashLoopBackOff가 kubectl로 파드를 조회하거나 describe할 때 볼 수 있는 상태 또는 이벤트이며, 컨테이너가 제대로 시작하지 못하고 계속 실패하는 경우에 나타난다고 설명합니다. 즉 CrashLoopBackOff는 에러 이름이 아니라 "재시작을 반복하고 있고 대기 중"이라는 현상입니다.

재시작은 얼마 간격으로 일어나나요?

공식 문서에 따르면 파드의 spec에는 restartPolicy 필드가 있고 값은 Always, OnFailure, Never이며 기본값은 Always입니다. 컨테이너가 종료되면 kubelet이 지수 백오프 지연(10초, 20초, 40초, ...)을 두고 다시 시작하며, 지연은 최대 300초(5분)로 제한됩니다. 컨테이너가 문제없이 10분 동안 실행되면 kubelet은 그 컨테이너의 재시작 백오프 타이머를 초기화합니다.

재시작 횟수대기 시간(기본값)
1번째 이후10초
2번째 이후20초
3번째 이후40초
이후 계속 2배최대 300초(5분)에서 고정

위 표는 공식 문서가 밝힌 규칙(10초에서 시작해 2배씩 증가, 최대 300초)을 정리한 것입니다. 클러스터 버전이나 설정에 따라 값이 다를 수 있습니다.

재시작 대기 시간을 바꿀 수 있나요?

공식 문서의 같은 페이지에는 버전별로 달라진 기능이 두 가지 적혀 있습니다. 문서에 표시된 상태는 이 글을 쓴 시점의 기준이므로, 사용 중인 클러스터 버전에서 지원되는지 반드시 확인하세요.

  • 재시작 지연 단축: Kubernetes v1.33부터 알파이며 기본값은 비활성화입니다. 피처 게이트 ReduceDefaultCrashLoopBackOffDecay를 켜면 지연이 1초에서 시작해 2배씩 늘어나고 최대 60초까지로 줄어듭니다.
  • 최대 지연 설정: Kubernetes v1.35부터 베타이며 기본 활성화입니다. 피처 게이트 KubeletCrashLoopBackOffMax를 쓰면 노드별 kubelet 설정으로 최대 지연을 기본 300초에서 바꿀 수 있습니다.

kubelet 설정의 crashLoopBackOff 항목에서 maxContainerRestartPeriod 필드를 "1s"에서 "300s" 사이로 지정합니다. 공식 문서에 실린 예시는 다음과 같습니다.

# 지연은 10초에서 시작해 2배씩 늘고, 최대 100초
kind: KubeletConfiguration
crashLoopBackOff:
  maxContainerRestartPeriod: "100s"

문서에 따르면 설정한 최대값이 기본 초기값 10초보다 작으면 초기 지연이 그 최대값으로 바뀝니다. 다만 이것은 재시작 간격을 조정할 뿐 크래시의 원인을 해결하지는 않습니다.

CrashLoopBackOff는 어떻게 진단하나요?

1단계: 파드 상태와 재시작 횟수 확인

kubectl get pods
kubectl describe pod ${POD_NAME}

공식 디버깅 문서는 파드 디버깅의 첫 단계로 kubectl describe pods를 실행해 현재 상태와 최근 이벤트를 보라고 안내합니다. 컨테이너가 모두 Running인지, 최근 재시작이 있었는지를 확인하라고 합니다. describe 출력에는 컨테이너 상태(Waiting, Running, Terminated 중 하나)와 재시작 횟수(Restart Count)가 포함되며, 재시작 횟수는 restartPolicy가 Always인 컨테이너의 크래시 루프를 찾는 데 유용하다고 문서에 설명돼 있습니다. 아래쪽 Events 항목의 Reason과 Message도 함께 보세요.

2단계: 직전에 죽은 컨테이너의 로그 확인

공식 문서는 먼저 문제 컨테이너의 로그를 보고, 컨테이너가 이전에 크래시했다면 이전 컨테이너의 크래시 로그를 --previous 옵션으로 볼 수 있다고 안내합니다.

kubectl logs ${POD_NAME} -c ${CONTAINER_NAME}
kubectl logs ${POD_NAME} -c ${CONTAINER_NAME} --previous

CrashLoopBackOff 상태에서는 현재 컨테이너가 막 재시작되어 로그가 비어 있는 경우가 많습니다. 이때 --previous로 직전 실행의 로그를 보는 것이 핵심입니다. 컨테이너가 하나뿐이면 -c 옵션은 생략할 수 있다고 공식 문서에 적혀 있습니다.

3단계: 흔한 원인 후보 점검

아래는 크래시 루프에서 일반적으로 많이 점검하는 항목입니다. 원인은 애플리케이션과 환경마다 다르며, 위 로그와 이벤트로 어느 항목에 해당하는지 확인해야 합니다.

  • 애플리케이션이 시작 중 에러로 종료(설정값 누락, 필수 환경변수 없음, 연결 실패 등)
  • 컨테이너 command나 args가 잘못되어 프로세스가 곧바로 종료
  • 필요한 ConfigMap이나 Secret, 볼륨이 없거나 값이 틀림
  • liveness probe 설정이 너무 엄격해 정상 컨테이너가 반복해서 재시작
  • 메모리 한도 초과로 종료(describe 출력의 종료 이유와 이벤트로 확인)

주의할 점

  • kubectl logs만 보면 재시작 직후의 빈 로그를 보고 원인을 놓치기 쉽습니다. 항상 --previous를 함께 확인하세요.
  • 대기 시간이 최대 5분까지 늘어나므로, 원인을 고친 뒤에도 파드가 곧바로 다시 뜨지 않고 한동안 기다릴 수 있습니다. 급하면 파드를 삭제해 새로 만들 수 있습니다.
  • 피처 게이트나 kubelet 설정으로 재시작 간격을 줄이면 크래시 루프가 더 자주 반복되어 노드에 부하를 줄 수 있습니다. 원인 해결이 먼저입니다.
  • 이 글은 공식 문서를 근거로 정리한 것이며 특정 클러스터에서 직접 실행해 확인한 결과가 아닙니다.

정리표

확인할 것명령 또는 설정알 수 있는 것
파드 상태와 재시작 횟수kubectl describe pod컨테이너 상태, Restart Count, Events
직전 크래시 로그kubectl logs --previous종료 직전 에러 메시지
재시작 간격(기본)10초부터 2배, 최대 300초대기 시간의 상한
최대 간격 조정kubelet의 maxContainerRestartPeriod노드별 상한(1초~300초)

자주 묻는 질문(FAQ)

CrashLoopBackOff는 에러인가요?

에러 자체가 아니라 컨테이너가 반복해서 실패하고 있어 재시작 대기 중이라는 상태입니다. 실제 원인은 컨테이너 로그와 파드 이벤트에서 찾아야 합니다.

CrashLoopBackOff일 때 로그가 비어 있는데 어떻게 하나요?

현재 컨테이너가 막 재시작된 상태일 수 있습니다. kubectl logs에 --previous 옵션을 붙여 직전에 크래시한 컨테이너의 로그를 확인하세요.

재시작 대기 시간은 최대 얼마까지 늘어나나요?

공식 문서 기준 기본값은 10초에서 시작해 2배씩 늘어 최대 300초(5분)입니다. 컨테이너가 10분 동안 문제없이 실행되면 타이머가 초기화됩니다. 최신 버전에서는 kubelet 설정으로 상한을 바꿀 수 있습니다.

restartPolicy를 바꾸면 해결되나요?

restartPolicy는 종료된 컨테이너를 다시 시작할지를 정하는 값이며 크래시의 원인을 고치지는 않습니다. 원인을 해결하지 않고 정책만 바꾸면 증상이 가려질 수 있습니다.

참고 문서: Kubernetes - Pod Lifecycle · Debug Running Pods · Debug Pods

최종 업데이트: 2026-10-26 · 작성: 내멋스레 사는 이야기

Kubernetes ImagePullBackOff 에러 해결법

🔍 검색 키워드: k8s ImagePullBackOff, 쿠버네티스 이미지 풀 실패, Docker 레지스트리 인증, 이미지 태그 오류, Pod 시작 실패

Kubernetes ImagePullBackOff 에러 해결법

증상

Kubernetes Pod를 배포했을 때 다음과 같은 상태에서 멈춘다:

$ kubectl get pods -n production
  NAME                    READY   STATUS             RESTARTS   AGE
  app-deployment-abc123   0/1     ImagePullBackOff   2          5m

상세 확인 시:

$ kubectl describe pod app-deployment-abc123 -n production
  Events:
    Type     Reason                 Age   Message
      ----     ------                 ----  -------
        Normal   Scheduled              5m    Successfully assigned production/app-deployment-abc123 to worker-node-1
          Normal   BackOff                4m    Back-off pulling image "myrepo/app:v1.0"
            Warning  Failed                 4m    Failed to pull image "myrepo/app:v1.0": rpc error: code = Unknown desc = Error response from daemon: unauthorized
              Warning  Failed                 3m    Back-off pulling image

또는 다음과 같은 메시지:

image not found
  image pull rate limit exceeded
  no such image
  invalid reference format

원인

  1. 이미지명 오류: 잘못된 저장소명, 태그 또는 레지스트리 주소
  2. 인증 실패: Private Docker 레지스트리 접근 권한 없음
  3. 네트워크 단절: 워커 노드에서 레지스트리 접근 불가
  4. 레지스트리 다운: Docker Hub, ECR 등 서비스 장애
  5. 이미지 미존재: 푸시되지 않은 이미지 태그
  6. 레이트 제한: Docker Hub 무료 계정 풀 한도 초과
  7. CPU/메모리 부족: 노드 리소스 부족으로 스케줄링 실패

해결 방법

방법 1: 이미지명 및 태그 확인

# 현재 Pod의 이미지 정보 확인
  kubectl get pod app-deployment-abc123 -n production -o yaml | grep image
  
  # 정확한 이미지명 확인 (레지스트리 포함)
  # 형식: [registry]/[repository]/[image]:[tag]
  # 정상 예: docker.io/myrepo/app:v1.0
  # 정상 예: gcr.io/my-project/app:latest
  # 정상 예: ecr.amazonaws.com/123456789.dkr.ecr.us-east-1.amazonaws.com/app:v1.0

Deployment 수정:

apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: app-deployment
      namespace: production
      spec:
        replicas: 3
          selector:
              matchLabels:
                    app: app
                      template:
                          metadata:
                                labels:
                                        app: app
                                            spec:
                                                  containers:
                                                        - name: app
                                                                image: docker.io/myrepo/app:v1.0  # 정확한 이미지명
                                                                        imagePullPolicy: IfNotPresent      # 또는 Always

방법 2: Private 레지스트리 인증 설정

# 1. Docker 자격증명으로 Secret 생성
  kubectl create secret docker-registry regcred \
    --docker-server=gcr.io \
      --docker-username=_json_key \
        --docker-password="$(cat ~/gcr-key.json)" \
          --docker-email=user@example.com \
            -n production
            
            # 2. 또는 기존 docker config 파일 사용
            kubectl create secret generic regcred \
              --from-file=.dockerconfigjson=$HOME/.docker/config.json \
                --type=kubernetes.io/dockercfg \
                  -n production

Deployment에서 사용:

apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: app-deployment
    spec:
      template:
          spec:
                imagePullSecrets:
                      - name: regcred  # 위에서 생성한 Secret 이름
                            containers:
                                  - name: app
                                          image: gcr.io/my-project/app:v1.0

방법 3: 워커 노드 네트워크 확인

# 워커 노드에서 직접 레지스트리 연결 확인
  kubectl debug node/worker-node-1 -it --image=ubuntu
  # Pod 내에서:
  apt-get update && apt-get install -y curl
  curl -I https://gcr.io
  curl -I https://docker.io
  
  # 또는 임시 Pod에서 테스트
  kubectl run test-curl --image=curlimages/curl -it --rm -- \
    curl -v https://gcr.io

방법 4: 로컬에서 이미지 빌드 및 푸시 확인

# 1. 로컬에서 이미지 빌드
  docker build -t myrepo/app:v1.0 .
  
  # 2. 레지스트리에 푸시
  docker push myrepo/app:v1.0
  
  # 3. 푸시된 이미지 확인
  # Docker Hub: https://hub.docker.com/r/myrepo/app
  # GCR: gcloud container images list
  # ECR: aws ecr describe-images --repository-name app
  
  # 4. 로컬에서 이미지 실행 가능 확인
  docker run --rm myrepo/app:v1.0 --version

방법 5: imagePullPolicy 조정

apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: app-deployment
    spec:
      template:
          spec:
                containers:
                      - name: app
                              image: myrepo/app:v1.0
                                      # imagePullPolicy 옵션:
                                              # Always: 매번 레지스트리에서 풀 (기본, 태그 latest 사용 시)
                                                      # IfNotPresent: 로컬에 없을 때만 풀
                                                              # Never: 로컬에서만 사용 (오프라인 환경)
                                                                      imagePullPolicy: Always

방법 6: 디버깅 및 재시도

# Pod 상세 로그 확인
  kubectl logs app-deployment-abc123 -n production --previous
  
  # 이벤트 확인 (시간 역순)
  kubectl get events -n production --sort-by='.lastTimestamp'
  
  # Pod 재생성 (자동 재시도)
  kubectl rollout restart deployment/app-deployment -n production
  
  # 캐시 클리어 후 재배포
  kubectl set image deployment/app-deployment \
    app=myrepo/app:v1.1 \
      -n production
      
      # 또는 현재 이미지로 강제 롤아웃
      kubectl rollout restart deployment/app-deployment -n production

정리표

원인 증상 해결법
이미지명 오류 image not found 정확한 이미지명 확인
인증 실패 unauthorized imagePullSecrets 설정
네트워크 단절 connection timeout 워커 노드 네트워크 확인
레지스트리 장애 service unavailable 레지스트리 상태 확인
태그 미존재 manifest not found docker push 재실행
레이트 제한 rate limit exceeded 인증된 계정으로 전환
노드 리소스 부족 OutOfmemory, OutOfDisk 노드 리소스 확인

팁: 배포 전에 로컬 환경에서 docker push까지 성공하는지 확인하고, 클러스터에는 imagePullPolicy: Always 설정으로 항상 최신 이미지를 가져오도록 설정하면 버전 관리가 쉬워집니다.

화요일

k8s OOMKilled 에러 진단 및 해결 완벽 가이드

<div style="font-family:'Noto Sans KR',sans-serif;line-height:1.8;max-width:860px;margin:0 auto">

<p style="color:#666;font-size:14px">🔍 검색 키워드: k8s OOMKilled, Kubernetes 메모리 부족, 파드 종료, 메모리 리소스 설정, 컨테이너 메모리 누수</p>

<h2>k8s OOMKilled 에러 진단 및 해결</h2>

<p>Kubernetes에서 파드가 갑자기 종료되고 재시작되는 문제는 보통 메모리 부족 때문입니다.</p>

<h3>1. 증상: 파드가 자꾸 크래시된다</h3>

<pre style="background:#1e1e1e;color:#d4d4d4;padding:16px;border-radius:6px;overflow-x:auto"><code>$ kubectl get pods

NAME              READY   STATUS    RESTARTS   AGE

my-app-abc123     0/1     CrashLoopBackOff    5      2m

Last State:  Terminated (reason:OOMKilled, exit code:137)</code></pre>

<p>exit code 137은 Linux에서 SIGKILL(9) 신호를 받았다는 뜻입니다.</p>

<h3>2. 원인</h3>

<ul>

<li>메모리 limit이 너무 낮게 설정됨</li>

<li>애플리케이션의 메모리 누수</li>

<li>노드의 물리 메모리 부족</li>

</ul>

<h3>3. 해결 방법</h3>

<h4>방법 1: 메모리 limit 증가</h4>

<pre style="background:#1e1e1e;color:#d4d4d4;padding:16px;border-radius:6px;overflow-x:auto"><code>resources:

  limits:

    memory: 512Mi

  requests:

    memory: 256Mi</code></pre>

<h4>방법 2: HPA로 자동 확장</h4>

<pre style="background:#1e1e1e;color:#d4d4d4;padding:16px;border-radius:6px;overflow-x:auto"><code>apiVersion: autoscaling/v2

kind: HorizontalPodAutoscaler

metadata:

  name: my-app-hpa

spec:

  minReplicas: 2

  maxReplicas: 10

  metrics:

  - type: Resource

    resource:

      name: memory

      target:

        type: Utilization

        averageUtilization: 70</code></pre>

<h3>정리표</h3>

<table border="1" cellpadding="10" cellspacing="0" style="width:100%;border-collapse:collapse">

<tr style="background:#f5f5f5"><th style="text-align:left">확인 항목</th><th style="text-align:left">명령어</th><th style="text-align:left">의미</th></tr>

<tr><td>파드 상태</td><td>kubectl describe pod</td><td>OOMKilled 여부</td></tr>

<tr><td>실제 메모리 사용</td><td>kubectl top pod</td><td>현재 사용량</td></tr>

<tr><td>노드 여유</td><td>kubectl top node</td><td>전체 노드 메모리 상태</td></tr>

</table>

<hr>

<p><strong>팁</strong>: requests는 평상시 사용량의 70~80%, limits는 requests의 1.5~2배로 설정하는 것이 best practice입니다.</p>

</div>

금요일

Kubernetes OOMKilled 에러 완벽 해결 가이드

🔍 검색 키워드: k8s OOMKilled, 쿠버네티스 메모리 부족, 포드 강제 종료, 메모리 리소스 요청, 리미트 설정

Kubernetes OOMKilled 에러 완벽 해결 가이드

1. 증상: OOMKilled 에러 메시지

Pod이 갑자기 재시작되고 로그에 다음과 같이 나타난다:

$ kubectl describe pod my-app-5f8d4c9d7b-xyz12
...
Last State:     Terminated
  Reason:       OOMKilled
  Exit Code:    137
  Killed:       True
Events:
  Type    Reason     Age   Message
  ----    ------     ---   -------
  Normal  Created    2m    Created container app
  Normal  Started    2m    Started container app
  Normal  Killing    1m    Killing container app (killed due to memory limit exceeded)

Pod의 상태가 계속 Pending이거나 CrashLoopBackOff 상태에 빠진다. 다른 Pod들은 정상인데 특정 Pod만 반복적으로 재시작된다.

2. 원인 분석

메모리 리미트 설정 부족

애플리케이션이 사용하는 실제 메모리가 Pod에 할당된 메모리 한계를 초과했다. kubelet이 OOM(Out of Memory) 상태를 감지하면 강제로 Pod을 kill한다.

메모리 누수

애플리케이션 코드에 메모리 누수가 있어서 시간이 지날수록 메모리 사용량이 증가한다. Node의 물리적 메모리도 한계가 있어 OOMKilled 발생.

Node 자원 부족

Node 레벨의 메모리가 부족하면 kubelet은 eviction policy에 따라 Pod들을 순차적으로 종료한다.

사이드카 컨테이너

logging agent, service mesh proxy(Istio sidecar) 등 추가 컨테이너들의 메모리 누적.

3. 해결방법

방법 1: Memory Request/Limit 올바르게 설정

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  containers:
  - name: app
    image: my-app:latest
    resources:
      requests:
        memory: "256Mi"    # Pod 스케줄링 시 보장받는 메모리
      limits:
        memory: "512Mi"    # 절대 초과 불가능한 한계
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 30
      periodSeconds: 10

requests: Scheduler가 Node 할당 결정 시 사용
limits: cgroup을 통해 강제로 제한

방법 2: 메모리 사용량 모니터링

# Pod의 실제 메모리 사용량 확인
$ kubectl top pod my-app-5f8d4c9d7b-xyz12 -n default

NAME                     CPU(cores)   MEMORY(bytes)
my-app-5f8d4c9d7b-xyz12  150m         387Mi

# Node 전체 메모리 상태
$ kubectl top nodes
NAME          CPU(cores)   CPU%   MEMORY(bytes)   MEMORY%
worker-node1  1200m        60%    5432Mi          68%

Prometheus + Grafana로 시간대별 메모리 추이를 분석. 대부분 정상이지만 특정 시간에 메모리 스파이크 발생하는지 확인.

방법 3: 메모리 누수 디버깅 (Node.js 예시)

// Node.js 힙 덤프 수집
const heapdump = require('heapdump');

app.get('/heapdump', (req, res) => {
  const fileName = `/tmp/heapdump-${Date.now()}.heapsnapshot`;
  heapdump.writeSnapshot(fileName, (err, filename) => {
    if (err) return res.status(500).send(err);
    res.send(`Heap dump written to ${filename}`);
  });
});

// Kubernetes manifest에 보안 컨텍스트 추가
securityContext:
  readOnlyRootFilesystem: true
  runAsNonRoot: true
  allowPrivilegeEscalation: false
volumeMounts:
- name: tmp
  mountPath: /tmp
volumes:
- name: tmp
  emptyDir: {}

방법 4: HPA(Horizontal Pod Autoscaler) 설정

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: my-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 70

메모리 사용율이 70% 도달하면 자동으로 Pod 개수 증가.

4. 정리표

구분 내용 해결도
증상 Pod이 OOMKilled로 반복 재시작됨 -
원인 1 메모리 limit 설정 부족 ✓ 높음
원인 2 애플리케이션 메모리 누수 ✓ 중간
원인 3 Node 자원 전체 부족 ✓ 중간
원인 4 사이드카 컨테이너 누적 ✓ 낮음
해결 1 Request/Limit 재설정 즉시 효과
해결 2 메모리 모니터링 (top, Prometheus) 원인 파악 필수
해결 3 메모리 누수 디버깅 근본 해결
해결 4 HPA 자동 스케일링 장기 대책

핵심: k8s OOMKilled는 "메모리가 부족하다"는 신호. requests는 넉넉하게, limits는 필요한 만큼만 설정하고, 정기적으로 메모리 프로파일링을 해야 한다.

🔍 검색 키워드: Docker 멀티스테이지 빌드, Docker 캐시 최적화, Dockerfile 성능, Docker 이미지 크기, Docker BuildKit, 컨테이너 최적화

Docker 멀티스테이지 빌드와 캐시 전략으로 빌드 시간 70% 단축

Docker 이미지 빌드는 CI/CD 파이프라인에서 가장 시간이 오래 걸리는 단계입니다. 잘못된 Dockerfile 구조는 매번 모든 의존성을 다시 다운로드하고, 컴파일하며, 불필요한 파일까지 포함시킵니다.

문제 증상

$ docker build -t myapp:latest .
Step 4/15 : RUN npm ci
 ---> cde345cde678 (cache miss) 120.5s
Total: 245.8s  ← 너무 오래 걸림!

# 이미지 크기: 980MB

원인 분석

원인 1: 레이어 캐싱을 무시하는 구조

FROM node:18
COPY . .
RUN npm ci
RUN npm run build

원인 2: 불필요한 파일을 최종 이미지에 포함

# 최종 이미지: node_modules (650MB) + 소스코드 + dist = 900MB

해결 방법

해결책 1: 레이어 순서 최적화

FROM node:18
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
CMD ["node", "dist/index.js"]

해결책 2: 멀티스테이지 빌드

FROM node:18 AS builder
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:18-alpine
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

성능 개선 결과

방식빌드 시간이미지 크기
기본 방식245초980MB
멀티스테이지15초180MB

이 전략을 적용하면 빌드 시간을 93% 단축할 수 있습니다.

수요일

Docker Compose healthcheck 에러 해결 — depends_on이 기다려주지 않는 이유

🔍 검색 키워드: Docker Compose depends_on 안 기다림, depends_on service_healthy, Docker Compose healthcheck 설정, 컨테이너 시작 순서 DB 연결 실패, docker compose condition service_healthy, Connection refused 컨테이너 기동 순서

요약: Docker Compose의 depends_on은 기본적으로 컨테이너가 "시작"되는 순서만 보장하고, 안의 서비스가 "준비"될 때까지는 기다리지 않습니다. 의존 대상에 healthcheck를 정의하고 depends_on에 condition: service_healthy를 지정하면 healthy 상태가 된 뒤에 다음 컨테이너가 시작됩니다.

depends_on을 썼는데 왜 DB 연결이 실패하나요?

앱 컨테이너가 시작 직후 DB에 접속하다가 Connection refused 또는 "could not connect to server" 같은 에러로 죽는 경우가 많습니다. depends_on: [db]만 쓰면 Compose는 db 컨테이너를 먼저 "시작(start)"할 뿐, db 프로세스가 포트를 열 때까지 기다리지 않기 때문입니다. 공식 문서도 짧은 형식의 depends_on은 서비스가 준비될 때까지 기다리지 않는다고 설명합니다.

직접 재현해 본 결과

이 글의 출력은 아래 환경에서 직접 실행한 결과입니다. 실제 DB 이미지를 새로 내려받지 않고, "시작 후 8초 뒤에 5432 포트를 여는 서버"(Java ServerSocket)로 늦게 준비되는 DB를 흉내 냈습니다. PostgreSQL이나 MySQL로 재현한 것은 아니며, 기동 순서의 동작 원리를 확인하는 용도입니다.

  • 환경: macOS 27.0.1, Docker 29.7.2, Docker Compose v5.4.0
  • 이미지: eclipse-temurin:8-jdk (openjdk 1.8.0_502)

1) depends_on만 쓴 경우 (실패)

services:
  db:
    image: eclipse-temurin:8-jdk
    working_dir: /w
    volumes: ["./:/w"]
    entrypoint: ["sh","-c","javac Server.java && java Server"]  # 8초 뒤 5432 오픈
  app:
    image: eclipse-temurin:8-jdk
    depends_on: [db]
    entrypoint: ["bash","-c","date +%T; if (echo > /dev/tcp/db/5432) 2>/dev/null; then echo 'app: connected to db'; else echo 'app: connection to db FAILED'; fi"]
$ docker compose -p hcbad up --abort-on-container-exit
app-1  | 03:06:36
app-1  | app: connection to db FAILED
app-1 exited with code 0

db 컨테이너는 시작됐지만 포트가 아직 열리지 않았으므로 app의 접속이 실패했습니다.

2) healthcheck + condition: service_healthy (성공)

services:
  db:
    image: eclipse-temurin:8-jdk
    working_dir: /w
    volumes: ["./:/w"]
    entrypoint: ["sh","-c","javac Server.java && java Server"]
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/localhost/5432'"]
      interval: 2s
      timeout: 2s
      retries: 10
  app:
    image: eclipse-temurin:8-jdk
    depends_on:
      db:
        condition: service_healthy
    entrypoint: [...]  # 위와 동일
$ docker compose -p hcgood up --abort-on-container-exit
 Container hcgood-db-1 Healthy
 Container hcgood-app-1 Starting
app-1  | 03:06:55
app-1  | app: connected to db

db가 Healthy가 된 것을 확인한 뒤에야 app이 Starting 상태로 넘어갔고, 접속에 성공했습니다. (위 두 출력의 시각은 서로 다른 실행의 값이라 비교 대상이 아닙니다.)

3) healthcheck 없이 service_healthy를 쓴 경우 (에러)

의존 대상에 healthcheck가 없으면 up 실행 시점에 아래 에러로 중단됩니다. 직접 실행해 확인한 메시지입니다.

Container hcno-db-1 Error dependency db failed to start
dependency failed to start: container hcno-db-1 has no healthcheck configured

실제 DB에는 어떤 healthcheck를 쓰나요?

위 재현은 TCP 포트 확인이었고, 실제 서비스에서는 해당 DB의 전용 명령으로 준비 상태를 확인하는 것이 일반적입니다. 아래는 많이 쓰는 형태의 예시이며, 이 글에서 직접 실행해 확인한 것은 아닙니다. 이미지와 계정 값은 환경에 맞게 바꾸세요.

# PostgreSQL 예시
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres"]
  interval: 5s
  timeout: 3s
  retries: 10

# MySQL 예시
healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
  interval: 5s
  timeout: 3s
  retries: 10

healthcheck 옵션은 어떻게 정하나요?

  • interval: 검사 주기. 너무 길면 시작이 늦어지고, 너무 짧으면 부하가 늘어납니다.
  • timeout: 한 번의 검사가 이 시간을 넘으면 실패로 처리합니다.
  • retries: 연속 실패가 이 횟수를 넘으면 unhealthy가 됩니다. DB가 늦게 뜨는 환경이면 넉넉히 두세요.
  • start_period: 초기 기동 시간 동안은 실패를 세지 않는 유예 시간입니다. 기동이 오래 걸리는 서비스에 유용합니다.

주의할 점

  • service_healthy 조건은 시작 시점의 순서만 다룹니다. 이후 DB가 재시작되거나 일시적으로 끊기는 상황까지 막아 주지 않으므로, 앱 쪽에도 재시도(retry) 로직을 두는 편이 안전합니다.
  • 의존 대상에 healthcheck가 없으면 위 3)의 에러가 납니다. 반드시 healthcheck를 정의하세요.
  • healthcheck 명령은 컨테이너 안에서 실행되므로 그 안에 해당 명령(pg_isready 등)이 있어야 합니다.

정리표

설정보장하는 것결과(직접 재현)
depends_on: [db]db 컨테이너를 먼저 시작app 접속 실패
condition: service_healthy + healthcheckhealthy 상태가 된 뒤 시작app 접속 성공
condition: service_healthy, healthcheck 없음-no healthcheck configured 에러

자주 묻는 질문(FAQ)

depends_on만으로 DB가 준비될 때까지 기다리게 할 수 없나요?

없습니다. 짧은 형식의 depends_on은 시작 순서만 지정합니다. 준비 완료까지 기다리려면 의존 서비스에 healthcheck를 정의하고 condition: service_healthy를 사용하세요.

wait-for-it.sh 같은 스크립트가 아직 필요한가요?

Compose의 healthcheck와 service_healthy로 대부분 대체할 수 있습니다. 다만 Compose 밖에서 실행되는 앱이나 시작 이후 재연결까지 다뤄야 한다면 앱 자체의 재시도 로직이 더 근본적인 해결입니다.

healthcheck가 계속 unhealthy로 나오면 어떻게 확인하나요?

docker inspect로 컨테이너의 Health 로그를 확인하면 검사 명령의 출력과 종료 코드를 볼 수 있습니다. 명령이 컨테이너 안에 없거나 포트·계정이 틀린 경우가 흔한 원인입니다.

service_healthy를 썼는데도 가끔 접속이 실패합니다.

healthcheck가 "DB 프로세스 응답"만 확인하고 앱이 쓰는 계정·스키마까지 준비됐는지는 확인하지 못하는 경우입니다. 초기화 스크립트가 끝난 뒤에 healthy가 되도록 검사 명령을 조정하거나, 앱에 재시도를 추가하세요.

참고 문서: Docker Docs - Control startup and shutdown order in Compose · Compose file reference - depends_on

최종 업데이트: 2026-10-06 · 작성: 내멋스레 사는 이야기

금요일

Docker 포트 충돌 & 컨테이너 연결 에러 완전 정복

🔍 검색 키워드: Docker 포트 충돌, port is already allocated, docker: Error response from daemon, 컨테이너 연결 안됨, bind failed port already in use, docker ps -a, EADDRINUSE 도커

왜 이 에러가 자꾸 나오냐

도커를 쓰다 보면 십중팔구 이 두 가지를 겪는다.

  1. 컨테이너 띄우려는데 포트가 이미 점유됐다고 막힘
  2. 컨테이너는 실행 중인데 앱끼리 통신이 안 됨

둘 다 "왜?"를 이해하면 해결은 5분이다. 모르고 --force나 재시작만 반복하면 하루 날린다.


1. 포트 충돌 에러

에러 메시지 패턴

Error response from daemon: driver failed programming external connectivity on endpoint myapp
(xxx): Bind for 0.0.0.0:8080 failed: port is already allocated
Error starting userland proxy: listen tcp4 0.0.0.0:3306: bind: address already in use

원인 3가지

원인빈도설명
이전 컨테이너가 죽지 않고 포트 점유 중★★★docker stop 안 하고 그냥 터미널 닫은 경우
호스트 프로세스(MySQL, Nginx 등)가 같은 포트 사용★★☆로컬에 MySQL 깔려있는데 3306 쓰려 할 때
이전 컨테이너가 exited 상태로 포트 홀딩★☆☆docker ps엔 안 보이지만 docker ps -a엔 보임

[초보] 단계별 해결법

1단계: 어떤 프로세스가 포트 쓰는지 확인

# macOS / Linux
lsof -i :8080

# Windows (PowerShell)
netstat -ano | findstr :8080

2단계: 도커 컨테이너 확인

# 실행 중인 컨테이너만
docker ps

# 중단된 것 포함 전체
docker ps -a

# 특정 포트 쓰는 컨테이너 찾기
docker ps --filter "publish=8080"

3단계: 점유 중인 컨테이너 정리

# 특정 컨테이너 중지
docker stop <container_id>

# 중지 + 삭제
docker rm -f <container_id>

# exited 상태 컨테이너 일괄 정리
docker container prune

[중급] 포트 매핑 전략

같은 포트를 써야 하는 서비스가 여러 개라면, 호스트 포트를 다르게 매핑한다.

# 호스트 8081 → 컨테이너 내부 8080
docker run -p 8081:8080 myapp

# 여러 포트 동시 매핑
docker run -p 8080:8080 -p 443:443 myapp

docker-compose.yml에서는:

services:
  app:
    image: myapp
    ports:
      - "8081:8080"  # 호스트:컨테이너
  db:
    image: mysql:8
    ports:
      - "3307:3306"  # 로컬 MySQL과 충돌 방지

[고급] 동적 포트 할당

테스트 환경에서 포트 충돌을 원천 차단하는 방법 — 호스트 포트를 도커가 알아서 비어있는 거 잡게 한다.

# 호스트 포트 미지정 → 임의 할당
docker run -p 0:8080 myapp

# 할당된 포트 확인
docker port <container_id> 8080
# 출력 예: 0.0.0.0:49152

Node.js에서 환경변수로 포트 받아 쓰는 패턴:

// app.js
const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

2. 컨테이너 간 통신 안 되는 에러

에러 메시지 패턴

Error: connect ECONNREFUSED 127.0.0.1:3306
getaddrinfo ENOTFOUND db

컨테이너 A에서 컨테이너 B의 localhost로 접속하려 해서 생기는 문제다. 컨테이너끼리 localhost는 공유하지 않는다. 각자 독립된 네트워크 네임스페이스를 가진다.

원인과 해결법 체크리스트

상황잘못된 접근올바른 접근
컨테이너 A → B 접속localhost:3306컨테이너명 또는 서비스명
docker run 단독 실행네트워크 미지정--network 플래그로 같은 네트워크 사용
docker-compose 사용별도 network 정의같은 compose 파일 내면 자동 연결

[초보] docker-compose로 컨테이너 연결

docker-compose를 쓰면 같은 파일 안의 서비스끼리는 서비스명으로 바로 통신된다. 네트워크 설정 따로 안 해도 된다.

# docker-compose.yml
services:
  app:
    image: node:20
    environment:
      DB_HOST: db        # "localhost" 아니고 서비스명 "db"
      DB_PORT: 3306
    depends_on:
      - db

  db:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: secret
      MYSQL_DATABASE: mydb

Node.js에서 DB 연결:

const mysql = require('mysql2/promise');

const pool = mysql.createPool({
  host: process.env.DB_HOST || 'db',  // 서비스명
  port: process.env.DB_PORT || 3306,
  user: 'root',
  password: 'secret',
  database: 'mydb'
});

Python (SQLAlchemy):

import os
from sqlalchemy import create_engine

DATABASE_URL = (
    f"mysql+pymysql://root:secret@"
    f"{os.getenv('DB_HOST', 'db')}:"
    f"{os.getenv('DB_PORT', '3306')}/mydb"
)

engine = create_engine(DATABASE_URL)

[중급] docker run으로 수동 네트워크 연결

docker-compose 없이 컨테이너 여러 개 연결할 때:

# 1. 공용 네트워크 생성
docker network create mynet

# 2. DB 컨테이너를 해당 네트워크에 붙여 실행
docker run -d \
  --name mydb \
  --network mynet \
  -e MYSQL_ROOT_PASSWORD=secret \
  mysql:8

# 3. 앱 컨테이너도 같은 네트워크로 실행
docker run -d \
  --name myapp \
  --network mynet \
  -e DB_HOST=mydb \
  -p 8080:8080 \
  myapp:latest

Java (Spring Boot) application.yml:

spring:
  datasource:
    url: jdbc:mysql://${DB_HOST:mydb}:${DB_PORT:3306}/mydb
    username: root
    password: secret

[고급] 네트워크 디버깅

# 컨테이너가 어떤 네트워크에 붙어있나
docker inspect myapp | grep -A 20 "Networks"

# 특정 네트워크에 연결된 컨테이너 목록
docker network inspect mynet

# 컨테이너 안에서 직접 핑 테스트
docker exec -it myapp ping mydb

# 컨테이너 안에서 포트 열려있나 확인
docker exec -it myapp nc -zv mydb 3306

# 임시 debug 컨테이너로 네트워크 진단
docker run --rm --network mynet nicolaka/netshoot nmap -p 3306 mydb

Nginx 설정에서 upstream을 컨테이너명으로:

# nginx.conf
upstream backend {
    server app:8080;  # 컨테이너/서비스명
}

server {
    listen 80;
    location / {
        proxy_pass http://backend;
    }
}

트러블슈팅 체크리스트

포트 충돌 발생 시

체크 항목명령어
실행 중인 컨테이너 확인docker ps
중단 포함 전체 확인docker ps -a
호스트 포트 점유 확인lsof -i :PORT (mac/linux)
문제 컨테이너 강제 삭제docker rm -f CONTAINER_ID
불필요한 컨테이너 일괄 정리docker container prune
포트 다르게 재매핑docker run -p HOST:CONTAINER

컨테이너 연결 안 될 때

체크 항목명령어
같은 네트워크인지 확인docker network inspect NETWORK
컨테이너명/서비스명으로 접속하는지 확인localhost → 서비스명
컨테이너 내부에서 핑 테스트docker exec -it APP ping DB
포트 열려있나 확인docker exec -it APP nc -zv DB PORT
컨테이너 로그 확인docker logs CONTAINER_ID
네트워크 재생성 후 재연결docker network create + --network

자주 하는 실수 요약

1. docker stop 대신 터미널만 닫는다
→ 컨테이너는 살아서 포트 계속 점유. docker stop 또는 docker-compose down 습관화.

2. 컨테이너 안에서 localhost로 다른 컨테이너 접근
→ 각 컨테이너는 독립 네트워크. 서비스명이나 컨테이너명으로 접근.

3. exited 컨테이너가 포트 잡고 있는 줄 모름
→ docker ps -a로 exited 포함해서 항상 확인.

4. depends_on만 믿고 DB 준비됐다고 착각
→ depends_on은 컨테이너 시작 순서만 보장. DB가 실제로 ready 상태인지는 별개. healthcheck나 wait 로직 필요.

# healthcheck로 DB 준비 확인
services:
  db:
    image: mysql:8
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      timeout: 10s
      retries: 5

  app:
    depends_on:
      db:
        condition: service_healthy  # DB healthy 확인 후 시작

도커 관련 에러는 대부분 이 두 가지에서 온다. 포트 충돌이면 docker ps -a부터, 연결 안 되면 네트워크와 호스트명부터 확인하면 길을 잃지 않는다.