K8s PVC Pending? 바인딩 실패 원인 5가지 완벽 진단 및 해결 가이드

Kubernetes 환경에서 애플리케이션을 배포하다 보면, 가장 당황스러운 순간 중 하나가 바로 PVC(PersistentVolumeClaim)가 Pending 상태에 멈춰버리는 상황입니다. "왜 이 볼륨이 할당되지 않는 거지?"라는 질문에 답을 얻기 위해 수많은 문서를 뒤지지만, 막상 장애가 발생하면 원인을 찾기 어렵습니다.

PVC가 Pending 상태에 머무는 것은 단순히 "볼륨이 안 생기는 것" 이상의 의미를 가집니다. 이는 클러스터의 스토리지 프로비저닝 파이프라인 어딘가에 문제가 생겼다는 신호입니다. 이 가이드는 DevOps 엔지니어와 인프라 운영자들이 가장 많이 겪는 PVC 바인딩 실패의 5가지 패턴을 체계적으로 진단하고, 장애 시간을 획기적으로 줄일 수 있는 실전 가이드를 제공합니다.

1. 첫 번째 진단 단계: kubectl describe pvc로 이벤트 로그 파헤치기

PVC가 Pending 상태일 때, 가장 먼저 해야 할 일은 감(感)이 아니라 증거(Evidence)를 수집하는 것입니다. 이때 핵심 명령어는 바로 kubectl describe pvc <pvc-name>입니다.

이 명령어의 출력 결과 중 Events 섹션과 Status 필드를 집중적으로 확인해야 합니다.

kubectl describe pvc my-app-pvc -n default

🔍 핵심 분석 포인트:

1. Events: 여기에 기록된 메시지는 시스템이 현재 시도하고 실패한 액션의 기록입니다. "Failed to provision volume" 같은 메시지가 보인다면, 그 직전에 어떤 리소스(예: StorageClass)를 참조했는지 확인해야 합니다.
2. Status: Phase: Pending 외에, 만약 VolumeBound가 되어야 하는데 그렇지 않다면, 시스템이 어떤 리소스를 찾지 못했는지 힌트를 얻을 수 있습니다.

만약 Events에 아무런 유의미한 정보가 없다면, 문제는 PVC 레벨이 아닌, StorageClass 레벨이나 클러스터 자체의 CSI 드라이버 레벨에 있을 가능성이 높습니다.

2. 원인 1 & 2: StorageClass 부재 및 잘못된 바인딩 패턴 (가장 흔한 실수)

대부분의 Pending 문제는 이 단계에서 발생합니다. PVC는 반드시 유효한 StorageClass를 참조해야 하며, 이 StorageClass가 동적 프로비저닝(Dynamic Provisioning)을 지원하는지 확인해야 합니다.

💡 실습: 동적 프로비저닝 지원 확인

StorageClass가 동적 프로비저닝을 지원하는지 확인하는 가장 확실한 방법은 YAML을 통해 provisioner 필드를 검토하는 것입니다.

✅ 정상적인 StorageClass 예시 (AWS EBS 사용 시):

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-storage
provisioner: ebs.csi.aws.com  # <-- 이 부분이 핵심입니다.
parameters:
  type: gp3
reclaimPolicy: Delete
volumeBindingMode: Immediate

여기서 provisioner: ebs.csi.aws.com은 쿠버네티스에게 "이 스토리지 요청은 AWS CSI 드라이버를 통해 처리해야 한다"고 명시하는 역할을 합니다.

🚨 해결책:

1. StorageClass가 없는 경우: kubectl get sc로 확인하고, 없다면 클라우드 벤더 문서를 참고하여 적절한 StorageClass를 생성해야 합니다.
2. 잘못된 provisioner: 만약 클러스터가 NFS를 사용하는데 StorageClass에 aws.com 프로바이더가 명시되어 있다면, 이 불일치가 원인입니다.

3. 원인 3 & 4: AccessMode 불일치 및 ReclaimPolicy 검증

