PVC가 계속 Pending 상태일 때: StorageClass 매칭 실패 완벽 디버깅 가이드

안녕하세요, 인프라를 설계하고 운영하는 동료 엔지니어 여러분.

Kubernetes 환경에서 애플리케이션을 배포할 때, 가장 흔하게 마주치면서도 가장 디버깅하기 까다로운 장애 중 하나가 바로 PersistentVolumeClaim (PVC)가 Pending 상태에 머무르는 현상입니다. 특히 스토리지 프로비저닝 과정에서 StorageClass와 관련된 문제가 꼬일 때면, 마치 블랙박스 속의 신호처럼 원인을 찾기 어렵죠.

"왜 내 PVC는 계속 Pending일까?" 이 질문에 대한 답의 핵심은 바로 StorageClass의 동작 원리와, 그 과정에서 발생하는 미묘한 매칭 실패에 있습니다. 이 가이드는 단순한 명령어 나열을 넘어, 시니어 엔지니어가 옆에서 팁을 주듯이, 이 복잡한 문제를 체계적으로 진단하고 해결할 수 있는 실전 체크리스트를 제공합니다.

스토리지 추상화의 핵심: StorageClass의 역할 이해하기

우리가 클라우드 환경에서 사용하는 실제 스토리지(AWS EBS, GCP PD, NFS 등)는 종류가 너무 다양합니다. 만약 PVC를 만들 때마다 "너는 EBS로 할래? 아니면 NFS로 할래?"라고 물어봐야 한다면, 개발 속도는 현저히 떨어질 겁니다.

바로 이 지점에서 **StorageClass**가 등장합니다.

StorageClass는 스토리지의 *속성(Availability Zone, 성능 레벨, 백업 정책 등)*을 추상화하여 정의하는 일종의 '규약서'입니다. PVC가 이 StorageClass를 참조하면, Kubernetes는 "아, 이 클래스에 정의된 방식으로 스토리지 자원을 요청하면 되겠구나"라고 판단하고, 실제 스토리지 프로비저너(Provisioner)에게 요청을 넘기게 됩니다.

핵심 원리: PVC $\xrightarrow{\text{참조}}$ StorageClass $\xrightarrow{\text{지시}}$ Provisioner $\xrightarrow{\text{실행}}$ PersistentVolume (PV) 할당

만약 이 과정 중 어느 한 단계라도 연결이 끊기거나, 요청된 조건이 실제 환경과 맞지 않으면, PVC는 영원히 Pending 상태에 갇히게 됩니다.

🚨 가장 흔한 실수 3가지: 매칭 실패의 함정

대부분의 Pending 문제는 복잡한 버그가 아니라, 사소한 설정 오류에서 비롯됩니다. 다음 세 가지 시나리오를 먼저 점검해 보세요.

1. StorageClass 이름 오타 또는 미존재 (The Typo Trap)

가장 흔합니다. YAML 파일에 오타가 있거나, 해당 StorageClass 자체가 클러스터에 배포되지 않았을 때 발생합니다.

진단 명령어:

# 클러스터에 존재하는 모든 StorageClass 목록을 확인합니다.
kubectl get storageclass

만약 여기서 원하는 클래스 이름이 보이지 않는다면, 먼저 해당 클래스를 생성해야 합니다.

2. 네임스페이스 범위 문제 (Scope Misunderstanding)

StorageClass는 클러스터 레벨(Cluster-scoped)로 정의할 수도 있고, 특정 네임스페이스(Namespace-scoped)로 정의할 수도 있습니다. PVC를 생성하는 네임스페이스와 StorageClass가 정의된 범위를 혼동하면 매칭에 실패합니다.

3. 프로비저너(Provisioner) 불일치 또는 권한 문제

StorageClass 정의 시 명시된 provisioner 이름이 실제 클러스터에 배포된 CSI 드라이버와 일치하지 않거나, 해당 드라이버가 정상적으로 동작하지 않을 때 발생합니다.

💡 YAML 비교 예시 (실패 vs. 성공)

만약 StorageClass 정의가 다음과 같이 되어 있다면 (실패 예시):

# ❌ 잘못된 예시: provisioner가 존재하지 않거나 오타가 있음
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata: { name: wrong-provisioner-sc }
provisioner: "non.existent.provisioner.io" # <-- 문제의 지점

