Kubernetes PVC Pending 해결 — PV·PVC 마운트 문제

kubectl get pvc를 쳤을 때 STATUS가 Pending에서 움직이지 않고, 그 볼륨을 쓰는 Pod는 ContainerCreating에 갇혀 있다면 스토리지가 아직 붙지 못한 상태입니다. PVC(PersistentVolumeClaim)는 "이만큼의 디스크를 달라"는 요청서고, PV(PersistentVolume)는 실제 디스크입니다. Pending은 요청서에 맞는 디스크를 찾거나 만들지 못했다는 뜻이며, 원인은 거의 정해져 있습니다.

1단계 — 왜 못 붙는지 직접 본다

추측하지 말고 PVC의 이벤트부터 봅니다.

Kubernetes

# PVC 상태와 바인딩된 PV 확인
kubectl get pvc

# Pending 이유는 여기 Events에 다 나온다
kubectl describe pvc <pvc>

# 클러스터에 어떤 StorageClass가 있는지
kubectl get storageclass

describe의 Events에 no persistent volumes available, waiting for first consumer, storageclass not found 같은 문구가 핵심 단서입니다.

2단계 — 메시지로 원인 좁히기

Events 메시지	흔한 의미	어디를 보나
`storageclass "x" not found`	없는 StorageClass 지정	`kubectl get storageclass`
`no persistent volumes available`	정적 PV가 없거나 조건 불일치	PV의 용량·접근모드
`waiting for first consumer`	정상 (Pod 스케줄 대기)	Pod가 스케줄되는지
`failed to provision volume`	프로비저너·권한 문제	CSI 드라이버 로그

원인 4가지와 해결

① StorageClass 이름 오타·누락 — PVC가 존재하지 않는 storageClassName을 가리키면 영원히 Pending입니다. kubectl get storageclass로 실제 이름을 확인하고, 기본 클래스를 쓰려면 storageClassName 필드를 아예 비웁니다. 클러스터에 기본 클래스(default 표시)가 있는지도 확인합니다.

② 동적 프로비저닝이 없는데 정적 PV가 부족 — 베어메탈·온프렘에서는 동적 프로비저너가 없을 수 있습니다. 이때는 PV를 직접 만들어야 합니다. PVC가 요구하는 용량보다 PV가 작거나, 접근 모드가 다르면 바인딩되지 않습니다. PV의 capacity.storage가 요청보다 크거나 같아야 합니다.

③ 접근 모드 불일치 — PVC가 ReadWriteMany를 요구하는데 PV·스토리지가 ReadWriteOnce만 지원하면 못 붙습니다. NFS·CephFS가 아닌 블록 스토리지(EBS 등)는 대개 ReadWriteOnce만 됩니다.

④ WaitForFirstConsumer — volumeBindingMode: WaitForFirstConsumer인 StorageClass는 Pod가 스케줄되기 전까지 일부러 Pending을 유지합니다. 이건 정상이며, 그 PVC를 쓰는 Pod를 배포하면 풀립니다. Pod가 다른 이유로 스케줄 안 되는지 describe pod로 확인합니다.

정적 PV 예시 (온프렘)

YAML

apiVersion: v1
kind: PersistentVolume
metadata:
  name: data-pv
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /mnt/data

PVC의 요청 용량이 5Gi 이하, 접근 모드가 ReadWriteOnce여야 이 PV에 바인딩됩니다.

체크리스트

Kubernetes

kubectl describe pvc <pvc>          # Events에서 Pending 사유
kubectl get storageclass            # 클래스 이름·기본 여부
kubectl get pv                      # 바인딩 가능한 PV·용량·접근모드
kubectl describe pod <pod>          # WaitForFirstConsumer면 Pod 스케줄 확인

이 4개면 위 원인 대부분이 좁혀집니다.

PV·PVC를 직접 만들어 바인딩 과정을 눈으로 확인하는 실습은 쿠버네티스 트랙에서 해볼 수 있습니다 — 회원가입 없이 무료로.