쿠버네티스 PVC Pending 원인 분석: StorageClass부터 CSI 바인딩 실패 완벽 진단 가이드

PersistentVolumeClaim(PVC)가 Pending 상태에 머무는 근본적인 이유

쿠버네티스 환경에서 서비스를 배포할 때 가장 흔하게 마주치는 좌절감 중 하나가 바로 PersistentVolumeClaim (PVC)이 'Pending' 상태에 갇히는 상황일 것입니다. 개발팀은 단순히 "볼륨을 연결해달라"고 요청했을 뿐인데, 실제로는 수많은 인프라 계층의 복잡한 상호작용 문제 때문에 배포가 막혀버립니다.

PVC Pending 상태란, 쿠버네티스 컨트롤 플레인이 사용자가 요청한 스토리지 자원(PVC)을 실제로 사용할 물리적/논리적 볼륨(PV)과 연결하는 과정(바인딩)에 실패했거나 아직 완료되지 않았음을 의미합니다. 이 문제는 단순히 YAML 파일의 오타로 끝나지 않습니다. StorageClass 설정 오류, CSI 드라이버 권한 문제, 클라우드 API 접근 제한 등 여러 계층에서 문제가 발생할 수 있습니다.

이 글은 단순한 원인 나열을 넘어, 마치 선배 DevOps 엔지니어가 옆에서 손잡고 문제를 해결해 주는 것처럼, 어떤 순서로 어떤 명령어를 실행하며 체계적으로 진단해야 하는지에 초점을 맞춘 실질적인 '진단 흐름도(Diagnosis Flowchart)'를 제공합니다.

💡 K8s 스토리지 바인딩 실패: 3단계 진단 체크리스트 (Flowchart)

PVC가 Pending 상태일 때, 무작정 재시작하거나 설정을 변경하는 것은 시간을 낭비할 수 있습니다. 다음의 순서대로 문제를 격리(Isolate)해 나가는 것이 가장 효율적입니다.

진단 흐름도 요약: PVC Pending 발견 $\rightarrow$ Step 1: PVC 요청 검토 (What?) $\rightarrow$ Step 2: StorageClass 유효성 및 존재 여부 확인 (How?) $\rightarrow$ Step 3: CSI 드라이버와 백엔드 자원 연결 상태 점검 (Can it connect?)

Step 1. PVC 정의와 이벤트 로그 분석 (The Symptom)

가장 먼저 해야 할 일은 "왜 Pending인지"에 대한 단서를 찾는 것입니다. kubectl describe 명령어는 이 과정에서 가장 강력한 도구입니다.

# 구문: kubectl describe pvc <pvc-이름> -n <네임스페이스>
kubectl describe pvc my-app-data -n default

🔍 주목할 부분: Events 섹션의 로그를 주의 깊게 확인해야 합니다. 여기에 "Failed to provision volume" 또는 특정 에러 메시지(예: Unauthorized, Invalid parameter)가 기록되어 있다면, 그 메시지가 곧 문제의 원인입니다. 이 로그는 모든 진단의 출발점입니다.

Step 2. StorageClass 유효성 및 Provisioner 검증 (The Blueprint)

PVC가 요청한 스토리지 타입이 실제로 존재하는지 확인합니다. PVC는 StorageClass라는 청사진을 참조하여 실제 PV를 생성하도록 지시합니다.

1. SC 목록 조회:

kubectl get sc
# 출력 예: standard-sc, fast-ssd-sc

요청한 스토리지 타입이 이 목록에 존재하는지 확인합니다.

2. SC 상세 검증 (핵심):

# 구문: kubectl describe storageclass <storageclass-이름> -n <네임스페이스>
kubectl describe sc standard-sc

🚨 핵심 체크 포인트: Provisioner 필드를 확인합니다. 이 값은 실제로 볼륨을 생성하는 백엔드 시스템(예: kubernetes.io/aws-ebs, cuelabs/gce-pd)을 가리킵니다. 만약 이 값이 잘못되었다면, PVC는 어떤 것도 만들 수 없습니다.

