Address CR feedback container-storage-interface#3

Author: saad-ali

csi.proto

@@ -367,7 +367,7 @@ message Volume {
   // volume is accessible from.
   // A plugin that returns this field MUST also set the
   // ACCESSIBILITY_CONSTRAINTS plugin capability.
-  // An SP may specify multiple topologies to indicate the volume is
+  // 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
   // returned by NodeGetInfo to ensure that a given volume is accessible
@@ -395,41 +395,41 @@ message TopologyRequirement {
   // Specifies the list of topologies the provisioned volume MUST be
   // accessible from.
   // This field is OPTIONAL. If TopologyRequirement is specified either
-  // permitted or preferred or both MUST be specified.
+  // requisite or preferred or both MUST be specified.
   // 
-  // If permitted is specified, the provisioned volume MUST be
-  // accessible from at least one of the permitted topologies.
+  // If requisite is specified, the provisioned volume MUST be
+  // accessible from at least one of the requisite topologies.
   // 
   // Given
   //   x = number of topologies provisioned volume is accessible from
-  //   n = number of permitted topologies
+  //   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 permitted topologies. If it is
+  // 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 permitted =
+  // 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
-  // permitted =
+  // 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".
   //
   // If x<n, than the SP SHALL choose x unique topologies from the list
-  // of permitted topologies. If it is unable to do so, the SP MUST fail
+  // 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 permitted =
+  // 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
-  // permitted =
+  // requisite =
   //   {"region": "R1", "zone": "Z2"},
   //   {"region": "R1", "zone": "Z3"},
   //   {"region": "R1", "zone": "Z4"}
@@ -438,42 +438,42 @@ message TopologyRequirement {
   //  "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 permitted topologies and MAY choose
+  // 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
-  // permitted =
+  // 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".
-  repeated Topology permitted = 1;
+  repeated Topology requisite = 1;
 
   // Specifies the list of topologies the CO would prefer the volume to
   // be provisioned in.
   //
   // This field is OPTIONAL. If TopologyRequirement is specified either
-  // permitted or preferred or both MUST be specified.
+  // 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.
   //
-  // If permitted is specified, all topologies in preferred volume MUST
-  // also be present in the list of permitted topologies.
+  // 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 permitted topologies.
-  // If the list of permitted topologies is not specified, then the SP
+  // 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 permitted topologies is specified and the SP is
+  // If the list of requisite topologies is specified and the SP is
   // unable to to make the provisioned volume available from any of the
-  // permitted topologies it MUST fail the CreateVolume call.
+  // requisite topologies it MUST fail the CreateVolume call.
   // 
   // Example 1:
   // Given a volume should be accessible from a single zone, and
-  // permitted =
+  // requisite =
   //   {"region": "R1", "zone": "Z2"},
   //   {"region": "R1", "zone": "Z3"}
   // preferred =
@@ -484,7 +484,7 @@ message TopologyRequirement {
   //
   // Example 2:
   // Given a volume should be accessible from a single zone, and
-  // permitted =
+  // requisite =
   //   {"region": "R1", "zone": "Z2"},
   //   {"region": "R1", "zone": "Z3"},
   //   {"region": "R1", "zone": "Z4"},
@@ -499,10 +499,11 @@ message TopologyRequirement {
   // "Z3" or "Z5" in the "region" "R1".
   //
   // Example 3:
-  // Given a volume should be accessible from TWO zones (because opaque
-  // parameter in CreateVolumeRequest, for example, specifies volume is
-  // accessible from two zones, aka synchronously replicated), and
-  // permitted =
+  // 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 =
   //   {"region": "R1", "zone": "Z2"},
   //   {"region": "R1", "zone": "Z3"},
   //   {"region": "R1", "zone": "Z4"},
@@ -514,10 +515,10 @@ message TopologyRequirement {
   // 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
-  // permitted. If that's not possible, it should fall back  to a
+  // requisite. If that's not possible, it should fall back  to a
   // combination of "Z3" and other possibilities from the list of
-  // permitted. If that's not possible, it should fall back  to a
-  // combination of other possibilities from the list of permitted.
+  // requisite. If that's not possible, it should fall back  to a
+  // combination of other possibilities from the list of requisite.
   repeated Topology preferred = 2;
 }
 
@@ -539,6 +540,8 @@ message TopologyRequirement {
 // The key prefix SHOULD include the plugin's host company name and/or
 // the plugin name, to minimize the possibility of collisions with keys
 // from other plugins.
+// If a key prefix is specified, it MUST be identical across all
+// topology keys returned by the SP (across all RPCs).
 // Keys MUST be case-insensitive. Meaning the keys "Zone" and "zone"
 // MUST not both exist.
 // Each value (topological segment) MUST contain 1 or more strings.
@@ -697,15 +700,14 @@ message GetCapacityRequest {
   // specific `parameters`. These are the same `parameters` the CO will
   // use in `CreateVolumeRequest`. This field is OPTIONAL.
   map<string, string> parameters = 2;
-  
+
   // If specified, the Plugin SHALL report the capacity of the storage
-  // that can be used to provision volumes that satisfy ALL of the
-  // specified `accessibility_requirements`. These are the same
-  // `accessibility_requirements` the CO will use in a
-  // `CreateVolumeRequest`.
+  // that can be used to provision volumes that in the specified
+  // `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.
-  TopologyRequirement accessibility_requirements = 7;
+  Topology accessible_topology = 3;
 }
 
 message GetCapacityResponse {