Merge pull request #322 from saad-ali/clarifyCreateVolumeError

Clarify `CreateVolume` idepotent recovery behavior

Author: saad-ali

csi.proto

@@ -173,14 +173,21 @@ message CreateVolumeRequest {
   // The suggested name for the storage space. This field is REQUIRED.
   // It serves two purposes:
   // 1) Idempotency - This name is generated by the CO to achieve
-  //    idempotency. If `CreateVolume` fails, the volume may or may not
-  //    be provisioned. In this case, the CO may call `CreateVolume`
-  //    again, with the same name, to ensure the volume exists. The
-  //    Plugin should ensure that multiple `CreateVolume` calls for the
-  //    same name do not result in more than one piece of storage
-  //    provisioned corresponding to that name. If a Plugin is unable to
-  //    enforce idempotency, the CO's error recovery logic could result
-  //    in multiple (unused) volumes being provisioned.
+  //    idempotency.  The Plugin should ensure that multiple
+  //    `CreateVolume` calls for the same name do not result in more
+  //    than one piece of storage provisioned corresponding to that
+  //    name. If a Plugin is unable to enforce idempotency, the CO's
+  //    error recovery logic could result in multiple (unused) volumes
+  //    being provisioned.
+  //    In the case of error, the CO MUST handle the gRPC error codes
+  //    per the recovery behavior defined in the "CreateVolume Errors"
+  //    section below.
+  //    The CO is responsible for cleaning up volumes it provisioned
+  //    that it no longer needs. If the CO is uncertain whether a volume
+  //    was provisioned or not when a `CreateVolume` call fails, the CO
+  //    MAY call `CreateVolume` again, with the same name, to ensure the
+  //    volume exists and to retrieve the volume's `volume_id` (unless
+  //    otherwise prohibited by "CreateVolume Errors").
   // 2) Suggested name - Some storage systems allow callers to specify
   //    an identifier by which to refer to the newly provisioned
   //    storage. If a storage system supports this, it can optionally