YAML 비교 분석 (정상 vs 오류):

Step 3. CSI 드라이버 및 권한(RBAC) 점검 (The Execution Layer)

StorageClass가 완벽하더라도, 실제로 볼륨 생성을 요청하는 주체(CSI Controller Pod)가 적절한 권한을 가지고 있지 않거나 네트워크 연결이 끊겨 있다면 실패합니다.

1. CSI 컨트롤러 상태 확인: 클러스터의 kube-system 네임스페이스에서 CSI 관련 파드들이 정상적으로 실행 중인지 확인해야 합니다. (예: AWS EBS CSI Driver, GCP PD CSI Driver 등)

# 예시 명령어: kube-system 네임스페이스의 CSI Pod 상태 확인
kubectl get pods -n kube-system | grep csi

만약 파드들이 CrashLoopBackOff나 Error 상태라면, 드라이버 자체에 문제가 있는 것입니다. 이는 클라우드 API 키 만료, 네트워크 설정 오류 등 복합적인 원인을 가집니다.

2. RBAC 권한 검증: PVC를 생성하는 ServiceAccount가 스토리지 자원을 만들 수 있는 충분한 Role과 RoleBinding을 가지고 있는지 확인해야 합니다. 이 단계는 종종 간과되지만, 실제 운영 환경에서 가장 흔하게 발생하는 실수 중 하나입니다.

💡 [관련 지식] Pod 자체의 배포 실패 원인이나 권한 문제는 Kubernetes Pod Pending 원인 7가지: kubectl describe로 완벽 진단하는 실전 가이드를 참고하여 점검할 수 있습니다.

🛠️ 원인별 해결책: 가장 흔하게 발생하는 4가지 실패 시나리오와 액션 플랜

진단 체크리스트를 거쳤다면, 이제 발견된 증상에 따른 구체적인 해결 방안을 적용해야 합니다.

시나리오 A: StorageClass 매칭 오류 (Type Mismatch)

증상: PVC가 존재하는 SC를 참조했으나, 해당 SC가 요청한 볼륨 타입(예: ReadWriteMany)을 지원하지 않아 Pending 상태에 머뭅니다. 원인: 클라우드 공급자별로 스토리지 유형의 특성이 다릅니다. 예를 들어, AWS EBS는 기본적으로 단일 노드에서만 쓰기가 가능하여 RWM 볼륨 생성을 제한할 수 있습니다. 해결책: PVC를 생성하기 전에 해당 SC가 지원하는 AccessMode와 VolumeType을 명확히 파악하고, 필요한 경우 네트워크 파일 시스템(NFS) 기반의 별도 스토리지 솔루션을 고려해야 합니다.

시나리오 B: CSI 드라이버 권한 문제 (RBAC Failure)

증상: kubectl describe pvc 이벤트 로그에 "Unauthorized" 또는 "Permission Denied"와 유사한 메시지가 반복적으로 나타납니다. 원인: PVC를 생성하는 ServiceAccount가 클라우드 API 호출이나 볼륨 생성을 위한 커널 레벨의 권한을 받지 못했기 때문입니다. 해결책: 해당 네임스페이스의 ServiceAccount에 스토리지 관련 리소스(PV, SC)를 관리할 수 있는 충분한 Role과 이를 바인딩하는 ClusterRoleBinding이 부여되었는지 확인해야 합니다.

시나리오 C: 클라우드 파라미터 불일치 (Parameter Mismatch)

증상: PVC가 생성되는 과정에서 "Invalid parameter" 또는 "Missing required field"와 같은 에러 메시지가 발생합니다. 원인: 사용자가 정의한 StorageClass의 parameters에 클라우드 공급자(AWS, GCP 등)가 필수적으로 요구하는 파라미터(예: 특정 암호화 옵션, 가용 영역 지정 등)를 누락했거나 잘못 설정했을 때 발생합니다. 해결책: 공식 문서에서 해당 스토리지 타입이 요구하는 최소한의 파라미터 목록을 확인하고, SC YAML에 이를 추가해야 합니다.

