Щоб скористатися цією функцією, вам (або адміністратору кластера) потрібно увімкнути функціональну можливість CSIVolumeHealth для всіх відповідних компонентів у вашому кластері.
Перегляньте Увімкнення або вимкнення функціональних можливостей для отримання додаткової інформації.
Моніторинг справності томів CSI дозволяє CSI драйверу повідомляти про проблеми зі справністю тому або його підлеглої системи збереження безпосередньо до Kubernetes. Драйвер повідомляє через CSI RPC, а Kubernetes виводить ці звіти у трьох полях статусу: PersistentVolumeClaim .status.healthStatus, Pod .status.volumeHealth та CSINode .status.storageHealth. Автоматизація може відстежувати ці довготривалі поля статусу замість необхідності відновлювати стан справності тому з ефемерних подій чи зі специфічних для постачальника панелей моніторингу.
CSIVolumeHealth існує ще з Kubernetes v1.21, але механізм, описаний на цій сторінці, є перепроєктуванням, яке замінює початкову альфа-реалізацію. Див. Обмеження, щоб дізнатися, що змінилося.Специфікація CSI визначає чотири RPC для звітування про стан справності:
ControllerListVolumeHealth та ControllerGetVolumeHealth, для спостережуваного контролером стану справності кожного тому.NodeGetVolumeHealth, для спостережуваного вузлом стану справності кожного тому, та NodeGetStorageHealth, для стану справності системи збереження як видно з цього вузла.Драйверу потрібно реалізувати лише ті RPC, які він хоче підтримувати, і він повідомляє про підтримку через можливості втулка CSI. Драйвер, який не реалізує жоден із цих RPC, ніколи не опитується, і звітування залишається неактивним для цього драйвера. Драйвер, який повідомляє про можливість контролера LIST_VOLUME_HEALTH, також повинен повідомляти про GET_VOLUME_HEALTH; sidecar csi-external-health-monitor-controller забезпечує виконання цієї вимоги.
Кожен звіт про стан справності містить status, взятий із невеликого набору значень, придатних для машинного аналізу, разом із визначеним драйвером reason та необовʼязковим зрозумілим людині message:
PersistentVolumeClaim.status.healthStatus та Pod.status.volumeHealth): Inaccessible, DataLoss, Degraded.CSINode.status.storageHealth): StorageUnreachable, StorageDegraded.Звіти зі сторони вузла та зі сторони контролера незалежні: том може бути Inaccessible з одного вузла, який втратив свій шлях доступу до даних системи збереження, тоді як втулок контролера все ще повідомляє про том як справний, і навпаки.
Для томів, які використовують драйвер CSI, що підтримує RPC NodeGetVolumeHealth зі сторони вузла, kubelet періодично викликає цей RPC для кожного тома CSI, який він змонтував для Podʼа, і записує результат у 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 записує лише pods/status, субресурс, який він уже авторизований оновлювати для Podʼів, привʼязаних до його власного вузла, тому для цього поля не потрібна нова авторизація.
Для кожного драйвера CSI, зареєстрованого на вузлі, який підтримує NodeGetStorageHealth, 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, для систем збереження, які деградують асиметрично (наприклад, мережева проблема, яка впливає на доступ ReadWriteMany, але не на ReadWriteOnce).
Запис у csinodes/status — це нова можливість, додана цією функцією: режим авторизації вузла та втулок допуску NodeRestriction дозволяють kubelet патчити лише обʼєкт CSINode, який відповідає його власному вузлу, і лише поки функціональну можливість CSIVolumeHealth увімкнено.
Спостережуваний контролером стан справності тому записується у persistentvolumeclaim.status.healthStatus через sidecar csi-external-health-monitor-controller, який запускається поряд із втулком контролера драйвера CSI. Sidecar викликає 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"
Жоден вузол ніколи не записує це поле; це робить лише sidecar csi-external-health-monitor-controller, що працює в панелі управління. Це не дозволяє скомпрометованому або неправильно працюючому вузлу впливати на те, що інші користувачі кластера бачать у PVC.
Чи доступний цей шлях для конкретного драйвера, залежить від того, чи цей драйвер та його розгортання sidecar csi-external-health-monitor-controller запровадили нові RPC контролера.
Моніторинг справності томів керується однією функціональною можливістю, CSIVolumeHealth, як на kube-apiserver, так і на kubelet:
kube-apiserver увімкнення функціональної можливості дозволяє записувати та читати нові поля статусу; вимкнення видаляє поля при наступному записі в обʼєкт, зберігаючи вже збережені значення.Моніторинг зі сторони контролера, який заповнює persistentvolumeclaim.status.healthStatus, не має власної функціональної можливості. Розгортання sidecar csi-external-health-monitor-controller поряд із втулком контролера вашого драйвера CSI саме по собі є згодою зі сторони контролера.
Увімкнення функціональної можливості саме по собі не призводить до появи будь-якої інформації про стан справності: драйвер CSI також повинен повідомляти та реалізовувати відповідні RPC. Перегляньте документацію вашого драйвера CSI, щоб дізнатися, які з чотирьох RPC, якщо такі є, він підтримує.
Kubelet надає метрику-датчик csi_node_storage_health_status, позначену мітками driver_name, status та reason, зі значенням 1 для кожного стану системи збереження, про який наразі повідомляється для драйвера на цьому вузлі.
CSIVolumeHealth (доступна починаючи з Kubernetes v1.21) повідомляла про ненормальні умови тому за допомогою Kubernetes Events та метрики kubelet_volume_stats_health_status_abnormal. Цей механізм було замінено полями статусу та RPC, описаними на цій сторінці, і його більше не існує.