Add Topology for Snapshot

This PR adds topology requirements for snapshots.

Author: xing-yang

csi.proto

@@ -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;
   }
@@ -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;
 }
 
@@ -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
@@ -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"},
@@ -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"},
@@ -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.
@@ -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;
 }
 
@@ -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;
 }
 
@@ -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 {
@@ -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.
@@ -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