Skip to content

Commit

Permalink
Added the SnapshotMetadata service. (#551)
Browse files Browse the repository at this point in the history
  • Loading branch information
carlbraganza authored Mar 14, 2024
1 parent abf6346 commit 2696773
Show file tree
Hide file tree
Showing 4 changed files with 2,920 additions and 1,602 deletions.
188 changes: 188 additions & 0 deletions csi.proto
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,16 @@ service GroupController {
}
}

service SnapshotMetadata {
option (alpha_service) = true;

rpc GetMetadataAllocated(GetMetadataAllocatedRequest)
returns (stream GetMetadataAllocatedResponse) {}

rpc GetMetadataDelta(GetMetadataDeltaRequest)
returns (stream GetMetadataDeltaResponse) {}
}

service Node {
rpc NodeStageVolume (NodeStageVolumeRequest)
returns (NodeStageVolumeResponse) {}
Expand Down Expand Up @@ -220,6 +230,14 @@ message PluginCapability {
// well as specific RPCs as indicated by
// GroupControllerGetCapabilities.
GROUP_CONTROLLER_SERVICE = 3 [(alpha_enum_value) = true];

// SNAPSHOT_METADATA_SERVICE indicates that the Plugin provides
// RPCs to retrieve metadata on the allocated blocks of a single
// snapshot, or the changed blocks between a pair of snapshots of
// the same block volume.
// The presence of this capability determines whether the CO will
// attempt to invoke the OPTIONAL SnapshotMetadata service RPCs.
SNAPSHOT_METADATA_SERVICE = 4 [(alpha_enum_value) = true];
}
Type type = 1;
}
Expand Down Expand Up @@ -1913,3 +1931,173 @@ message GetVolumeGroupSnapshotResponse {
// This field is REQUIRED
VolumeGroupSnapshot group_snapshot = 1;
}
// BlockMetadata specifies a data range.
message BlockMetadata {
// This is the zero based byte position in the volume or snapshot,
// measured from the start of the object.
// This field is REQUIRED.
int64 byte_offset = 1;

// This is the size of the data range.
// size_bytes MUST be greater than zero.
// This field is REQUIRED.
int64 size_bytes = 2;
}
enum BlockMetadataType {
UNKNOWN = 0;

// The FIXED_LENGTH value indicates that data ranges are
// returned in fixed size blocks.
FIXED_LENGTH = 1;

// The VARIABLE_LENGTH value indicates that data ranges
// are returned in potentially variable sized extents.
VARIABLE_LENGTH = 2;
}
// The GetMetadataAllocatedRequest message is used to solicit metadata
// on the allocated blocks of a snapshot: i.e. this identifies the
// data ranges that have valid data as they were the target of some
// previous write operation on the volume.
message GetMetadataAllocatedRequest {
// This is the identifier of the snapshot.
// This field is REQUIRED.
string snapshot_id = 1;

// This indicates the zero based starting byte position in the volume
// snapshot from which the result should be computed.
// It is intended to be used to continue a previously interrupted
// call.
// The CO SHOULD specify this value to be the offset of the byte
// position immediately after the last byte of the last data range
// received, if continuing an interrupted operation, or zero if not.
// The SP MUST ensure that the returned response stream does not
// contain BlockMetadata tuples that end before the requested
// starting_offset: i.e. if S is the requested starting_offset, and
// B0 is block_metadata[0] of the first message in the response
// stream, then (S < B0.byte_offset + B0.size_bytes) must be true.
// This field is REQUIRED.
int64 starting_offset = 2;

// This is an optional parameter, and if non-zero it specifies the
// maximum number of tuples to be returned in each
// GetMetadataAllocatedResponse message returned by the RPC stream.
// The plugin will determine an appropriate value if 0, and is
// always free to send less than the requested value.
// This field is OPTIONAL.
int32 max_results = 3;

// 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 = 4 [(csi_secret) = true];
}