# 수정 전 (오류 가능성):
parameters:
  type: gp2 

# 수정 후 (필수 파라미터 추가 예시):
parameters:
  type: gp3
  iops: "500" # 필수 IOPS 값 지정
  encrypted: "true" # 암호화 여부 명시

시나리오 D: 네트워크/방화벽 문제 (Connectivity Failure)

증상: CSI Pod 로그에서 Timeout, Connection Refused 등의 메시지가 반복적으로 발견됩니다. 원인: 쿠버네티스 클러스터 외부의 스토리지 API 엔드포인트로 나가는 아웃바운드 트래픽이 방화벽이나 보안 그룹에 의해 차단된 경우입니다. 해결책: 클러스터 노드에서 해당 스토리지 공급자의 API 엔드포인트(IP 주소 또는 도메인)로의 네트워크 경로가 열려 있는지, 그리고 필요한 포트(예: 443/TCP)가 허용되었는지 인프라 팀과 협력하여 점검해야 합니다.

✨ K8s 스토리지 관리를 위한 GitOps 기반 습관화 제안

PVC Pending 문제는 결국 '불확실성'에서 비롯됩니다. 수동으로 kubectl describe를 반복하며 진단하는 것은 피로도가 높고, 휴먼 에러가 발생하기 쉽습니다.

궁극적으로 가장 안정적인 인프라 운영 방법은 GitOps (Infrastructure as Code) 원칙을 적용하여 스토리지 설정을 코드로 관리하고, 배포 전에 자동화된 검증 프로세스를 거치는 것입니다.

1. IaC 도구 활용: Terraform이나 Pulumi 같은 IaC 도구를 사용하여 StorageClass 정의와 네트워크 리소스까지 모두 코드에 포함합니다.
2. Pre-commit Hook 구현: Git 커밋 단계에서 스토리지 YAML 파일의 문법 검사, 필수 파라미터 누락 여부 등을 자동으로 체크하는 훅을 추가하여, 잘못된 설정이 클러스터에 도달하는 것을 원천 차단해야 합니다.

이렇게 관리하면, 문제가 발생했을 때도 "어떤 사람이 언제 무엇을 바꿨는가?"를 Git의 커밋 히스토리에서 명확하게 추적할 수 있습니다.

자주 묻는 질문 (FAQ)

Q1: PVC Pending 상태와 Pod Pending 상태는 같은 문제인가요? A: 아닙니다. PVC Pending은 스토리지 볼륨 자체(PV)가 생성되거나 바인딩되는 단계에서 문제가 발생한 것입니다. 반면, Pod Pending은 컨테이너 이미지를 가져오지 못했거나, 리소스 부족, 또는 네트워크 준비 완료(Readiness Probe) 실패 등 Pod의 실행 자체가 지연되는 문제입니다.

Q2: StorageClass를 수정하면 기존 PVC에 영향을 주나요? A: 일반적으로는 그렇지 않습니다. StorageClass는 새로운 자원을 생성할 때 참조하는 '템플릿' 역할을 합니다. 이미 바인딩이 완료되어 사용 중인 PV/PVC에는 직접적인 영향은 없습니다. 하지만 SC의 provisioner 자체를 변경하거나 삭제하면, 이후에 생성되는 모든 PVC가 영향을 받습니다.

Q3: CSI 드라이버 로그에서 "API rate limit exceeded" 에러가 발생했다면 어떻게 해야 하나요? A: 이는 클라우드 공급자 API 호출 횟수 제한(Rate Limit)을 초과했음을 의미합니다. 가장 먼저 할 일은 해당 스토리지 자원 요청의 빈도를 줄이는 것입니다. 근본적으로는 캐싱 전략을 도입하거나, 배치 처리 방식으로 작업을 분산하여 API 부하를 낮추는 것이 필요합니다.