PV/PVC/StorageClass

Kubernetes 스토리지의 동적 프로비저닝, 바인딩, 확장 완벽 가이드

Kubernetes 스토리지의 동적 프로비저닝, 바인딩, 확장 완벽 가이드

목표: 상태유지 앱을 위한 스토리지 아키텍처를 설계할 수 있는 수준

🏗️ 스토리지 아키텍처

[Pod] ──> [PVC] ──> [PV] ──> [Storage Backend]
              │
              ▼
         [StorageClass]
         (동적 프로비저닝)

리소스	역할	생성자
StorageClass	프로비저너, 파라미터 정의	관리자
PV	실제 스토리지 볼륨	시스템 (동적) 또는 관리자 (정적)
PVC	사용자의 스토리지 요청	사용자

📦 StorageClass

기본 StorageClass

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: standard
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: kubernetes.io/gce-pd  # 클라우드별 다름
parameters:
  type: pd-standard
  replication-type: none
reclaimPolicy: Delete
allowVolumeExpansion: true
volumeBindingMode: WaitForFirstConsumer

NFS StorageClass (온프레미스)

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-client
provisioner: k8s-sigs.io/nfs-subdir-external-provisioner
parameters:
  archiveOnDelete: "false"
reclaimPolicy: Delete
volumeBindingMode: Immediate

# StorageClass 확인
kubectl get storageclass
kubectl get sc standard -o yaml

💾 PV (PersistentVolume)

정적 프로비저닝

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv001
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  hostPath:
    path: /data/pv001

PV 상태

상태	설명
Available	사용 가능
Bound	PVC에 바인딩됨
Released	PVC가 삭제됨, 재사용 대기
Failed	자동 재활용 실패

📋 PVC (PersistentVolumeClaim)

기본 PVC

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
  storageClassName: standard

Pod에 마운트

apiVersion: v1
kind: Pod
metadata:
  name: app-with-pvc
spec:
  containers:
  - name: app
    image: nginx
    volumeMounts:
    - name: data
      mountPath: /usr/share/nginx/html
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: my-pvc

# PVC 확인
kubectl get pvc
kubectl get pv

# 상세 정보
kubectl describe pvc my-pvc

🔄 동적 프로비저닝 흐름

[사용자: PVC 생성]
    │
    ▼
[StorageClass 확인]
    │
    ▼
[프로비저너: PV 자동 생성]
    │
    ▼
[PVC <-> PV 바인딩]
    │
    ▼
[Pod에서 사용 가능]

📈 볼륨 확장

PVC 확장 (StorageClass에서 allowVolumeExpansion: true 필요)

# 1. PVC 편집
kubectl patch pvc my-pvc --patch '{"spec":{"resources":{"requests":{"storage":"10Gi"}}}}'

# 2. 확인
kubectl get pvc my-pvc

# 3. 파일시스템 확장 (Pod에서)
kubectl exec -it app-with-pvc -- df -h
# ext4, xfs 등 파일시스템에 따라 추가 작업 필요

🐛 문제 해결

PVC Pending

# 원인 확인
kubectl describe pvc my-pvc

# 흔한 원인:
# 1. StorageClass 없음
kubectl get sc

# 2. 프로비저너 실패
kubectl get pods -n kube-system | grep provisioner

# 3. 리소스 부족 (클러스터)

PV Released 상태

# 재활용 정책 확인
kubectl get pv pv001 -o yaml | grep persistentVolumeReclaimPolicy

# 수동 재활용
kubectl patch pv pv001 -p '{"spec":{"claimRef": null}}'

📋 체크리스트

🔗 관련 노트

01-05-StatefulSet-관리 — 상태유지 앱
02-07-볼륨-타입 — 볼륨 종류
02-08-스테이트풀-앱-배포 — 실전 배포

마지막 업데이트: 2026-06-01