Skip to content

Commit

Permalink
Add Topology for Snapshot
Browse files Browse the repository at this point in the history 
This PR adds topology requirements for snapshots.
  • Loading branch information
@xing-yang
xing-yang committed Oct 15, 2018
1 parent 7c6a627 commit 0dbe605
Show file tree
Hide file tree
Showing 3 changed files with 701 additions and 500 deletions.
206 changes: 134 additions & 72 deletions csi.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,13 +130,21 @@ message PluginCapability {
// as specific RPCs as indicated by ControllerGetCapabilities.
CONTROLLER_SERVICE = 1;

// ACCESSIBILITY_CONSTRAINTS indicates that the volumes for this
// plugin may not be equally accessible by all nodes in the
// VOLUME_ACCESSIBILITY_CONSTRAINTS indicates that the volumes for
// this plugin may not be equally accessible by all nodes in the
// cluster. The CO MUST use the topology information returned by
// CreateVolumeRequest along with the topology information
// returned by NodeGetInfo to ensure that a given volume is
// accessible from a given node when scheduling workloads.
ACCESSIBILITY_CONSTRAINTS = 2;
VOLUME_ACCESSIBILITY_CONSTRAINTS = 2;

// SNAPSHOT_ACCESSIBILITY_CONSTRAINTS indicates that the snapshots
// for this plugin may not be equally accessible by all nodes in
// the cluster. The CO MUST use the topology information returned
// by CreateSnapshotRequest along with the topology information
// returned by NodeGetInfo to ensure that a given snapshot is
// accessible from a given node when scheduling workloads.
SNAPSHOT_ACCESSIBILITY_CONSTRAINTS = 3;
}
Type type = 1;
}
Expand Down Expand Up @@ -231,10 +239,10 @@ message CreateVolumeRequest {
// topological accessibility information supported by the SP.
// This field is OPTIONAL.
// This field SHALL NOT be specified unless the SP has the
// ACCESSIBILITY_CONSTRAINTS plugin capability.
// VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability.
// If this field is not specified and the SP has the
// ACCESSIBILITY_CONSTRAINTS plugin capability, the SP MAY choose
// where the provisioned volume is accessible from.
// VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability, the SP MAY
// choose where the provisioned volume is accessible from.
TopologyRequirement accessibility_requirements = 7;
}

