From 0b6954c497998a8b60e6a227c6f5931a47a99401 Mon Sep 17 00:00:00 2001 From: xing-yang Date: Mon, 16 Jul 2018 16:56:04 -0700 Subject: [PATCH] Modify VolumeSnapshotStatus --- .../design-proposals/storage/csi-snapshot.md | 117 ++++++++++-------- 1 file changed, 66 insertions(+), 51 deletions(-) diff --git a/contributors/design-proposals/storage/csi-snapshot.md b/contributors/design-proposals/storage/csi-snapshot.md index 49905885fee..95f4e0e98b0 100644 --- a/contributors/design-proposals/storage/csi-snapshot.md +++ b/contributors/design-proposals/storage/csi-snapshot.md @@ -90,51 +90,54 @@ type VolumeSnapshotSpec struct { SnapshotClassName string `json:"storageClassName" protobuf:"bytes,3,opt,name=storageClassName"` } -type VolumeSnapshotStatus struct { - // The time the snapshot was successfully created - // +optional - CreationTimestamp metav1.Time `json:"creationTimestamp" protobuf:"bytes,1,opt,name=creationTimestamp"` +type VolumeSnapshotCreated struct { + // The time the snapshot was successfully created + // +optional + CreatedAt metav1.Time `json:"createdAt" protobuf:"bytes,1,opt,name=createdAt"` +} - // Represents the lates available observations about the volume snapshot - Conditions []VolumeSnapshotCondition `json:"conditions" protobuf:"bytes,2,rep,name=conditions"` +type VolumeSnapshotAvailable struct { + // The time the snapshot was successfully created and available for use + // +optional + AvailableAt metav1.Time `json:"availableAt" protobuf:"bytes,1,opt,name=availableAt"` } -type VolumeSnapshotConditionType string - -// These are valid conditions of a volume snapshot. -const ( - // If VolumeSnapshotConditionType is "Created" and ConditionStatus is True, it means - // the snapshot is created. - // If VolumeSnapshotConditionType is "Created" and ConditionStatus is False, it means - // the snapshot is not created yet. - VolumeSnapshotConditionCreated VolumeSnapshotConditionType = "Created" - // If VolumeSnapshotConditionType is "Available" and ConditionStatus is True, it means - // the snapshot is created and available to be used. - // If VolumeSnapshotConditionType is "Available" and ConditionStatus is False, it means - // the snapshot is created, application can be resumed if it was previously frozen, but - // the snapshot is not available to be used yet. In this case, it is possible that the - // snapshot is being uploaded to the cloud. For example, both GCE and AWS support - // uploading of the snapshot after it is cut as part of the Create Snapshot process. - VolumeSnapshotConditionAvailable VolumeSnapshotConditionType = "Available" - // VolumeSnapshotConditionError means an error occurred during snapshot creation or uploading. - VolumeSnapshotConditionError VolumeSnapshotConditionType = "Error" -) - -// VolumeSnapshot Condition describes the state of a volume snapshot at a certain point. -type VolumeSnapshotCondition struct { - // Type of replication controller condition. - Type VolumeSnapshotConditionType `json:"type" protobuf:"bytes,1,opt,name=type,casttype=VolumeSnapshotConditionType"` - // Status of the condition, one of True, False, Unknown. - Status core_v1.ConditionStatus `json:"status" protobuf:"bytes,2,opt,name=status,casttype=ConditionStatus"` - // The last time the condition transitioned from one status to another. - // +optional - LastTransitionTime metav1.Time `json:"lastTransitionTime" protobuf:"bytes,3,opt,name=lastTransitionTime"` - // The reason for the condition's last transition. - // +optional - Reason string `json:"reason" protobuf:"bytes,4,opt,name=reason"` - // A human readable message indicating details about the transition. - // +optional - Message string `json:"message" protobuf:"bytes,5,opt,name=message"` +type VolumeSnapshotError struct { + // A brief CamelCase string indicating details about why the snapshot is in error state. + // +optional + Reason string + // A human-readable message indicating details about why the snapshot is in error state. + // +optional + Message string + // The time the error occurred during the snapshot creation (or uploading) process + // +optional + FailedAt metav1.Time `json:"failedAt" protobuf:"bytes,1,opt,name=failedAt"` +} + +type VolumeSnapshotStatus struct { + // VolumeSnapshotCreated indicates whether the snapshot was successfully created. + // If the timestamp CreateAt is set, it means the snapshot was created; + // Otherwise the snapshot was not created. + // +optional + Created VolumeSnapshotCreated + + // VolumeSnapshotAvailable indicates whether the snapshot was available for use. + // A snapshot MUST have already been created before it can be available. + // If a snapshot was available, it indicates the snapshot was created. + // When the snapshot was created but not available yet, the application can be + // resumed if it was previously frozen before taking the snapshot. In this case, + // it is possible that the snapshot is being uploaded to the cloud. For example, + // both GCE and AWS support uploading of the snapshot after it is cut as part of + // the Create Snapshot process. + // If the timestamp AvailableAt is set, it means the snapshot was available; + // Otherwise the snapshot was not available. + // +optional + Available VolumeSnapshotAvailable + + // VolumeSnapshotError indicates an error occurred during the snapshot creation + // (or uploading) process. + // +optional + Error VolumeSnapshotError } ``` @@ -213,26 +216,36 @@ type CSIVolumeSnapshotSource struct { Add a new field into PVC to represent the source of the data which is prepopulated to the provisioned volume. Possible source types may include the following: - * Snapshot: restore snapshot to a new volume + * VolumeSnapshot: restore snapshot to a new volume * PersistentVolumeClaim: clone volume which is represented by PVC ``` type PersistentVolumeClaimSpec struct { - // If specified, volume will be prepopulated with data from the DataSource. + // If specified, volume will be prepopulated with data from the PVCDataSourceRef. // +optional - PVCDataSource DataSource + PVCDataSourceRef *core_v1.LocalObjectReference `json:"dataSourceRef" protobuf:"bytes,2,opt,name=dataSourceRef"` + } -type DataSource struct { - // Name of the source that the volume will be prepopulated with. - Name string - // Type of the source that the volume will be prepopulated with. - Type string +``` + +The existing LocalObjectReference in core API will be modified to add a `Kind`. + +``` + +// LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace. +type LocalObjectReference struct { + //TODO: Add other useful fields. apiVersion, kind, uid? + Name string + // Kind indicates the type of the object reference. + // +optional + Kind string } ``` -Note: Type could be Snapshot, PersistentVolumeClaim, etc. + +In the first version, only VolumeSnapshot will be a supported `Type` for data source object reference. PersistentVolumeClaim will be added in a future version. If unsupported `Type` is used, the PV Controller SHALL bail out of the operation. #### The `SnapshotClass` Object @@ -298,6 +311,8 @@ The snapshotter creates CreateSnapshotRequest and calls CreateSnapshot through C The snapshotter checks status in VolumeSnapshot to decide whether to bind. It binds VolumeSnapshot and VolumeSnapshotContent when ready. +When the storage system fails to create snapshot, retry will not be performed in the first version. This is because users may not want to retry when taking consistent snapshots or scheduled snapshots when the timing of the snapshot creation is important. In a future version, a maxRetries flag will be added to allow users to control whether retries are needed. + ### Changes in PV Controller and CSI External Provisioner