볼륨 상태 모니터링

볼륨 상태 모니터링 (Volume Health Monitoring)

이 기능을 사용하려면 사용자(또는 클러스터 관리자)가 클러스터의 모든 관련 컴포넌트에서 CSIVolumeHealth 기능 게이트(feature gate)를 활성화해야 해요.

자세한 내용은 기능 게이트 활성화/비활성화 (Enable Or Disable Feature Gates)를 참고하세요.

**CSI 볼륨 상태 모니터링(CSI volume health monitoring)**은 CSI 드라이버가 볼륨이나 그 스토리지 백엔드의 상태 문제를 Kubernetes에 직접 보고할 수 있게 해줍니다. 드라이버는 CSI RPC를 통해 보고하고, Kubernetes는 그 보고를 세 가지 상태 필드에 표면화합니다: PersistentVolumeClaim.status.healthStatus, Pod.status.volumeHealth, CSINode.status.storageHealth. 자동화는 일시적인 Events나 벤더별 대시보드에서 볼륨 상태를 재구성하는 대신 이 지속적인 상태 필드를 감시할 수 있어요.

참고: CSIVolumeHealth 기능 게이트는 Kubernetes v1.21부터 존재했지만, 이 페이지에서 설명하는 메커니즘은 원래 알파 구현을 대체하는 재설계입니다. 무엇이 바뀌었는지는 제한 사항을 참고하세요.

출처: 문서

작동 방식 (How it works)

CSI 사양은 상태 보고를 위한 네 가지 RPC를 정의합니다.

CSI 컨트롤러 플러그인에서: ControllerListVolumeHealth와 ControllerGetVolumeHealth. 컨트롤러가 관찰하는 볼륨별 상태용입니다.
CSI 노드 플러그인에서: NodeGetVolumeHealth. 노드가 관찰하는 볼륨별 상태용이고, NodeGetStorageHealth는 그 노드에서 보이는 스토리지 백엔드의 상태용입니다.

드라이버는 지원하려는 RPC만 구현하면 되며, CSI 플러그인 캐퍼빌리티(capabilities)를 통해 지원을 광고합니다. 이 RPC 중 어느 것도 구현하지 않는 드라이버는 절대 조사(probe)되지 않으며, 그 드라이버에 대한 보고는 휴면 상태로 유지됩니다. 컨트롤러 LIST_VOLUME_HEALTH 캐퍼빌리티를 광고하는 드라이버는 반드시 GET_VOLUME_HEALTH도 광고해야 합니다. csi-external-health-monitor-controller 사이드카가 이 요구 사항을 강제합니다.

각 상태 보고는 기계가 파싱할 수 있는 작은 값 집합에서 가져온 상태와, 드라이버가 정의한 reason, 선택적인 사람이 읽을 수 있는 message를 함께 전달합니다.

볼륨 수준 상태 값(PersistentVolumeClaim.status.healthStatus와 Pod.status.volumeHealth에 사용): Inaccessible, DataLoss, Degraded.
스토리지 백엔드 상태 값(CSINode.status.storageHealth에 사용): StorageUnreachable, StorageDegraded.

노드 측 보고와 컨트롤러 측 보고는 독립적입니다. 한 노드가 백엔드로의 데이터 경로를 잃어 볼륨이 Inaccessible일 수 있지만, 컨트롤러 플러그인은 그 볼륨을 여전히 정상으로 보고할 수 있어요(그 반대도 마찬가지).

Pod에 보고되는 상태 (Health reported on Pods)

노드 측 NodeGetVolumeHealth RPC를 지원하는 CSI 드라이버를 사용하는 볼륨의 경우, kubelet은 Pod를 위해 마운트한 각 CSI 볼륨에 대해 그 RPC를 주기적으로 호출하고 결과를 pod.status.volumeHealth에 씁니다. pod.spec.volumes의 볼륨 이름으로 키가 지정됩니다. 조사 간격은 kubelet의 volumeStatsAggPeriod 설정(--volume-stats-agg-period 커맨드 라인 플래그)입니다.

apiVersion: v1
kind: Pod
# ...
status:
  volumeHealth:
  - name: my-volume
    healthConditions:
    - status: Inaccessible
      reason: VolumeNotFound
      message: "volume not found on the storage backend"
    lastTransitionTime: "2026-07-20T12:00:00Z"

kubelet은 자신의 노드에 바인딩된 Pod에 대해 이미 업데이트할 권한이 있는 하위 리소스인 pods/status만 씁니다. 따라서 이 필드에 대한 새 권한 부여는 필요하지 않습니다.

CSINode에 보고되는 상태 (Health reported on CSINode)

NodeGetStorageHealth를 지원하는 노드에 등록된 각 CSI 드라이버에 대해, kubelet은 그 RPC를 주기적으로 호출하고 결과를 csinode.status.storageHealth에 씁니다. 드라이버 이름으로 키가 지정됩니다.

apiVersion: storage.k8s.io/v1
kind: CSINode
# ...
status:
  storageHealth:
  - name: csi.example.com
    healthConditions:
    - status: StorageUnreachable
      reason: NetworkPartition
      message: "data path to the storage backend is unreachable from this node"

StorageHealthCondition 항목은 선택적으로 특정 accessMode나 volumeMode로 범위를 한정할 수 있어요. 비대칭적으로 성능이 저하되는 백엔드(예: ReadWriteOnce에는 영향을 주지 않으면서 ReadWriteMany 접근에는 영향을 주는 네트워크 문제)의 경우입니다.

csinodes/status 쓰기는 이 기능이 추가하는 새 캐퍼빌리티입니다. Node 권한 부여 모드와 NodeRestriction admission 플러그인은 kubelet이 자신의 노드와 일치하는 CSINode 객체만 패치할 수 있게 허용하며, CSIVolumeHealth 기능 게이트가 활성화된 동안에만 허용합니다.

PersistentVolumeClaim에 보고되는 상태 (Health reported on PersistentVolumeClaims)

컨트롤러가 관찰한 볼륨 상태는 CSI 드라이버의 컨트롤러 플러그인과 함께 실행되는 csi-external-health-monitor-controller 사이드카가 persistentvolumeclaim.status.healthStatus에 씁니다. 사이드카는 ControllerListVolumeHealth를 호출하고(또는 볼륨별로 ControllerGetVolumeHealth로 대체) 결과를 씁니다.

apiVersion: v1
kind: PersistentVolumeClaim
# ...
status:
  healthStatus:
    healthConditions:
    - status: Inaccessible
      reason: VolumeNotFound
      message: "volume not found on the storage backend"
    lastTransitionTime: "2026-07-20T12:00:00Z"

어떤 노드도 이 필드를 쓰지 않습니다. 컨트롤 플레인에서 실행되는 사이드카만 써요. 이는 손상되거나 오작동하는 노드가 클러스터의 다른 사용자가 PVC에서 보는 것에 영향을 줄 수 없게 합니다.

이 경로가 주어진 드라이버에 사용 가능한지 여부는 그 드라이버와, 그 csi-external-health-monitor-controller 사이드카 배포가 새 컨트롤러 RPC를 채택했는지에 달려 있습니다.