반면, 실제 동작하는 CSI 드라이버를 사용한다면 (성공 예시):

# ✅ 올바른 예시: 실제 CSI 드라이버를 명시
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata: { name: fast-storage }
provisioner: csi.storage.vendor.com/driver-name # <-- 실제 드라이버 이름
parameters: { type: premium }

🕵️‍♂️ 심층 디버깅 가이드: 로그를 읽는 법

위의 기본적인 체크리스트를 통과했는데도 Pending이라면, 이제는 시스템의 '이벤트 로그'를 깊이 파고들 시간입니다.

1. kubectl describe pvc로 이벤트 추적하기

PVC 객체 자체의 Events 섹션은 가장 중요한 단서가 담겨 있습니다.

kubectl describe pvc <pvc-name> -n <namespace>

출력된 내용 중 Events 섹션을 유심히 보세요. 만약 Provisioner failed와 같은 메시지가 보인다면, 이는 스토리지 요청 자체가 실패했다는 명확한 신호입니다. 이 메시지 근처에 어떤 종류의 에러(예: 인증 실패, 리소스 부족 등)가 언급되어 있는지 캡처하는 것이 중요합니다.

2. CSI 드라이버 및 프로비저너 로그 확인 (최종 병기)

만약 Events에서 모호한 에러만 발견된다면, 문제는 PVC가 아닌 실제 프로비저너(Provisioner) 자체에 있을 가능성이 높습니다.

이 경우, 해당 프로비저너가 사용하는 Pod나 DaemonSet의 로그를 확인해야 합니다. 예를 들어, AWS EBS CSI 드라이버를 사용한다면, 해당 드라이버가 배포된 노드의 로그를 확인하여 API 호출 단계에서 어떤 에러가 반환되었는지 추적해야 합니다.

✍️ 시니어 엔지니어의 실전 팁: 저는 PVC가 Pending일 때, 단순히 kubectl describe만 보지 않습니다. 항상 kubectl get events --field-selector involvedObject.name=<pvc-name>을 함께 실행하여, 해당 PVC와 관련된 모든 이벤트 스트림을 시간 순서대로 재구성합니다. 이 과정을 통해 '요청 시점'과 '실패 감지 시점' 사이의 시간차를 분석하는 것이 디버깅 속도를 획기적으로 높여줍니다.

🚀 Best Practice: 명시적 지정과 모범 사례

가장 안전하고 모범적인 방법은 PVC를 생성할 때 storageClassName을 명시적으로 지정하는 것입니다.

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteOnce
  # ⭐ 가장 중요한 부분: 클래스 이름을 명시합니다.
  storageClassName: fast-storage 
  resources:
    requests:
      storage: 10Gi

이 방식을 사용하면, 클러스터에 여러 종류의 스토리지 클래스가 있더라도 원하는 자원을 정확히 지정할 수 있어 불필요한 매칭 실패를 원천 차단할 수 있습니다.

자주 묻는 질문 (FAQ)

Q1. PVC가 Pending 상태일 때, storageClassName을 아예 생략해도 되나요? A1. 아닙니다. storageClassName을 생략하면, 클러스터의 StorageClass 중 '기본값(Default)'으로 지정된 클래스를 사용하려고 시도합니다. 만약 기본값이 설정되어 있지 않거나, 기본값이 원하는 스토리지와 다르면 Pending 상태가 됩니다.

Q2. StorageClass를 변경하고 싶을 때, PVC를 삭제해야 하나요? A2. 네, 일반적으로 PVC의 storageClassName을 변경하려면 PVC를 삭제하고, 변경된 storageClassName을 명시하여 새 PVC를 생성해야 합니다. (단, PV가 이미 바인딩되어 있다면, PV를 먼저 분리(Unbind)하는 과정이 필요할 수 있습니다.)

Q3. CSI 드라이버가 없다면 어떻게 스토리지 자원을 요청해야 하나요? A3. CSI 드라이버는 현대 클라우드 네이티브 환경의 표준입니다. 만약 드라이버를 사용할 수 없다면, 클러스터의 관리자에게 요청하여 해당 스토리지 타입에 맞는 CSI 드라이버 배포를 요청하거나, 혹은 StorageClass를 사용하지 않고 PersistentVolume을 직접 생성하여 바인딩하는 레거시 방식을 고려해야 합니다.