// GetMetadataAllocatedResponse messages are returned in a gRPC stream.
// Cumulatively, they provide information on the allocated data
// ranges in the snapshot.
message GetMetadataAllocatedResponse {
// This specifies the style used in the BlockMetadata sequence.
// This value must be the same in all such messages returned by
// the stream.
// If block_metadata_type is FIXED_LENGTH, then the size_bytes field
// of each message in the block_metadata list MUST be constant.
// This field is REQUIRED.
BlockMetadataType block_metadata_type = 1;

// This returns the capacity of the underlying volume in bytes.
// This value must be the same in all such messages returned by
// the stream.
// This field is REQUIRED.
int64 volume_capacity_bytes = 2;

// This is a list of data range tuples.
// If the value of max_results in the GetMetadataAllocatedRequest
// message is greater than zero, then the number of entries in this
// list MUST be less than or equal to that value.
// The SP MUST respect the value of starting_offset in the request.
// The byte_offset fields of adjacent BlockMetadata messages
// MUST be strictly increasing and messages MUST NOT overlap:
// i.e. for any two BlockMetadata messages, A and B, if A is returned
// before B, then (A.byte_offset + A.size_bytes <= B.byte_offset)
// MUST be true.
// This MUST also be true if A and B are from block_metadata lists in
// different GetMetadataAllocatedResponse messages in the gRPC stream.
// This field is OPTIONAL.
repeated BlockMetadata block_metadata = 3;
}
// The GetMetadataDeltaRequest message is used to solicit metadata on
// the data ranges that have changed between two snapshots.
message GetMetadataDeltaRequest {
// This is the identifier of the snapshot against which changes
// are to be computed.
// This field is REQUIRED.
string base_snapshot_id = 1;

// This is the identifier of a second snapshot in the same volume,
// created after the base snapshot.
// This field is REQUIRED.
string target_snapshot_id = 2;

// This indicates the zero based starting byte position in the volume
// snapshot from which the result should be computed.
// It is intended to be used to continue a previously interrupted
// call.
// The CO SHOULD specify this value to be the offset of the byte
// position immediately after the last byte of the last data range
// received, if continuing an interrupted operation, or zero if not.
// The SP MUST ensure that the returned response stream does not
// contain BlockMetadata tuples that end before the requested
// starting_offset: i.e. if S is the requested starting_offset, and
// B0 is block_metadata[0] of the first message in the response
// stream, then (S < B0.byte_offset + B0.size_bytes) must be true.
// This field is REQUIRED.
int64 starting_offset = 3;

// This is an optional parameter, and if non-zero it specifies the
// maximum number of tuples to be returned in each
// GetMetadataDeltaResponse message returned by the RPC stream.
// The plugin will determine an appropriate value if 0, and is
// always free to send less than the requested value.
// This field is OPTIONAL.
int32 max_results = 4;

// 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 = 5 [(csi_secret) = true];
}

// GetMetadataDeltaResponse messages are returned in a gRPC stream.
// Cumulatively, they provide information on the data ranges that
// have changed between the base and target snapshots specified
// in the GetMetadataDeltaRequest message.
message GetMetadataDeltaResponse {
// This specifies the style used in the BlockMetadata sequence.
// This value must be the same in all such messages returned by
// the stream.
// If block_metadata_type is FIXED_LENGTH, then the size_bytes field
// of each message in the block_metadata list MUST be constant.
// This field is REQUIRED.
BlockMetadataType block_metadata_type = 1;

// This returns the capacity of the underlying volume in bytes.
// This value must be the same in all such messages returned by
// the stream.
// This field is REQUIRED.
int64 volume_capacity_bytes = 2;

// This is a list of data range tuples.
// If the value of max_results in the GetMetadataDeltaRequest message
// is greater than zero, then the number of entries in this list MUST
// be less than or equal to that value.
// The SP MUST respect the value of starting_offset in the request.
// The byte_offset fields of adjacent BlockMetadata messages
// MUST be strictly increasing and messages MUST NOT overlap:
// i.e. for any two BlockMetadata messages, A and B, if A is returned
// before B, then (A.byte_offset + A.size_bytes <= B.byte_offset)
// MUST be true.
// This MUST also be true if A and B are from block_metadata lists in
// different GetMetadataDeltaResponse messages in the gRPC stream.
// This field is OPTIONAL.
repeated BlockMetadata block_metadata = 3;
}
Loading

0 comments on commit 2696773

Please sign in to comment.