Kubernetes PVC Pending 오류 | PersistentVolumeClaim 대기 문제로 답답하셨죠? 복잡한 원인 분석부터 확실한 해결 방법까지, 이 글 하나로 모든 것을 해결해 드립니다.
관련 정보를 찾아봐도 명확한 해결책을 찾기 어렵고, 무엇부터 손봐야 할지 막막했을 겁니다.
실제 문제 해결 경험을 바탕으로 구성된 이 글을 통해, Pending 상태를 신속하게 해제하고 정상적으로 PersistentVolumeClaim을 활용하는 방법을 배우실 수 있습니다.
PVC Pending 오류 원인 분석
Kubernetes에서 PersistentVolumeClaim(PVC)이 ‘Pending’ 상태로 멈추는 문제는 클라우드 네이티브 환경에서 자주 발생하는 불편함 중 하나입니다. 마치 주문한 상품이 배송되지 않고 창고에 계속 머무르는 것과 같습니다.
PVC는 Pod가 사용할 저장 공간을 요청하는 명세입니다. 예를 들어, 여러분이 스마트폰에서 사진을 저장하기 위해 128GB 저장 공간을 원한다고 요청하는 것과 같습니다. 이 요청이 제대로 처리되지 않으면 ‘Pending’ 상태가 됩니다.
이 요청이 정상적으로 처리되기 위해서는 Kubernetes 클러스터에 해당 요구사항을 만족하는 PersistentVolume(PV)이 존재해야 합니다. 마치 128GB 저장 공간을 제공할 수 있는 스마트폰 자체(PV)가 있어야 하는 것처럼 말이죠. 만약 128GB PV가 없거나, 있더라도 다른 Pod에서 이미 사용 중이라면 PVC는 대기 상태에 머물게 됩니다.
PV는 크게 두 가지 방식으로 생성됩니다. 하나는 관리자가 미리 생성해 놓은 PV(Static Provisioning)이고, 다른 하나는 PVC 요청 시 자동으로 생성되는 PV(Dynamic Provisioning)입니다. 예를 들어, 삼성전자의 갤럭시 S24 Ultra 모델(PV)은 미리 생산되어 준비되어 있을 수도 있고, 사용자의 요청에 따라 즉시 생산될 수도 있습니다.
Dynamic Provisioning은 StorageClass라는 설정을 통해 관리됩니다. StorageClass는 SSD, HDD, 혹은 클라우드 스토리지(AWS EBS, GCP Persistent Disk 등)와 같이 스토리지의 종류와 성능을 정의합니다. 마치 소비자가 SSD 기반의 고성능 저장 공간을 원할지, 혹은 HDD 기반의 대용량 저장 공간을 원할지 선택하는 것과 같습니다. 해당 StorageClass에 맞는 PV가 자동으로 생성되지 않으면 PVC는 Pending 상태를 벗어나기 어렵습니다.
| 스토리지 종류 | 일반적 특징 | 예상 속도 | 가격대 |
| SSD (GP2/gp3) | 빠른 입출력 성능 | 높음 | 중간~높음 |
| HDD (SC1/st1) | 대용량 저장에 적합 | 보통 | 낮음~중간 |
| 클라우드 스토리지 (AWS EBS IO2) | 고성능, 고가용성 | 매우 높음 | 높음 |
PVC Pending 오류를 해결하기 위해서는 먼저 kubectl describe pvc
예를 들어, “no persistent volumes available for this claim and no storage class is set” 와 같은 메시지가 보인다면, 요청한 용량과 일치하는 PV가 없거나 StorageClass 설정에 문제가 있는 것입니다. 이 경우, 사용 가능한 PV가 있는지 확인하거나, StorageClass 설정을 올바르게 지정해야 합니다.
중요: PersistentVolumeClaim Pending 오류는 주로 PV 부족, StorageClass 설정 오류, 혹은 Access Mode 충돌 때문에 발생합니다. 각 원인을 정확히 진단하고 해결해야 합니다.
- PV 확인: kubectl get pv 명령어로 사용 가능한 PV 리스트 확인
- StorageClass 확인: PVC와 연결된 StorageClass가 올바르게 설정되었는지 점검
- Access Mode: PVC의 Access Mode(ReadWriteOnce, ReadOnlyMany 등)가 PV와 호환되는지 확인
- Provisioner 설정: StorageClass에 정의된 Provisioner가 정상적으로 작동하는지 확인
PersistentVolumeClaim 대기 해결법
PersistentVolumeClaim(PVC)이 ‘Pending’ 상태에 머무르는 문제를 해결하기 위한 구체적인 단계와 실전 팁을 안내합니다. 각 과정별 예상 소요 시간과 주의 사항을 명확히 제시하여 문제 해결에 실질적인 도움을 드리고자 합니다.
가장 먼저 PVC와 연결될 StorageClass가 올바르게 정의되었는지 확인해야 합니다. StorageClass의 provisioner 설정이 정확한 스토리지 공급자와 일치하는지 검증하는 데 보통 5분 이내로 소요됩니다. 또한, 해당 StorageClass에 대한 PersistentVolume(PV)이 자동으로 생성되도록 reclaimPolicy가 Delete 또는 Retain으로 설정되어 있는지 확인하는 것이 중요합니다.
StorageClass의 volumeBindingMode가 WaitForFirstConsumer로 설정된 경우, PVC를 사용하는 Pod가 생성되기 전까지 PV 할당이 지연될 수 있습니다. 이 설정은 PV의 노드 선호도를 Pod의 노드 선호도와 일치시키기 위함이므로, Pod 생성 후 PVC가 ‘Bound’ 상태로 변경되는지 확인해야 합니다.
PVC의 accessModes와 요청된 capacity가 사용 가능한 스토리지 풀에서 지원되는지 여부를 확인하는 것이 필수적입니다. 종종 스토리지 공급자 측의 제약으로 인해 ‘Pending’ 상태가 발생할 수 있습니다. 이는 일반적으로 10분에서 30분 정도의 추가 확인 시간을 필요로 합니다.
만약 동적 프로비저닝이 아닌 수동으로 PV를 생성하는 경우, PV의 spec에 정의된 storageClassName이 PVC의 storageClassName과 정확히 일치해야 합니다. 이 매칭이 되지 않으면 PVC는 영원히 ‘Pending’ 상태에 머무르게 됩니다.
핵심 팁: ‘kubectl describe pvc
- 즉시 확인: 스토리지 컨트롤러의 로그를 확인하여 프로비저닝 실패 원인을 파악하세요.
- 재부팅 시도: 스토리지 관련 데몬이나 컨트롤러를 재시작하는 것이 문제를 해결하는 경우도 있습니다.
- 공식 문서 참조: 사용 중인 스토리지 솔루션(예: Ceph, AWS EBS, GCE PD)의 공식 Kubernetes 통합 문서를 참고하세요.
- 커뮤니티 지원: 해결이 어려운 경우, Kubernetes 관련 커뮤니티나 포럼에 질문하여 도움을 받는 것도 좋은 방법입니다.
StorageClass 설정 확인 방법
Kubernetes PVC Pending 오류 해결을 위해 StorageClass 설정을 점검하는 실질적인 방법을 단계별로 안내합니다. 각 과정의 예상 소요 시간과 주요 체크 포인트를 포함하여 바로 적용할 수 있도록 구성했습니다.
작업 시작 전, Kubernetes 클러스터 환경과 kubectl 명령어를 사용할 준비가 되어 있는지 확인해야 합니다. StorageClass 정의를 직접 확인할 수 있는 권한이 필요합니다.
또한, Pending 상태인 PersistentVolumeClaim(PVC)의 이름과 해당 PVC가 속한 네임스페이스를 미리 파악해 두면 진단이 더욱 용이합니다.
| 단계 | 실행 방법 | 소요시간 | 주의사항 |
| 1단계 | 클러스터 접속 및 kubectl 확인 | 2-3분 | kubectl version 명령어로 정상 작동 확인 |
| 2단계 | PVC 정보 확인 | 3-5분 | kubectl get pvc |
| 3단계 | StorageClass 목록 조회 | 2-3분 | kubectl get sc 명령어로 사용 가능한 StorageClass 확인 |
| 4단계 | PVC와 StorageClass 매칭 확인 | 5-10분 | PVC 정의에서 storageClassName 필드와 실제 SC 이름 일치 여부 확인 |
StorageClass 설정 오류로 인해 PersistentVolumeClaim이 Pending 상태에 머무는 경우가 많습니다. 특히, StorageClass의 provisioner가 올바르게 설정되었는지, 해당 provisioner가 정상적으로 작동하는지 확인하는 것이 중요합니다.
만약 kubectl get sc 명령어로 StorageClass가 조회되지 않거나, PVC 정의에 명시된 StorageClass 이름이 존재하지 않는다면 문제가 발생합니다. 이 경우, StorageClass를 생성하거나 이름을 정확히 맞춰야 합니다.
체크포인트: PVC에서 storageClassName이 명시되지 않은 경우, 기본 StorageClass가 사용됩니다. 클러스터에 기본 StorageClass가 설정되어 있는지, 그리고 해당 StorageClass가 정상적으로 동작하는지 확인하세요.
- ✓ StorageClass 존재 여부: kubectl get sc 명령어로 StorageClass 목록 확인
- ✓ 이름 일치 확인: PVC YAML 파일의 storageClassName과 실제 StorageClass 이름 비교
- ✓ Provisioner 동작 확인: StorageClass가 의존하는 provisioner (예: CSI driver) 정상 작동 여부 점검
- ✓ 기본 StorageClass 설정: 동적으로 PV를 프로비저닝하기 위한 기본 StorageClass 설정 확인
PV와 PVC 바인딩 과정 이해
Kubernetes 환경에서 PersistentVolumeClaim (PVC)이 ‘Pending’ 상태로 머무르는 문제는 많은 사용자들에게 혼란을 야기합니다. 이는 PV (PersistentVolume)와 PVC 간의 바인딩 과정에 문제가 발생했음을 의미합니다.
PVC가 Pending 상태에 머무르는 가장 흔한 원인은 동적 프로비저닝 설정 오류나 수동 PV 생성 시 스토리지 클래스, 용량, 접근 모드 불일치입니다.
예를 들어, 요청한 PVC의 용량이 PV에 할당 가능한 용량보다 크거나, 특정 스토리지 클래스 이름을 잘못 지정하면 바인딩이 이루어지지 않습니다. 또한, 이미 사용 중인 PV를 지정하거나, PV의 접근 모드 (ReadWriteOnce, ReadOnlyMany, ReadWriteMany)가 PVC의 요구사항과 맞지 않을 때도 동일한 문제가 발생합니다.
이러한 Kubernetes PVC Pending 오류를 해결하기 위해서는 먼저 kubectl describe pvc
로그에서 ‘Provisioning failed’ 또는 ‘No PersistentVolumes available’와 같은 메시지가 보인다면, 스토리지 클래스 정의, PV의 어노테이션, 레이블, 용량, 접근 모드 설정이 PVC의 사양과 일치하는지 면밀히 재확인해야 합니다. 동적 프로비저닝을 사용하는 경우, StorageClass YAML 파일에 정의된 프로비저너가 올바르게 설정되었는지, 해당 프로비저너가 정상적으로 동작하는지 확인하는 것이 중요합니다.
- 용량 불일치: PVC 요청 용량과 PV 가용 용량 비교
- 접근 모드 충돌: PVC와 PV의 접근 모드 호환성 확인
- 스토리지 클래스 오류: StorageClass 이름 및 프로비저너 설정 검토
- 레이블/셀렉터 매칭: PV와 PVC 간 레이블 셀렉터 일치 여부 확인
권장 설정 및 예방 팁
PersistentVolumeClaim (PVC)가 Pending 상태에 머무르는 상황은 스토리지 프로비저닝 문제를 시사합니다. 이는 주로 StorageClass 설정 오류, Provisioner의 비정상 동작, 또는 노드와 스토리지 시스템 간의 통신 문제로 인해 발생합니다.
Kubernetes PVC Pending 오류 해결을 위해선 스토리지 프로비저닝의 작동 방식을 깊이 이해해야 합니다. Provisioner의 로그를 면밀히 분석하고, PersistentVolume (PV)과 PVC 간의 바인딩 조건을 정확히 파악하는 것이 중요합니다.
특히, 동적 프로비저닝 시 StorageClass에 명시된 Provisioner가 정상적으로 작동하는지, 해당 StorageClass가 노드에 바인딩 가능한지 확인해야 합니다. 때로는 네트워킹 정책이나 방화벽 설정이 프로비저너의 정상 작동을 방해하기도 합니다.
스토리지 클래스 간의 호환성 및 리소스 제한 설정을 최적화하면 예기치 못한 PVC Pending 오류 발생 빈도를 줄일 수 있습니다. 예를 들어, 동일한 Provisioner를 사용하는 다른 StorageClass에서 성공적으로 PV가 생성되고 있는지 확인하는 것은 좋은 진단 방법입니다.
또한, 스토리지 시스템 자체의 용량 부족이나 성능 저하도 간접적으로 PVC Pending 오류를 유발할 수 있습니다. 따라서 스토리지 시스템의 상태를 주기적으로 모니터링하고, 필요시 용량 증설이나 성능 개선 작업을 선제적으로 진행하는 것이 장기적인 안정성을 확보하는 길입니다.
전문가 팁: PersistentVolumeClaim (PVC) Pending 상태 해결을 위해 스토리지 Provisioner의 로그를 상세히 분석하고, 가능한 모든 네트워크 및 접근 권한 문제를 점검하는 것이 필수적입니다.
- StorageClass 검증: Provisioner 이름, 파라미터, Reclaim Policy 등 설정 값을 철저히 확인하세요.
- API 서버 통신 확인: Kubernetes API 서버와 스토리지 Provisioner 간의 통신이 원활한지 점검하세요.
- Resource Quotas/Limits: 네임스페이스별 Resource Quotas 또는 Limits 설정이 PV 생성을 제한하지 않는지 확인하세요.
- 스토리지 백엔드 상태: 사용 중인 스토리지 백엔드(예: NFS, Ceph, 클라우드 스토리지)의 상태를 점검하세요.
자주 묻는 질문
✅ Kubernetes에서 PersistentVolumeClaim(PVC)이 ‘Pending’ 상태로 멈추는 가장 일반적인 원인은 무엇인가요?
→ PVC가 ‘Pending’ 상태로 멈추는 가장 일반적인 원인은 클러스터에 PVC의 요구사항(용량, 접근 모드 등)을 만족하는 PersistentVolume(PV)이 없거나, Dynamic Provisioning을 위한 StorageClass 설정에 문제가 있기 때문입니다.
✅ PVC Pending 오류 발생 시, 문제의 원인을 파악하기 위해 어떤 명령어를 사용해야 하나요?
→ PVC Pending 오류 발생 시, kubectl describe pvc
✅ Dynamic Provisioning을 통해 PVC가 자동으로 PV를 생성하도록 하려면 무엇을 설정해야 하나요?
→ Dynamic Provisioning을 통해 PVC가 자동으로 PV를 생성하도록 하려면 StorageClass를 설정해야 합니다. StorageClass는 스토리지의 종류와 성능(SSD, HDD, 클라우드 스토리지 등)을 정의하며, 이를 통해 Kubernetes는 요청에 맞는 PV를 자동으로 프로비저닝합니다.