DevOps 지식 허브
DevOps 지식 허브

배포 실패 디버깅: 일반적인 YAML 및 구성 오류 식별

Pending 또는 오류 상태에 멈춘 Kubernetes 배포의 문제 해결을 마스터하세요. 이 실용 가이드에서는 `kubectl describe` 이벤트를 해석하고, 일반적인 YAML 구문 오류를 진단하며, 이미지 풀(pull) 문제를 해결하고, 성공적인 컨테이너 오케스트레이션을 방해하는 리소스 할당 및 어피니티(affinity) 규칙 오구성을 수정하는 방법을 자세히 설명합니다.

31 조회수

배포 실패 디버깅: 일반적인 YAML 및 구성 오류 식별

Kubernetes에 애플리케이션을 배포하는 작업은 YAML 매니페스트를 통해 관리되는 선언적 구성으로 간소화되는 경우가 많습니다. 그러나 배포가 원하는 상태에 도달하지 못하고 Pending, ImagePullBackOff 상태에 멈추거나 갑자기 실패하는 경우, 근본 원인은 이러한 구성 파일이나 기본 클러스터 리소스 내의 미묘한 오류인 경우가 많습니다. 이 가이드는 Kubernetes 배포를 괴롭히는 일반적인 YAML 및 구성 함정을 진단하고 해결하기 위한 체계적인 접근 방식을 제공합니다.

Kubernetes 이벤트를 해석하고 리소스 상태를 검사하는 방법을 이해하는 것은 효율적인 디버깅에 중요합니다. 이 문서에서는 구문 오류, 리소스 제약 조건 및 네트워킹 구성 문제에 중점을 두어 실패한 배포를 신속하게 정상 작동 상태로 전환하는 데 필요한 필수 명령과 확인 사항을 안내합니다.

첫 번째 단계: 배포 상태 및 이벤트 확인

배포가 실패하면 첫 번째 진단 단계는 항상 기본 리소스 자체와 관리되는 ReplicaSet 및 Pod와 관련된 이벤트를 확인하는 것이어야 합니다. 이는 Kubernetes가 무엇을 시도하고 있고 왜 실패하는지에 대한 최상위 수준의 보기를 제공합니다.

1. 배포 상태 검사

kubectl get deployments를 사용하여 전반적인 상태를 확인합니다. 특히 READY, UP-TO-DATE, AVAILABLE 열을 살펴보십시오. 여기에 불일치가 있으면 기본 Pod에 문제가 있음을 나타냅니다.

kubectl get deployments <deployment-name>

배포 상태에 준비된 레플리카가 거의 없거나 0개로 표시되면 ReplicaSet을 확인하십시오.

2. ReplicaSet 및 Pod 이벤트 검토

ReplicaSet은 원하는 수의 Pod를 관리합니다. 배포가 실패하면 ReplicaSet이 일반적으로 오류 연쇄의 원인이 됩니다. 일반적으로 <deployment-name>-<hash> 이름으로 지정된 ReplicaSet에 대해 describe 명령을 사용하십시오.

kubectl describe rs <replicaset-name>

중요한 것은 출력 하단의 Events 섹션을 검토하는 것입니다. 이 섹션은 스케줄링 시도, 이미지 풀 실패 및 볼륨 마운트 문제를 포함한 최근 작업을 자세히 설명합니다. 이러한 이벤트는 종종 결정적인 단서가 됩니다.

마지막으로 Pod 자체를 확인하십시오. Pod가 즉각적인 실패를 보고하기 때문입니다.

kubectl get pods -l app=<your-app-label>
kubectl describe pod <pod-name>

Pod 설명에서 State 및 Reason 필드를 찾으십시오. 일반적인 원인에는 ImagePullBackOff, ErrImagePull, CrashLoopBackOff, Pending이 있습니다.

YAML 매니페스트의 일반적인 구성 오류

YAML 파일의 잘못된 구성은 배포 실패의 가장 빈번한 원인입니다. 이러한 오류는 간단한 들여쓰기 실수부터 복잡한 구조적 문제에 이르기까지 다양할 수 있습니다.

1. YAML 구문 및 구조 오류

Kubernetes API는 올바른 YAML 구문(들여쓰기, 간격 및 데이터 유형)에 매우 민감합니다. YAML이 유효하지 않으면 kubectl apply가 파일을 구문 분석할 수 없다고 즉시 실패하는 경우가 많습니다.

모범 사례: 린터 사용
항상 적용하기 전에 YAML 구문을 유효성 검사하십시오. yamllint와 같은 도구 또는 통합 IDE 지원은 즉시 기본적인 구문 오류를 감지할 수 있습니다.

일반적인 구조적 오류의 예: 잘못된 매핑 또는 들여쓰기.

# 컨테이너 포트의 잘못된 들여쓰기
containers:
  - name: my-app
    image: myregistry/myapp:v1
    ports:
    - containerPort: 8080  # 목록 항목 '-' 아래에 들여쓰기 되어야 합니다.

2. 이미지 참조 및 풀 오류

