Skip to content

Add volume health proposal #604

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
gnufied wants to merge 11 commits into
base: master
Choose a base branch
from
+3,608 −4,239
Open

Add volume health proposal #604

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
4c95ae9
Add volume health proposal
gnufied May 18, 2026
7241cd9
Update specs to introduce ControllerGetVolumeHealth
gnufied May 21, 2026
0d21f26
Update wording for repeated VolumeHealthEntry
gnufied May 26, 2026
2a7193d
Add new enum type for StorageBackendHealth
gnufied May 26, 2026
456214c
Make reason field required in CSI spec
gnufied May 28, 2026
ef549d3
Restore VolumeCondition
gnufied Jun 17, 2026
fd7f326
Update wording
gnufied Jun 22, 2026
15c0135
Rename STORAGE_HEALTH to GET_STORAGE_HEALTH
gnufied Jul 1, 2026
c026e41
Remove VolumeCondition feature
gnufied Jul 7, 2026
918d0b4
Move degraded to first position
gnufied Jul 7, 2026
85d1755
Make ControllerGetVolumeHealth required if LIST_VOLUME_HEALTH is impl…
gnufied Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
311 changes: 264 additions & 47 deletions csi.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,16 @@ service Controller {
rpc ListVolumes (ListVolumesRequest)
returns (ListVolumesResponse) {}

rpc ControllerListVolumeHealth (ControllerListVolumeHealthRequest)
returns (ControllerListVolumeHealthResponse) {
option (alpha_method) = true;
}

rpc ControllerGetVolumeHealth (ControllerGetVolumeHealthRequest)
returns (ControllerGetVolumeHealthResponse) {
option (alpha_method) = true;
}

rpc GetCapacity (GetCapacityRequest)
returns (GetCapacityResponse) {}

Expand Down Expand Up @@ -157,6 +167,15 @@ service Node {
rpc NodeGetVolumeStats (NodeGetVolumeStatsRequest)
returns (NodeGetVolumeStatsResponse) {}

rpc NodeGetVolumeHealth (NodeGetVolumeHealthRequest)
returns (NodeGetVolumeHealthResponse) {
option (alpha_method) = true;
}

rpc NodeGetStorageHealth (NodeGetStorageHealthRequest)
returns (NodeGetStorageHealthResponse) {
option (alpha_method) = true;
}

rpc NodeExpandVolume(NodeExpandVolumeRequest)
returns (NodeExpandVolumeResponse) {}
Expand Down Expand Up @@ -958,11 +977,7 @@ message ListVolumesResponse {
// reported by the SP. The CO MUST be resilient to that.
repeated string published_node_ids = 1;

// Information about the current condition of the volume.
// This field is OPTIONAL.
// This field MUST be specified if the
// VOLUME_CONDITION controller capability is supported.
VolumeCondition volume_condition = 2 [(alpha_field) = true];
reserved 2;
}

message Entry {
Expand All @@ -985,6 +1000,140 @@ message ListVolumesResponse {
// An empty string is equal to an unspecified field value.
string next_token = 2;
}
message ControllerListVolumeHealthRequest {
option (alpha_message) = true;

// If specified (non-zero value), the Plugin MUST NOT return more
// entries than this number in the response. If the actual number of
// entries is more than this number, the Plugin MUST set `next_token`
// in the response which can be used to get the next page of entries
// in the subsequent `ControllerListVolumeHealth` call. This field is
// OPTIONAL. If not specified (zero value), it means there is no
// restriction on the number of entries that can be returned.
// The value of this field MUST NOT be negative.
int32 max_entries = 1;

// A token to specify where to start paginating. Set this field to
// `next_token` returned by a previous `ControllerListVolumeHealth`
// call to get the next page of entries. This field is OPTIONAL.
// An empty string is equal to an unspecified field value.
string starting_token = 2;

// Secrets required by plugin to complete the request.
// This field is OPTIONAL. Refer to the `Secrets Requirements`
// section on how to use this field.
map<string, string> secrets = 3 [(csi_secret) = true];
}

message ControllerListVolumeHealthResponse {
option (alpha_message) = true;

// List of abnormal volume health entries.
repeated VolumeHealth entries = 1;

// This token allows you to get the next page of entries for
// `ControllerListVolumeHealth` request. If the number of entries is
// larger than `max_entries`, use the `next_token` as a value for the
// `starting_token` field in the next request. This field is
// OPTIONAL.
// An empty string is equal to an unspecified field value.
string next_token = 2;
}

enum VolumeHealthErrorType {
UNKNOWN_VOLUME_HEALTH_TYPE = 0;

// The volume is usable but is not operating optimally.
DEGRADED = 1;

// The volume is not accessible.
// When a volume is reported as INACCESSIBLE in
// ControllerListVolumeHealth or ControllerGetVolumeHealth
// RPC calls, the CO MAY interpret the result as
// volume not being accessible from all nodes in the cluster.
//
// When a volume is reported as INACCESSIBLE in NodeGetVolumeHealth
// RPC call the CO MAY interpret the result as volume not
// being accessible from that node.
INACCESSIBLE = 2;

// Data loss is known or strongly suspected on underlying volume.
DATA_LOSS = 3;
}

message VolumeHealth {
option (alpha_message) = true;

message VolumeHealthEntry {
// One or more health status values associated with the volume.
// Adverse health conditions should only be removed from reporting
// when the corresponding health problem is no longer happening.
// This field is REQUIRED.
VolumeHealthErrorType status = 1;

// A brief CamelCase string that describes the condition and is
// suitable for machine parsing and concise CLI display.
// The Plugin MUST NOT return multiple VolumeHealthEntry messages
// for the same volume with the same (status, reason) combination.
// This field is REQUIRED.
string reason = 2;

// A user friendly description of the volume health condition.
// This field is OPTIONAL.
string message = 3;
}

// The ID of the volume.
// This field is REQUIRED.
string volume_id = 1;

// Health statuses associated with the volume. An empty list means no
// adverse health condition is known by the Plugin.
//
// The SP MAY report one or more health issues with the volume at the
// same time. A future version of the CSI spec MAY introduce
// additional VolumeHealthErrorType values. A Plugin that adopts a
// newer spec version MAY report newer error types alongside existing
// ones, but MUST NOT remove an older error entry from
// health_statuses until that condition is no longer present.
//
// COs MAY ignore unknown VolumeHealthErrorType values, that they
// don't know about.
//
// For example:
// - CSI spec v1.12.3
// A Plugin reports an adverse health condition as DEGRADED.
// - CSI spec v1.12.5
// A new VolumeHealthErrorType value MULTIPATH_LOSS is introduced.
// The Plugin upgrades and now reports [DEGRADED, MULTIPATH_LOSS]
// for this volume. An older CO that does not recognize
// MULTIPATH_LOSS still acts on DEGRADED as before and surfaces
// the unknown value for observability without taking automated
// action on it.
//
// This field is OPTIONAL.
repeated VolumeHealthEntry health_statuses = 2;
}
message ControllerGetVolumeHealthRequest {
option (alpha_message) = true;

// The ID of the volume to fetch health information for.
// This field is REQUIRED.
string volume_id = 1;

// Secrets required by plugin to complete the request.
// This field is OPTIONAL. Refer to the `Secrets Requirements`
// section on how to use this field.
map<string, string> secrets = 2 [(csi_secret) = true];
}

message ControllerGetVolumeHealthResponse {
option (alpha_message) = true;

// The health information for the requested volume.
// This field is REQUIRED.
VolumeHealth volume_health = 1;
}
message ControllerGetVolumeRequest {
option (alpha_message) = true;

Expand All @@ -1006,11 +1155,7 @@ message ControllerGetVolumeResponse {
// reported by the SP. The CO MUST be resilient to that.
repeated string published_node_ids = 1;

// Information about the current condition of the volume.
// This field is OPTIONAL.
// This field MUST be specified if the
// VOLUME_CONDITION controller capability is supported.
VolumeCondition volume_condition = 2;
reserved 2;
}

// This field is REQUIRED
Expand Down Expand Up @@ -1155,22 +1300,11 @@ message ControllerServiceCapability {
// The SP MUST also support PUBLISH_UNPUBLISH_VOLUME.
LIST_VOLUMES_PUBLISHED_NODES = 10;

// Indicates that the Controller service can report volume
// conditions.
// An SP MAY implement `VolumeCondition` in only the Controller
// Plugin, only the Node Plugin, or both.
// If `VolumeCondition` is implemented in both the Controller and
// Node Plugins, it SHALL report from different perspectives.
// If for some reason Controller and Node Plugins report
// misaligned volume conditions, CO SHALL assume the worst case
// is the truth.
// Note that, for alpha, `VolumeCondition` is intended be
// informative for humans only, not for automation.
VOLUME_CONDITION = 11 [(alpha_enum_value) = true];
reserved 11;

// Indicates the SP supports the ControllerGetVolume RPC.
// This enables COs to, for example, fetch per volume
// condition after a volume is provisioned.
// information after a volume is provisioned.
GET_VOLUME = 12 [(alpha_enum_value) = true];

// Indicates the SP supports the SINGLE_NODE_SINGLE_WRITER and/or
Expand All @@ -1190,6 +1324,18 @@ message ControllerServiceCapability {
// Indicates the SP supports the GetSnapshot RPC.
// This enables COs to fetch an existing snapshot.
GET_SNAPSHOT = 15 [(alpha_enum_value) = true];

// Indicates the SP supports the ControllerListVolumeHealth RPC.
// This enables COs to fetch volume health information from
// the Controller Plugin's perspective.
// A SP that supports ControllerListVolumeHealth MUST also
// support ControllerGetVolumeHealth.
LIST_VOLUME_HEALTH = 16 [(alpha_enum_value) = true];

// Indicates the SP supports the ControllerGetVolumeHealth RPC.
// This enables COs to fetch health information for a single
// volume from the Controller Plugin's perspective.
GET_VOLUME_HEALTH = 17 [(alpha_enum_value) = true];
}

Type type = 1;
Expand Down Expand Up @@ -1580,11 +1726,8 @@ message NodeGetVolumeStatsRequest {
message NodeGetVolumeStatsResponse {
// This field is OPTIONAL.
repeated VolumeUsage usage = 1;
// Information about the current condition of the volume.
// This field is OPTIONAL.
// This field MUST be specified if the VOLUME_CONDITION node
// capability is supported.
VolumeCondition volume_condition = 2 [(alpha_field) = true];

reserved 2;
}

message VolumeUsage {
Expand All @@ -1609,18 +1752,92 @@ message VolumeUsage {
Unit unit = 4;
}

// VolumeCondition represents the current condition of a volume.
message VolumeCondition {
message NodeGetVolumeHealthRequest {
option (alpha_message) = true;

// Normal volumes are available for use and operating optimally.
// An abnormal volume does not meet these criteria.
// The ID of the volume.
// This field is REQUIRED.
bool abnormal = 1;
string volume_id = 1;

// The path where the volume is or was expected to be
// published on the node. If not empty, it MUST be an absolute path
// in the root filesystem of the process serving this request.
// This field is OPTIONAL.
// This field overrides the general CSI size limit.
// SP SHOULD support the maximum path length allowed by the operating
// system/filesystem, but, at a minimum, SP MUST accept a max path
// length of at least 128 bytes.
string volume_publish_path = 2;

// The path where the volume is or was staged, if the plugin has the
// STAGE_UNSTAGE_VOLUME capability, otherwise empty.
// If not empty, it MUST be an absolute path in the root
// filesystem of the process serving this request.
// This field is OPTIONAL.
// This field overrides the general CSI size limit.
// SP SHOULD support the maximum path length allowed by the operating
// system/filesystem, but, at a minimum, SP MUST accept a max path
// length of at least 128 bytes.
string staging_target_path = 3;
}

message NodeGetVolumeHealthResponse {
option (alpha_message) = true;

// The message describing the condition of the volume.
// The health information for the requested volume.
// This field is REQUIRED.
string message = 2;
VolumeHealth volume_health = 1;
}
message NodeGetStorageHealthRequest {
option (alpha_message) = true;

// Secrets required by the plugin to complete the request.
// This field is OPTIONAL. Refer to the `Secrets Requirements`
// section on how to use this field.
map<string, string> secrets = 1 [(csi_secret) = true];
}

message NodeGetStorageHealthResponse {
option (alpha_message) = true;

message StorageBackendHealth {
// Health status for this storage backend.
// This field is REQUIRED.
StorageHealthErrorType status = 1;

// A brief CamelCase string that describes the condition and is
// suitable for machine parsing and concise CLI display.
// The Plugin MUST NOT return multiple StorageBackendHealth messages
// with the same (status, reason, volume_capability) combination.
// This field is REQUIRED.
string reason = 2;

// A user friendly description of the storage health condition.
// This field is OPTIONAL.
string message = 3;

// Volume capability affected by this storage health condition.
// This field is OPTIONAL.
VolumeCapability volume_capability = 4;
}

// Health information for storage backends or classes available from
// this node.
// This field is OPTIONAL.
repeated StorageBackendHealth backend_health = 1;
}

enum StorageHealthErrorType {
UNKNOWN_STORAGE_HEALTH_ERROR_TYPE = 0;

// The storage backend is completely unreachable from this node.
// Volumes using this backend are expected to be unavailable.
STORAGE_UNREACHABLE = 1;

// The storage backend is operating in a degraded
// state (e.g. reduced path count, high latency).
// Volumes using this backend may experience reduced performance.
STORAGE_DEGRADED = 2;
}
message NodeGetCapabilitiesRequest {
// Intentionally empty.
Expand All @@ -1644,18 +1861,8 @@ message NodeServiceCapability {
GET_VOLUME_STATS = 2;
// See VolumeExpansion for details.
EXPAND_VOLUME = 3;
// Indicates that the Node service can report volume conditions.
// An SP MAY implement `VolumeCondition` in only the Node
// Plugin, only the Controller Plugin, or both.
// If `VolumeCondition` is implemented in both the Node and
// Controller Plugins, it SHALL report from different
// perspectives.
// If for some reason Node and Controller Plugins report
// misaligned volume conditions, CO SHALL assume the worst case
// is the truth.
// Note that, for alpha, `VolumeCondition` is intended to be
// informative for humans only, not for automation.
VOLUME_CONDITION = 4 [(alpha_enum_value) = true];

reserved 4;

// Indicates the SP supports the SINGLE_NODE_SINGLE_WRITER and/or
// SINGLE_NODE_MULTI_WRITER access modes.
Expand All @@ -1672,6 +1879,16 @@ message NodeServiceCapability {
// with provided volume group identifier during node stage
// or node publish RPC calls.
VOLUME_MOUNT_GROUP = 6;

// Indicates the SP supports the NodeGetVolumeHealth RPC.
// This enables COs to fetch per-volume health information from
// the Node Plugin's perspective.
GET_VOLUME_HEALTH = 7 [(alpha_enum_value) = true];

// Indicates the SP supports the NodeGetStorageHealth RPC.
// This enables COs to fetch health of entire storage subsystem
// from node's perspective.
GET_STORAGE_HEALTH = 8 [(alpha_enum_value) = true];
}

Type type = 1;
Expand Down
Loading
Loading