From e9e11ccc45cd3e7a3adafcaed611657e0b028073 Mon Sep 17 00:00:00 2001 From: Jan Safranek Date: Mon, 21 Sep 2020 11:33:58 +0200 Subject: [PATCH 1/2] Clarify content of cloned / restored volumes When cloning a volume or restoring a snapshot, the resulting volume should be exact copy of the original volume. This includes any filesystem metadata. Therefore, when the new volume is larger than the original one, the new volume may need to resize the filesystem (ie call resize2fs, xfs_growfs, ...) to make the bigger capacity available to workloads. --- spec.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 7773dde1..430cd796 100644 --- a/spec.md +++ b/spec.md @@ -725,7 +725,13 @@ Plugins MAY create 3 types of volumes: - Empty volumes. When plugin supports `CREATE_DELETE_VOLUME` OPTIONAL capability. - From an existing snapshot. When plugin supports `CREATE_DELETE_VOLUME` and `CREATE_DELETE_SNAPSHOT` OPTIONAL capabilities. + The Plugin SHOULD create a volume that looks like exact copy of the original snapshotted volume at the time the snapshot was taken. + If CO requests a volume that is larger than the original snapshotted volume, the Plugin can either refuse such a call with `OUT_OF_RANGE` error or SHOULD provide a volume that, when presented to a workload by `NodePublish` call, has both the requested (larger) size and contains data from the snapshot. + Explicitly, it's responsibility of the Plugin to resize the filesystem of the volume at or before `NodePublish` call, if the volume has `VolumeCapability` `MountVolume` and the filesystem resize is required to have the larger volume usable by the workload. - From an existing volume. When plugin supports cloning, and reports the OPTIONAL capabilities `CREATE_DELETE_VOLUME` and `CLONE_VOLUME`. + The Plugin SHOULD create a volume that looks like exact copy of the original volume. + If CO requests a volume that is larger than the original volume, the Plugin can either refuse such a call with `OUT_OF_RANGE` error or SHOULD provide a volume that, when presented to a workload by `NodePublish` call, has both the requested (larger) size and contains data from the original volume. + Explicitly, it's responsibility of the Plugin to resize the filesystem of the volume at or before `NodePublish` call, if the volume has `VolumeCapability` `MountVolume` and the filesystem resize is required to have the larger volume usable by the workload. ```protobuf message CreateVolumeRequest { @@ -1161,7 +1167,7 @@ The CO MUST implement the specified error recovery behavior when it encounters t | Source does not exist | 5 NOT_FOUND | Indicates that the specified source does not exist. | Caller MUST verify that the `volume_content_source` is correct, the source is accessible, and has not been deleted before retrying with exponential back off. | | Volume already exists but is incompatible | 6 ALREADY_EXISTS | Indicates that a volume corresponding to the specified volume `name` already exists but is incompatible with the specified `capacity_range`, `volume_capabilities`, `parameters`, `accessibility_requirements` or `volume_content_source`. | Caller MUST fix the arguments or use a different `name` before retrying. | | Unable to provision in `accessible_topology` | 8 RESOURCE_EXHAUSTED | Indicates that although the `accessible_topology` field is valid, a new volume can not be provisioned with the specified topology constraints. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST ensure that whatever is preventing volumes from being provisioned in the specified location (e.g. quota issues) is addressed before retrying with exponential backoff. | -| Unsupported `capacity_range` | 11 OUT_OF_RANGE | Indicates that the capacity range is not allowed by the Plugin, for example when trying to create a volume smaller than the source snapshot. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST fix the capacity range before retrying. | +| Unsupported `capacity_range` | 11 OUT_OF_RANGE | Indicates that the capacity range is not allowed by the Plugin, for example when trying to create a volume smaller than the source snapshot or the Plugin does not support creating volumes larger than the source snapshot or source volume. More human-readable information MAY be provided in the gRPC `status.message` field. | Caller MUST fix the capacity range before retrying. | #### `DeleteVolume` From 579c2833e5f7a1a37caadd49b652547008536633 Mon Sep 17 00:00:00 2001 From: Jan Safranek Date: Fri, 12 Feb 2021 16:13:10 +0100 Subject: [PATCH 2/2] Move volume resize clarification to its own paragraph --- spec.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 430cd796..9e961104 100644 --- a/spec.md +++ b/spec.md @@ -725,13 +725,10 @@ Plugins MAY create 3 types of volumes: - Empty volumes. When plugin supports `CREATE_DELETE_VOLUME` OPTIONAL capability. - From an existing snapshot. When plugin supports `CREATE_DELETE_VOLUME` and `CREATE_DELETE_SNAPSHOT` OPTIONAL capabilities. - The Plugin SHOULD create a volume that looks like exact copy of the original snapshotted volume at the time the snapshot was taken. - If CO requests a volume that is larger than the original snapshotted volume, the Plugin can either refuse such a call with `OUT_OF_RANGE` error or SHOULD provide a volume that, when presented to a workload by `NodePublish` call, has both the requested (larger) size and contains data from the snapshot. - Explicitly, it's responsibility of the Plugin to resize the filesystem of the volume at or before `NodePublish` call, if the volume has `VolumeCapability` `MountVolume` and the filesystem resize is required to have the larger volume usable by the workload. - From an existing volume. When plugin supports cloning, and reports the OPTIONAL capabilities `CREATE_DELETE_VOLUME` and `CLONE_VOLUME`. - The Plugin SHOULD create a volume that looks like exact copy of the original volume. - If CO requests a volume that is larger than the original volume, the Plugin can either refuse such a call with `OUT_OF_RANGE` error or SHOULD provide a volume that, when presented to a workload by `NodePublish` call, has both the requested (larger) size and contains data from the original volume. - Explicitly, it's responsibility of the Plugin to resize the filesystem of the volume at or before `NodePublish` call, if the volume has `VolumeCapability` `MountVolume` and the filesystem resize is required to have the larger volume usable by the workload. + +If CO requests a volume to be created from existing snapshot or volume and the requested size of the volume is larger than the original snapshotted (or cloned volume), the Plugin can either refuse such a call with `OUT_OF_RANGE` error or MUST provide a volume that, when presented to a workload by `NodePublish` call, has both the requested (larger) size and contains data from the snapshot (or original volume). +Explicitly, it's the responsibility of the Plugin to resize the filesystem of the newly created volume at (or before) the `NodePublish` call, if the volume has `VolumeCapability` access type `MountVolume` and the filesystem resize is required in order to provision the requested capacity. ```protobuf message CreateVolumeRequest {