DevOps 지식 허브
DevOps 지식 허브

쿠버네티스 파드 장애 문제 해결: 종합 가이드

이 종합 가이드로 쿠버네티스 파드 장애의 복잡성을 탐색해 보세요. CrashLoopBackOff, ImagePullBackOff, 리소스 고갈과 같은 일반적인 문제를 진단하는 체계적인 프로세스를 알아보세요. `kubectl describe` 및 `kubectl logs --previous`와 같은 중요한 도구를 활용하여 근본 원인을 파악하고, 컨테이너 종료 상태를 해석하며, 안정적인 애플리케이션 가동 시간 및 안정성을 유지하기 위한 실용적인 해결책을 구현하는 방법을 자세히 설명합니다.

32 조회수

Kubernetes Pod 장애 해결: 종합 가이드

Kubernetes Pod는 생태계에서 배포 가능한 가장 작은 단위이며, 애플리케이션을 구동하는 컨테이너를 실행합니다. Pod에 장애가 발생하면 서비스의 가용성 및 안정성에 직접적인 영향을 미칩니다. Pod 장애를 빠르고 정확하게 진단하는 것은 모든 Kubernetes 관리자나 개발자에게 필수적인 기술입니다.

이 가이드는 가장 일반적인 Pod 장애 시나리오를 진단하기 위한 구조화되고 단계적인 접근 방식을 제공합니다. 검사에 사용되는 필수 kubectl 명령을 다루고, 다양한 Pod 상태를 해석하며, 애플리케이션을 안정적인 실행 상태로 복원하기 위한 실행 가능한 솔루션을 설명합니다.

Pod 진단의 세 가지 핵심 요소

문제 해결은 장애가 발생한 Pod에 대한 사용 가능한 모든 정보를 수집하기 위해 세 가지 주요 kubectl 명령을 활용하는 것에서 시작됩니다.

1. 초기 상태 확인 (kubectl get pods)

첫 번째 단계는 항상 Pod 및 해당 컨테이너의 현재 상태를 확인하는 것입니다. STATUS(상태) 및 READY(준비) 열에 세심한 주의를 기울이십시오.

kubectl get pods -n my-namespace

Pod 상태 해석

상태 (Status) 의미 (Meaning) 초기 조치 (Initial Action)
Running Pod가 정상이며, 모든 컨테이너가 실행 중입니다. (준비성 프로브가 실패하지 않는 한 문제가 없을 가능성이 높음)
Pending Pod가 Kubernetes에 의해 승인되었지만 컨테이너가 아직 생성되지 않았습니다. 스케줄링 이벤트 또는 이미지 풀 상태를 확인하십시오.
CrashLoopBackOff 컨테이너가 시작되었다가 충돌하고, Kubelet이 반복적으로 다시 시작을 시도합니다. 애플리케이션 로그를 확인하십시오 (kubectl logs --previous).
ImagePullBackOff Kubelet이 필요한 컨테이너 이미지를 가져올 수 없습니다. 이미지 이름, 태그 및 레지스트리 자격 증명을 확인하십시오.
Error 런타임 오류 또는 실패한 시작 명령으로 인해 Pod가 종료되었습니다. 로그 및 describe 이벤트를 확인하십시오.
Terminating/Unknown Pod가 종료 중이거나 Kubelet 호스트가 응답하지 않습니다. 노드 상태를 확인하십시오.

2. 심층 검사 (kubectl describe pod)

상태가 Running이 아닌 경우, describe 명령어는 스케줄링 결정, 리소스 할당 및 컨테이너 상태를 자세히 설명하는 중요한 컨텍스트를 제공합니다.

kubectl describe pod [POD_NAME] -n my-namespace

출력에서 다음 섹션에 집중하십시오:

  • Containers/Init Containers (컨테이너/Init 컨테이너): State(상태, 특히 Waiting 또는 Terminated)와 Last State(마지막 상태, 실패 이유가 자주 기록되는 곳, 예: Reason: OOMKilled)를 확인하십시오.
  • Resource Limits (리소스 제한): Limits(제한) 및 Requests(요청)가 올바르게 설정되었는지 확인하십시오.
  • Events (이벤트): 이 섹션이 가장 중요합니다. 이벤트는 스케줄링 실패, 볼륨 마운트 문제, 이미지 풀 시도 등 라이프사이클 이력을 보여줍니다.

