Skip to content

{WIP} 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 2 commits into
base: master
Choose a base branch
from
Open

{WIP} Add volume health proposal #604

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 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
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
262 changes: 214 additions & 48 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 @@ -946,6 +965,8 @@ message ListVolumesRequest {

message ListVolumesResponse {
message VolumeStatus{
reserved 2;

// A list of all `node_id` of nodes that the volume in this entry
// is controller published on.
// This field is OPTIONAL. If it is not specified and the SP has
Expand All @@ -958,11 +979,6 @@ 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];
}

message Entry {
Expand All @@ -985,6 +1001,115 @@ 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;

message Entry {
// This field is REQUIRED.
VolumeHealth volume_health = 1;
}

repeated Entry 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 VolumeHealthType {
UNKNOWN_VOLUME_HEALTH_TYPE = 0;

// The volume is not accessible.
INACCESSIBLE = 1;

// Data loss is known or strongly suspected.
DATA_LOSS = 2;

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

// The volume is available for use and operating optimally.
OK = 4;
}

message VolumeHealth {
option (alpha_message) = true;

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

// A brief CamelCase string that describes the condition and is
// suitable for machine parsing and concise CLI display.
// This field is OPTIONAL.
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.
// 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 @@ -997,6 +1122,8 @@ message ControllerGetVolumeResponse {
option (alpha_message) = true;

message VolumeStatus{
reserved 2;

// A list of all the `node_id` of nodes that this volume is
// controller published on.
// This field is OPTIONAL.
Expand All @@ -1006,11 +1133,6 @@ 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;
}

// This field is REQUIRED
Expand Down Expand Up @@ -1124,6 +1246,8 @@ message ControllerGetCapabilitiesResponse {
message ControllerServiceCapability {
message RPC {
enum Type {
reserved 11;

UNKNOWN = 0;
CREATE_DELETE_VOLUME = 1;
PUBLISH_UNPUBLISH_VOLUME = 2;
Expand Down Expand Up @@ -1155,22 +1279,9 @@ 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];

// 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 +1301,16 @@ 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.
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 @@ -1578,13 +1699,10 @@ message NodeGetVolumeStatsRequest {
}

message NodeGetVolumeStatsResponse {
reserved 2;

// 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];
}

message VolumeUsage {
Expand All @@ -1609,18 +1727,66 @@ 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 message describing the condition of the volume.
// The path where the volume is or was expected to be staged or
// 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_path = 2;
}

message NodeGetVolumeHealthResponse {
option (alpha_message) = true;

// 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 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 or class.
// This field is REQUIRED.
VolumeHealthType status = 1;

// A brief CamelCase string that describes the condition and is
// suitable for machine parsing and concise CLI display.
// This field is OPTIONAL.
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;
}
message NodeGetCapabilitiesRequest {
// Intentionally empty.
Expand All @@ -1636,6 +1802,8 @@ message NodeGetCapabilitiesResponse {
message NodeServiceCapability {
message RPC {
enum Type {
reserved 4;

UNKNOWN = 0;
STAGE_UNSTAGE_VOLUME = 1;
// If Plugin implements GET_VOLUME_STATS capability
Expand All @@ -1644,18 +1812,6 @@ 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];

// Indicates the SP supports the SINGLE_NODE_SINGLE_WRITER and/or
// SINGLE_NODE_MULTI_WRITER access modes.
Expand All @@ -1672,6 +1828,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.
VOLUME_HEALTH = 7 [(alpha_enum_value) = true];

// Indicates the SP supports the NodeGetStorageHealth RPC.
// This enables COs to fetch node-local storage health
// information that can affect one or more volumes.
STORAGE_HEALTH = 8 [(alpha_enum_value) = true];
}

Type type = 1;
Expand Down
Loading
Loading