쿠버네티스 스토리지 트러블슈팅의 kubectl describe pv
쿠버네티스 환경에서 스테이트풀 애플리케이션을 운영하다 보면, 파드가 정상적으로 뜨지 않거나 데이터가 마운트되지 않는 장애를 필연적으로 마주하게 됩니다.
이때 가장 먼저 확인해야 할 영역이 바로 퍼시스턴트 볼륨과 퍼시스턴트 볼륨 클레임의 매핑 상태입니다.
많은 주니어 개발자들이 kubectl get pv 명령어로 간단한 상태만 확인하고 넘어가지만, 실제 운영 환경의 트러블슈팅을 위해서는 오브젝트의 상세 메타데이터와 이벤트를 추적할 수 있는 describe 명령어를 제대로 독해할 줄 알아야 합니다.
1. get과 describe 출석부와 생활기록부
쿠버네티스에서 리소스를 조회하는 두 명령어는 사용 목적이 명확히 다릅니다.
kubectl get pv 전체 현황 파악
$ kubectl get pv
NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS
local-pv 1Gi RWO Retain Available manual
get 명령어는 현재 클러스터 내 PV들의 요약된 목록을 보여줍니다.
이름, 용량, 접근 모드, 현재 상태 등 단편적인 정보만 표 형식으로 제공하므로, 전체적인 리소스 보유 현황이나 간략한 상태를 빠르게 확인할 때 사용합니다.
마치 학교의 출석부처럼 누가 있고 없는지, 현재 대략적인 상태가 어떤지만 체크하는 용도입니다.
kubectl describe pv local-pv 상세 정밀 진단
$ kubectl describe pv local-pv
Name: local-pv
StorageClass: manual
Status: Available
Capacity: 1Gi
Access Modes: RWO
Reclaim Policy: Retain
Source:
Type: HostPath
Path: /data/pv-local
Events:
<none>
반면 describe는 특정 리소스의 내부 상태를 해부하여 보여줍니다.
단순히 YAML로 정의한 스펙뿐만 아니라, 현재 실제로 호스트의 어느 경로를 참조하고 있는지, 어떤 이벤트를 거쳐 현재 상태에 도달했는지까지 기록되어 있습니다.
즉, 트러블슈팅을 위한 생활기록부이자 진단서 역할을 합니다.
2. 초보자 시각에서 분석하는 describe pv
describe 결과를 읽을 때는 단순히 글자를 읽는 것을 넘어, 각 항목이 인프라 관점에서 어떤 의미를 가지는지 파악해야 합니다.
반드시 체크해야 할 5가지 핵심 포인트입니다.
① 볼륨의 현재 라이프사이클
Status: Available
-
Available: PV가 정상적으로 생성되었으나, 아직 어떤 PVC와도 연결되지 않은 대기 상태입니다. 만약 파드가 스토리지를 기다리고 있는데 계속 이 상태라면, PVC의 스펙과 PV의 조건이 일치하지 않아 바인딩이 실패하고 있는 것입니다.
-
Bound: 특정 PVC와 성공적으로 연결된 상태입니다.
실무에서는Claim:항목을 함께 확인하여 의도한 파드의 PVC와 매핑되었는지 교차 검증해야 합니다. -
Released / Failed: PVC가 삭제되었으나 리클레임 정책에 의해 볼륨이 회수되지 못했거나, 실제 스토리지 인프라와의 통신에 실패한 비정상 상태입니다.
즉시 해결이 필요한 장애 상황입니다.
② 실제 물리 스토리지 경로
Source:
Type: HostPath
Path: /data/pv-local
쿠버네티스의 PV는 논리적인 추상화 계층이며, 실제 데이터가 저장되는 물리적 장소는 Source에 정의됩니다.
- 예시의
HostPath는 노드의 로컬 디렉토리를 직접 참조합니다. - AWS EBS, GCP PD, Ceph 등 에서는 이 부분에 CSI 드라이버 정보나 실제 클라우드 볼륨 ID가 표기됩니다.
장애 발생 시 인프라 담당자와 소통할 때 가장 먼저 확인해서 전달해야 하는 물리적 경로 식별자입니다.
③ 동시 접근 권한 설계
Access Modes: RWO
-
RWO: 단일 노드에서만 읽기/쓰기로 마운트할 수 있습니다.
가장 일반적인 모드이지만, 여러 노드에 걸쳐 배포되는 다중 인스턴스 파드가 동일한 PV를 공유하려고 하면 마운트 에러가 발생합니다. -
파드의 스케일 아웃을 고려하는 아키텍처라면 RWX 지원 여부를 스토리지 클래스 단계부터 검토해야 합니다.
④ 데이터 유실 방지의 마지노선
Reclaim Policy: Retain
-
Retain: PVC가 삭제되어도 PV와 실제 데이터는 삭제되지 않고 보존됩니다.
실무에서 운영 DB나 중요 로그를 다룰 때 데이터 실수를 방지하기 위해 반드시 설정해야 하는 정책입니다. -
Delete: PVC 삭제 시 클라우드 볼륨도 함께 삭제됩니다.
임시 작업 공간이나 테스트 환경이 아니라면 주의해서 사용해야 합니다.
⑤ 장애의 결정적 단서
Events: <none>
describe 명령어의 꽃이라고 할 수 있는 영역입니다.
볼륨 프로비저닝 실패, 노드와의 마운트 타임아웃, 권한 에러 등 PV가 겪은 최근의 상태 변화와 에러 메시지가 여기에 시간순으로 기록됩니다.
스토리지가 정상적으로 붙지 않을 때, 가장 먼저 스크롤을 내려 내려다봐야 하는 로그 영역입니다.
3. 요약
kubectl describe pv 명령어는 단순한 조회 명령어가 아닙니다.
쿠버네티스의 논리적 스토리지와 인프라스트럭처의 물리적 스토리지가 제대로 맞물려 있는지 검증하는 가장 확실한 도구입니다.
kubectl get pv: 전체 스토리지 리소스의 요약본을 확인하는 출석부kubectl describe pv: 상태, 물리 경로, 설정 권한, 장애 이벤트를 정밀 진단하는 생활기록부
스토리지 관련 이슈가 발생했을 때는 막연히 파드의 로그만 보지 말고, describe pv를 통해 스토리지의 생활기록부부터 꼼꼼히 체크하는 습관을 들이는 것이 좋다는것을 배웠습니다.