Expand Down Expand Up @@ -368,7 +376,7 @@ message Volume {
// Specifies where (regions, zones, racks, etc.) the provisioned
// volume is accessible from.
// A plugin that returns this field MUST also set the
// ACCESSIBILITY_CONSTRAINTS plugin capability.
// VOLUME_ACCESSIBILITY_CONSTRAINTS plugin capability.
// An SP MAY specify multiple topologies to indicate the volume is
// accessible from multiple locations.
// COs MAY use this information along with the topology information
Expand All @@ -394,99 +402,109 @@ message Volume {
}

message TopologyRequirement {
// Specifies the list of topologies the provisioned volume MUST be
// accessible from.
// Specifies the list of topologies the provisioned volume or
// snapshot MUST be accessible from.
// This field is OPTIONAL. If TopologyRequirement is specified either
// requisite or preferred or both MUST be specified.
//
// If requisite is specified, the provisioned volume MUST be
// accessible from at least one of the requisite topologies.
// If requisite is specified, the provisioned volume or snapshot MUST
// be accessible from at least one of the requisite topologies.
//
// Given
// x = number of topologies provisioned volume is accessible from
// x = number of topologies provisioned volume or snapshot is
// accessible from
// n = number of requisite topologies
// The CO MUST ensure n >= 1. The SP MUST ensure x >= 1
// If x==n, than the SP MUST make the provisioned volume available to
// all topologies from the list of requisite topologies. If it is
// unable to do so, the SP MUST fail the CreateVolume call.
// For example, if a volume should be accessible from a single zone,
// and requisite =
// If x==n, than the SP MUST make the provisioned volume or snapshot
// available to all topologies from the list of requisite topologies.
// If it is unable to do so, the SP MUST fail the CreateVolume or
// CreateSnapshot call. For example, if a volume or snapshot should be
// accessible from a single zone, and
// requisite =
// {"region": "R1", "zone": "Z2"}
// then the provisioned volume MUST be accessible from the "region"
// "R1" and the "zone" "Z2".
// Similarly, if a volume should be accessible from two zones, and
// then the provisioned volume or snapshot MUST be accessible from
// the "region" "R1" and the "zone" "Z2".
// Similarly, if a volume or snapshot should be accessible from two
// zones, and
// requisite =
// {"region": "R1", "zone": "Z2"},
// {"region": "R1", "zone": "Z3"}
// then the provisioned volume MUST be accessible from the "region"
// "R1" and both "zone" "Z2" and "zone" "Z3".
// then the provisioned volume or snapshot MUST be accessible from the
// "region" "R1" and both "zone" "Z2" and "zone" "Z3".
//
// If x<n, than the SP SHALL choose x unique topologies from the list
// of requisite topologies. If it is unable to do so, the SP MUST fail
// the CreateVolume call.
// For example, if a volume should be accessible from a single zone,
// the CreateVolume or CreateSnapshot call.
// For example, if a volume or snapshot should be accessible from a
// single zone,
// and requisite =
// {"region": "R1", "zone": "Z2"},
// {"region": "R1", "zone": "Z3"}
// then the SP may choose to make the provisioned volume available in
// either the "zone" "Z2" or the "zone" "Z3" in the "region" "R1".
// Similarly, if a volume should be accessible from two zones, and
// then the SP may choose to make the provisioned volume or snapshot
// available in either the "zone" "Z2" or the "zone" "Z3" in the
// "region" "R1".
// Similarly, if a volume or snapshot should be accessible from two
// zones, and
// requisite =
// {"region": "R1", "zone": "Z2"},
// {"region": "R1", "zone": "Z3"},
// {"region": "R1", "zone": "Z4"}
// then the provisioned volume MUST be accessible from any combination
// of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or "R1/Z2" and
// "R1/Z4", or "R1/Z3" and "R1/Z4".
// then the provisioned volume or snapshot MUST be accessible from any
// combination of two unique topologies: e.g. "R1/Z2" and "R1/Z3", or
// "R1/Z2" and "R1/Z4", or "R1/Z3" and "R1/Z4".
//
// If x>n, than the SP MUST make the provisioned volume available from
// all topologies from the list of requisite topologies and MAY choose
// the remaining x-n unique topologies from the list of all possible
// topologies. If it is unable to do so, the SP MUST fail the
// CreateVolume call.
// For example, if a volume should be accessible from two zones, and
// If x>n, than the SP MUST make the provisioned volume or snapshot
// available from all topologies from the list of requisite topologies
// and MAY choose the remaining x-n unique topologies from the list of
// all possible topologies. If it is unable to do so, the SP MUST fail
// the CreateVolume or CreateSnapshot call.
// For example, if a volume or snapshot should be accessible from two
// zones, and
// requisite =
// {"region": "R1", "zone": "Z2"}
// then the provisioned volume MUST be accessible from the "region"
// "R1" and the "zone" "Z2" and the SP may select the second zone
// independently, e.g. "R1/Z4".
// then the provisioned volume or snapshot MUST be accessible from the
// "region" "R1" and the "zone" "Z2" and the SP may select the second
// zone independently, e.g. "R1/Z4".
repeated Topology requisite = 1;

// Specifies the list of topologies the CO would prefer the volume to
// be provisioned in.
// Specifies the list of topologies the CO would prefer the volume or
// snapshot to be provisioned in.
//
// This field is OPTIONAL. If TopologyRequirement is specified either
// requisite or preferred or both MUST be specified.
//
// An SP MUST attempt to make the provisioned volume available using
// the preferred topologies in order from first to last.
// An SP MUST attempt to make the provisioned volume or snapshot
// available using the preferred topologies in order from first to
// last.
//
// If requisite is specified, all topologies in preferred list MUST
// also be present in the list of requisite topologies.
//
// If the SP is unable to to make the provisioned volume available
// from any of the preferred topologies, the SP MAY choose a topology
// from the list of requisite topologies.
// If the SP is unable to to make the provisioned volume or snapshot
// available from any of the preferred topologies, the SP MAY choose
// a topology from the list of requisite topologies.
// If the list of requisite topologies is not specified, then the SP
// MAY choose from the list of all possible topologies.
// If the list of requisite topologies is specified and the SP is
// unable to to make the provisioned volume available from any of the
// requisite topologies it MUST fail the CreateVolume call.
// unable to to make the provisioned volume or snapshot available from
// any of the requisite topologies it MUST fail the CreateVolume or
// CreateSnapshot call.
//
// Example 1:
// Given a volume should be accessible from a single zone, and
// requisite =
// Given a volume or snapshot should be accessible from a single zone,
// and requisite =
// {"region": "R1", "zone": "Z2"},
// {"region": "R1", "zone": "Z3"}
// preferred =
// {"region": "R1", "zone": "Z3"}
// then the the SP SHOULD first attempt to make the provisioned volume
// available from "zone" "Z3" in the "region" "R1" and fall back to
// "zone" "Z2" in the "region" "R1" if that is not possible.
// or snapshot available from "zone" "Z3" in the "region" "R1" and
// fall back to "zone" "Z2" in the "region" "R1" if that is not
// possible.
//
// Example 2:
// Given a volume should be accessible from a single zone, and
// requisite =
// Given a volume or snapshot should be accessible from a single zone,
// and requisite =
// {"region": "R1", "zone": "Z2"},
// {"region": "R1", "zone": "Z3"},
// {"region": "R1", "zone": "Z4"},
Expand All @@ -495,17 +513,19 @@ message TopologyRequirement {
// {"region": "R1", "zone": "Z4"},
// {"region": "R1", "zone": "Z2"}
// then the the SP SHOULD first attempt to make the provisioned volume
// accessible from "zone" "Z4" in the "region" "R1" and fall back to
// "zone" "Z2" in the "region" "R1" if that is not possible. If that
// is not possible, the SP may choose between either the "zone"
// "Z3" or "Z5" in the "region" "R1".
// or snapshot accessible from "zone" "Z4" in the "region" "R1" and
// fall back to "zone" "Z2" in the "region" "R1" if that is not
// possible. If that is not possible, the SP may choose between either
// the "zone" "Z3" or "Z5" in the "region" "R1".
//
// Example 3:
// Given a volume should be accessible from TWO zones (because an
// opaque parameter in CreateVolumeRequest, for example, specifies
// the volume is accessible from two zones, aka synchronously
// replicated), and
// requisite =
// A volume or snapshot MAY be required to be accessible from TWO
// zones. This MAY be indicated by an opaque parameter in
// CreateVolumeRequest that specifies the volume to be accessible from
// two zones. While accessibility requirements MAY be satisfied by
// replication, CO MUST NOT assume accessibility requires replication.
// Given a volume or snapshot should be accessible from TWO zones,
// and requisite =
// {"region": "R1", "zone": "Z2"},
// {"region": "R1", "zone": "Z3"},
// {"region": "R1", "zone": "Z4"},
Expand All @@ -514,10 +534,10 @@ message TopologyRequirement {
// {"region": "R1", "zone": "Z5"},
// {"region": "R1", "zone": "Z3"}
// then the the SP SHOULD first attempt to make the provisioned volume
// accessible from the combination of the two "zones" "Z5" and "Z3" in
// the "region" "R1". If that's not possible, it should fall back to
// a combination of "Z5" and other possibilities from the list of
// requisite. If that's not possible, it should fall back to a
// or snapshot accessible from the combination of the two "zones" "Z5"
// and "Z3" in the "region" "R1". If that's not possible, it should
// fall back to a combination of "Z5" and other possibilities from the
// list of requisite. If that's not possible, it should fall back to a
// combination of "Z3" and other possibilities from the list of
// requisite. If that's not possible, it should fall back to a
// combination of other possibilities from the list of requisite.
Expand Down Expand Up @@ -642,7 +662,7 @@ message ValidateVolumeCapabilitiesRequest {
// A caller MAY specify multiple topologies to indicate they believe
// the volume to be accessible from multiple locations.
// This field is OPTIONAL. This field SHALL NOT be set unless the
// plugin advertises the ACCESSIBILITY_CONSTRAINTS capability.
// plugin advertises the VOLUME_ACCESSIBILITY_CONSTRAINTS capability.
repeated Topology accessible_topology = 4;
}

Expand Down Expand Up @@ -708,7 +728,7 @@ message GetCapacityRequest {
// `accessible_topology`. This is the same as the
// `accessible_topology` the CO returns in a `CreateVolumeResponse`.
// This field is OPTIONAL. This field SHALL NOT be set unless the
// plugin advertises the ACCESSIBILITY_CONSTRAINTS capability.
// plugin advertises the VOLUME_ACCESSIBILITY_CONSTRAINTS capability.
Topology accessible_topology = 3;
}

Expand Down Expand Up @@ -785,6 +805,19 @@ message CreateSnapshotRequest {
// - Specify primary or secondary for replication systems that
// support snapshotting only on primary.
map<string, string> parameters = 4;

// Specifies where (regions, zones, racks, etc.) the provisioned
// snapshot MUST be accessible from.
// An SP SHALL advertise the requirements for topological
// accessibility information in documentation. COs SHALL only specify
// topological accessibility information supported by the SP.
// This field is OPTIONAL.
// This field SHALL NOT be specified unless the SP has the
// SNAPSHOT_ACCESSIBILITY_CONSTRAINTS plugin capability.
// If this field is not specified and the SP has the
// SNAPSHOT_ACCESSIBILITY_CONSTRAINTS plugin capability, the SP MAY
// choose where the provisioned snapshot is accessible from.
TopologyRequirement accessibility_requirements = 5;
}

message CreateSnapshotResponse {
Expand Down Expand Up @@ -825,6 +858,33 @@ message Snapshot {

// The status of a snapshot.
SnapshotStatus status = 5;

// Specifies where (regions, zones, racks, etc.) the provisioned
// snapshot is accessible from.
// A plugin that returns this field MUST also set the
// SNAPSHOT_ACCESSIBILITY_CONSTRAINTS plugin capability.
// An SP MAY specify multiple topologies to indicate the snapshot is
// accessible from multiple locations.
// COs MAY use this information along with the topology information
// returned by NodeGetInfo to ensure that a given snapshot is
// accessible from a given node when scheduling workloads.
// This field is OPTIONAL. If it is not specified, the CO MAY assume
// the snapshot is equally accessible from all nodes in the cluster
// and may schedule workloads referencing the snapshot on any
// available node.
//
// Example 1:
// accessible_topology = {"region": "R1", "zone": "Z2"}
// Indicates a snapshot accessible only from the "region" "R1" and the
// "zone" "Z2".
//
// Example 2:
// accessible_topology =
// {"region": "R1", "zone": "Z2"},
// {"region": "R1", "zone": "Z3"}
// Indicates a snapshot accessible from both "zone" "Z2" and "zone"
// "Z3" in the "region" "R1".
repeated Topology accessible_topology = 6;
}

// The status of a snapshot.
Expand Down Expand Up @@ -1120,10 +1180,12 @@ message NodeGetInfoResponse {
// Specifies where (regions, zones, racks, etc.) the node is
// accessible from.
// A plugin that returns this field MUST also set the
// ACCESSIBILITY_CONSTRAINTS plugin capability.
// VOLUME_ACCESSIBILITY_CONSTRAINTS or
// SNAPSHOT_ACCESSIBILITY_CONSTRAINTS plugin capability.
// COs MAY use this information along with the topology information
// returned in CreateVolumeResponse to ensure that a given volume is
// accessible from a given node when scheduling workloads.
// returned in CreateVolumeResponse CreateSnapshotResponse to ensure
// that a given volume or snapshot is accessible from a given node
// when scheduling workloads.
// This field is OPTIONAL. If it is not specified, the CO MAY assume
// the node is not subject to any topological constraint, and MAY
// schedule workloads that reference any volume V, such that there are
Expand Down
Loading

0 comments on commit 0dbe605

Please sign in to comment.