GetCapacityResponse: distinguish between maximum volume size and total available capacity

[pohly]

The current wording for the capacity field is:

The available capacity, in bytes, of the storage that can be used to provision volumes.
If volume_capabilities or parameters is specified in the request, the Plugin SHALL
take those into consideration when calculating the available capacity of the
storage.

This is vague because it does not explain what the capacity is supposed to be available for: is it for creating one volume, or multiple different volumes?

This becomes relevant for drivers that manage storage which can be fragmented. Once the underlying storage is fragmented, it might be possible to create one volume of size 100GiB and another volume of size 50GiB, but might not be possible to create one volume of 150GiB. Should the driver then report "maximum volume size" (= 100GiB) or "total available capacity" (= 150GiB)?

Considering that volume_capabilities or parameters are meant to have an effect, it seems that this call is meant to simulate the execution of a CreateVolume operation and thus is expected to return "maximum volume size". A CO can then compare that size against a volume size to determine in advance whether it makes sense to attempt the volume creation with these parameters and be more confident that this will actually work.

However, "total available capacity" is useful as a metric and can help with even workload spreading. The wording "provision volumes" (plural instead of singular) points in that direction.

Proposal:

• add wording that explains that capacity can be both "total available capacity" as well as "maximum volume size" but that drivers shall prefer "maximum volume size" (backwards-compatible clarification)
• introduce new, optional fields totalAvailableCapacity and maximumVolumeSize which avoid the ambiguity (also backwards-compatible because they are optional)

[pohly]

Note that this is orthogonal to adding "total capacity" (issue #301). This issue here is focused on just reporting free capacity.