Pod가 ImagePullBackOff 또는 ErrImagePull 상태로 들어가면, 문제는 컨테이너 이미지 접근과 관련이 있습니다.

  • 이미지 이름/태그 오타: 이미지 저장소, 이름 및 태그의 철자를 다시 확인하십시오.
  • 프라이빗 레지스트리 인증: 프라이빗 레지스트리(예: Docker Hub 프라이빗 리포 또는 ECR/GCR)에서 풀링하는 경우, Pod 스펙에 ImagePullSecret을 올바르게 구성하고 참조했는지 확인하십시오.
# ImagePullSecret 사용법을 보여주는 스니펫
spec:
  imagePullSecrets:
  - name: my-registry-secret
  containers:
  # ... 나머지 컨테이너 스펙

3. 리소스 요청 및 제한 위반

Pod가 Pending 상태로 유지되고 이벤트에 리소스 부족이 언급되면, 클러스터 노드가 YAML에 정의된 CPU 또는 메모리 요구 사항을 충족할 수 없는 것입니다.

배포 매니페스트에 지정된 제한을 확인하십시오.

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

문제 해결 단계:
1. kubectl describe nodes를 사용하여 사용 가능한 용량을 확인합니다.
2. 0/3 nodes are available: 3 Insufficient cpu와 같은 이벤트가 보이면 YAML의 requests를 낮추거나 클러스터에 노드를 더 추가해야 합니다.

고급 구성 문제

기본적인 구문 및 이미지 풀 외에도 네트워킹, 스토리지 및 스케줄링과 관련된 복잡한 구성은 진단하기 어려운 실패로 이어질 수 있습니다.

1. 잘못 구성된 프로브(활성 및 준비)

Pod가 CrashLoopBackOff로 전환되면 컨테이너가 시작되지만 즉시 검사에 실패하거나, 시작되지만 준비 프로브에 반복적으로 실패함을 의미하는 경우가 많습니다.

  • 활성 프로브 (Liveness Probes): 이 프로브가 실패하면 Kubernetes는 컨테이너를 다시 시작합니다. 애플리케이션 로그(kubectl logs <pod-name>)를 확인하여 충돌 원인을 파악하십시오.
  • 준비 프로브 (Readiness Probes): 이 프로브가 실패하면 Pod는 Service 엔드포인트에서 제외됩니다. 경로, 포트 및 예상 응답 코드가 애플리케이션이 실제로 제공하는 것과 일치하는지 확인하십시오.

일반적인 준비 프로브 오류의 예: 잘못된 포트를 대상으로 하거나 앱이 TCP만 노출하는데 HTTP를 예상하는 경우.

2. 볼륨 및 PersistentVolumeClaim (PVC) 실패

볼륨 문제로 인해 Pod가 대기 중인 경우, PVC 상태를 검사하십시오.

kubectl get pvc <pvc-name>

PVC 상태가 Pending이면 클러스터가 일치하는 StorageClass 또는 바인딩할 적합한 PersistentVolume을 찾지 못했음을 의미합니다. 특정 바인딩 오류에 대해 PVC 이벤트를 확인하십시오.

3. 어피니티 및 안티-어피니티 규칙

nodeAffinity 또는 podAntiAffinity와 같은 복잡한 스케줄링 규칙은 모든 기준을 충족하는 노드가 없는 경우 Pod가 스케줄링되지 않도록 의도치 않게 방지할 수 있습니다. Pod가 Pending 상태로 유지되고 이벤트에 스케줄링 제한이 언급되면 이러한 규칙을 검토하십시오.

예를 들어, 기존 노드가 가지고 있지 않은 특정 레이블(nodeSelector)을 가진 노드에서 Pod가 실행되도록 요구하면 Pod는 절대 스케줄링되지 않습니다.

# 예시: 'disktype: ssd' 레이블이 지정된 노드로 배포 제한
spec:
  nodeSelector:
    disktype: ssd
  containers:
  # ...

문제 해결 팁: 제한적인 nodeSelector 또는 affinity 규칙을 일시적으로 주석 처리하십시오. Pod가 성공적으로 스케줄링되면 문제가 선택 기준에 있음을 알 수 있습니다.

디버깅 워크플로우 요약

배포 실패에 직면했을 때, 다음 구조화된 경로를 따르십시오.

  1. 배포 상태: kubectl get deployments -> 레플리카가 준비 상태를 보고하고 있습니까?
  2. Pod 이벤트: kubectl describe pod <failing-pod> -> Events 섹션에서 즉각적인 오류(ImagePull, OOMKilled, 볼륨 문제)를 확인하십시오.
  3. 컨테이너 로그: kubectl logs <failing-pod> -> 컨테이너가 시작되지만 충돌하는 경우(CrashLoopBackOff), 애플리케이션 로직 또는 활성 프로브가 의심됩니다.
  4. 리소스 확인: Pod가 Pending인 경우, 리소스 제약 조건(Insufficient cpu/memory) 또는 실패한 볼륨 바인딩(PVC 상태)을 확인하십시오.
  5. 구성 유효성 검사: 들여쓰기, 올바른 필드 이름 및 유효한 리소스 값(요청/제한)에 대해 YAML을 검토하십시오.

상태, 이벤트 및 기본 YAML 구성을 Kubernetes 기대치에 대해 체계적으로 확인함으로써 대부분의 배포 실패의 근본 원인을 신속하게 격리하고 해결할 수 있습니다.