StorageClass가 정상적으로 지정되었더라도, PVC가 요구하는 접근 모드(AccessMode)가 실제 스토리지 백엔드가 지원하는 모드와 충돌할 수 있습니다.

📊 AccessMode별 발생 시나리오 비교표

⚠️ 실무 팁: 만약 애플리케이션이 여러 Pod에서 동시에 데이터를 수정해야 하는데 PVC가 Pending 상태라면, 사용하려는 스토리지 백엔드가 RWX를 지원하는지가 가장 먼저 의심 지점입니다. 만약 지원하지 않는다면, 애플리케이션 아키텍처를 변경하여 데이터 공유 방식을 재고해야 합니다.

또한, reclaimPolicy가 Delete인데, 실제 볼륨이 이미 존재하여 삭제 권한이 없을 경우에도 바인딩 과정에서 오류가 발생할 수 있습니다.

4. 원인 5: CSI 드라이버 및 클라우드 프로바이더 레벨 문제 (심화 디버깅)

위의 모든 설정이 완벽해 보일 때, 문제는 인프라 계층에 있습니다. 이는 쿠버네티스 컨트롤 플레인 바깥의 영역입니다.

🛠️ 디버깅 플로우차트 (Step-by-Step)

1. Step 1: kubectl get nodes 확인: 모든 노드가 Ready 상태인가? (노드 문제가 스토리지 할당을 막을 수 있음)
2. Step 2: CSI 드라이버 Pod 확인: kubectl get pods -n kube-system에서 CSI 관련 파드(예: aws-ebs-csi-driver)가 Running 상태인가?
3. Step 3: CSI 로그 확인: 만약 파드가 비정상이라면, 해당 파드의 로그를 확인합니다.
   Bash복사

   kubectl logs <csi-driver-pod-name> -n kube-system

   로그에서 Timeout, Authentication Failure, 또는 API Error 등의 키워드를 찾으면, 클라우드 자격 증명(Credentials)이나 네트워크 정책(NetworkPolicy) 문제일 확률이 90% 이상입니다.

⭐ 운영자 경험 공유: 제가 과거에 겪었던 가장 까다로운 케이스는 네트워크 보안 그룹(Security Group) 문제였습니다. CSI 드라이버가 클라우드 API를 호출할 때 필요한 아웃바운드 포트가 방화벽에 막혀있어, 실제로는 스토리지 프로비저닝 요청 자체가 외부로 나가지 못하고 실패하는 경우였습니다. 이 경우, Events에는 모호한 시간 초과(Timeout)만 기록됩니다.

🚀 PVC Pending 해결을 위한 최종 체크리스트 요약

이 체크리스트를 순서대로 따라가며 진단한다면, 대부분의 Pending 문제는 15분 이내에 해결할 수 있을 것입니다.

자주 묻는 질문 (FAQ)

Q1. PVC가 Pending 상태인데, 임시로 볼륨을 사용하려면 어떻게 해야 하나요? A1. 가장 빠른 임시 방편은 PersistentVolume 리소스를 직접 생성하여 PVC에 수동으로 바인딩하는 것입니다. 하지만 이는 근본적인 해결책이 아니므로, 반드시 StorageClass 설정을 수정하여 자동화를 구현해야 합니다.

Q2. volumeBindingMode: WaitForFirstConsumer는 언제 사용해야 하나요? A2. 이 모드는 PVC가 생성된 시점(즉시)에 볼륨을 할당하지 않고, 실제로 해당 PVC를 사용하는 Pod가 스케줄링될 때 비로소 볼륨 할당을 시작하게 합니다. 네트워크나 특정 노드 제약 조건이 있을 때 유용합니다.

Q3. kubectl describe pvc에서 VolumeStatus가 Bound인데도 Pod가 시작되지 않아요. A3. 이 경우, PVC 자체의 문제는 아닙니다. Pod의 Deployment 또는 StatefulSet 정의에 문제가 있거나, Pod가 참조하는 다른 리소스(예: ConfigMap, Secret)에 문제가 있을 가능성이 높습니다. Pod의 이벤트 로그를 확인하세요.