팁: Events 섹션에 "0/N nodes available"과 같은 메시지가 표시되면, Pod는 리소스 부족(CPU, 메모리) 또는 어피니티 규칙이 충족되지 않아 스케줄링이 실패하고 있을 가능성이 높습니다.

3. 로그 검토 (kubectl logs)

런타임 애플리케이션 문제의 경우, 로그는 프로세스가 종료된 이유를 설명하는 스택 추적 또는 오류 메시지를 제공합니다.

# 현재 컨테이너 로그 확인
kubectl logs [POD_NAME] -n my-namespace

# Pod 내 특정 컨테이너의 로그 확인
kubectl logs [POD_NAME] -c [CONTAINER_NAME] -n my-namespace

# CrashLoopBackOff에 중요: *이전* 실패 실행의 로그 확인
kubectl logs [POD_NAME] --previous -n my-namespace

일반적인 Pod 장애 시나리오 및 해결책

대부분의 Pod 장애는 몇 가지 식별 가능한 패턴으로 분류되며, 각 패턴에는 표적화된 진단 접근 방식이 필요합니다.

시나리오 1: CrashLoopBackOff

이는 가장 빈번하게 발생하는 Pod 장애입니다. 컨테이너가 성공적으로 시작되었지만, 컨테이너 내 애플리케이션이 즉시 종료됨(0이 아닌 종료 코드와 함께)을 나타냅니다.

진단:
1. kubectl logs --previous를 사용하여 추적(traceback) 또는 종료 이유를 확인합니다.
2. kubectl describe를 사용하여 Exit Code(종료 코드)를 Last State(마지막 상태) 섹션에서 확인합니다.

일반적인 원인 및 해결 방법:

  • 종료 코드 1/2: 일반적인 애플리케이션 오류, 누락된 구성 파일, 데이터베이스 연결 실패 또는 잘못된 입력으로 인한 애플리케이션 충돌.
    • 해결: 애플리케이션 코드를 디버깅하거나 마운트된 ConfigMaps/Secrets를 확인합니다.
  • 누락된 종속성: 진입점 스크립트에 존재하지 않는 파일이나 환경이 필요합니다.
    • 해결: Dockerfile 및 이미지 빌드 프로세스를 확인합니다.

시나리오 2: ImagePullBackOff / ErrImagePull

이는 Kubelet이 Pod 정의에 지정된 컨테이너 이미지를 가져올 수 없을 때 발생합니다.

진단:
1. kubectl describe의 Events(이벤트) 섹션에서 특정 오류 메시지(예: 404 Not Found 또는 authentication required)를 확인합니다.

일반적인 원인 및 해결 방법:

  • 오타 또는 잘못된 태그: 이미지 이름 또는 태그가 잘못되었습니다.
    • 해결: Deployment 또는 Pod 사양에서 이미지 이름을 수정합니다.
  • 프라이빗 레지스트리 접근: 클러스터에 프라이빗 레지스트리(예: Docker Hub, GCR, ECR)에서 이미지를 가져올 수 있는 자격 증명이 없습니다.
    • 해결: Pod 사양에 적절한 imagePullSecret가 참조되었는지, 그리고 해당 Secret이 네임스페이스에 존재하는지 확인하십시오.
# 풀 시크릿 사용을 위한 Pod 사양 예시 스니펫
spec:
  containers:
  ...
  imagePullSecrets:
  - name: my-registry-secret

시나리오 3: Pending 상태 (정체)

Pod가 Pending 상태로 유지되는 경우는 일반적으로 노드에 스케줄링될 수 없거나 (PersistentVolume과 같은) 리소스를 기다리고 있음을 나타냅니다.

진단:
1. kubectl describe를 실행하고 Events(이벤트) 섹션을 확인합니다.

일반적인 원인 및 해결 방법:

  • 리소스 소진: 클러스터에 Pod의 requests(요청)를 충족할 만큼 충분한 CPU 또는 메모리를 가진 노드가 부족합니다.
    • 해결: 클러스터 크기를 늘리거나 Pod 리소스 요청을 줄입니다 (가능한 경우).
    • 이벤트 메시지 예시: 0/4 nodes are available: 4 Insufficient cpu.
  • 볼륨 바인딩 문제: Pod가 기본 PersistentVolume (PV)에 바인딩될 수 없는 PersistentVolumeClaim (PVC)을 필요로 합니다.
    • 해결: PVC의 상태를 확인하고 (kubectl get pvc) StorageClass가 작동하는지 확인합니다.

시나리오 4: OOMKilled (메모리 부족으로 종료됨)

이것이 일반적으로 CrashLoopBackOff 상태를 초래하지만, 근본적인 원인은 컨테이너가 사양에 정의된 제한보다 더 많은 메모리를 사용하여 호스트 운영 체제(Kubelet을 통해)가 컨테이너를 강제로 종료시켰다는 점에서 구체적입니다.

진단:
1. kubectl describe -> Last State(마지막 상태) -> Reason: OOMKilled를 확인합니다.

해결 방법:

  1. 제한 증가: Pod 사양에서 메모리 limit을 늘려 더 많은 여유 공간을 제공합니다.
  2. 애플리케이션 최적화: 애플리케이션의 메모리 사용량을 줄이기 위해 프로파일링합니다.
  3. 요청 설정: 스케줄링 안정성을 개선하기 위해 requests가 실제 안정 상태 사용량에 가깝게 설정되었는지 확인합니다.
resources:
  limits:
    memory: "512Mi" # 이 값을 증가시키십시오
  requests:
    memory: "256Mi"

향후 장애 방지: 모범 사례

견고한 애플리케이션은 일반적인 배포 함정을 방지하기 위해 신중한 구성이 필요합니다.

Liveness 및 Readiness 프로브 사용

프로브를 올바르게 구현하면 Kubernetes가 컨테이너 상태를 지능적으로 관리할 수 있습니다.

  • Liveness Probes (활성 프로브): 컨테이너가 계속 실행될 만큼 충분히 정상적인지 판단합니다. 활성 프로브가 실패하면 Kubelet이 컨테이너를 다시 시작합니다 (소프트 잠금 해결).
  • Readiness Probes (준비 프로브): 컨테이너가 트래픽을 처리할 준비가 되었는지 판단합니다. 준비 프로브가 실패하면 Pod는 서비스 엔드포인트에서 제거되어 컨테이너가 복구되는 동안 실패한 요청을 방지합니다.

리소스 제한 및 요청 강제화

컨테이너에 대한 리소스 요구 사항을 항상 정의하십시오. 이는 Pod가 과도한 리소스를 소비하는 것을 방지하고(노드 불안정으로 이어짐) 스케줄러가 충분한 용량을 가진 노드에 Pod를 배치할 수 있도록 보장합니다.

설정을 위한 Init 컨테이너 활용

메인 애플리케이션이 시작되기 전에 Pod에 종속성 확인 또는 데이터 설정이 필요한 경우 (예: 데이터베이스 마이그레이션 완료 대기), Init Container를 사용하십시오. Init Container가 실패하면 Pod는 이를 반복적으로 다시 시작하여, 설정 오류를 애플리케이션 런타임 오류로부터 깔끔하게 분리합니다.

결론

Kubernetes Pod 문제 해결 마스터는 kubectl get, kubectl describe, kubectl logs의 출력에 크게 의존하는 체계적인 접근 방식에 달려 있습니다. Pod 상태를 체계적으로 분석하고, 이벤트 이력을 읽고, 일반적인 종료 코드를 이해함으로써 CrashLoopBackOff, ImagePullBackOff 및 리소스 관련 장애를 신속하게 진단하고 해결하여 일관된 애플리케이션 가동 시간을 보장할 수 있습니다.