more comment updates

VolumeSnapshot comments
rename to VolumeSnapshotClassName
adding license
fix comments

Author: yuxiangqian

config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml

@@ -60,23 +60,24 @@ spec:
                 same as the name returned by the CSI GetPluginName() call for that
                 driver. Required.
               type: string
-            snapshotClassName:
-              description: name of the SnapshotClass to which this snapshot belongs.
-              type: string
             source:
               description: source specifies from where a snapshot will be created.
                 This field is immutable after creation. Required.
               properties:
                 snapshotHandle:
-                  description: snapshotHandle specifies the CSI name of a pre-existing
+                  description: snapshotHandle specifies the "snapshot_id" of a pre-existing
                     snapshot on the underlying storage system. This field is immutable.
                   type: string
                 volumeHandle:
-                  description: volumeHandle specifies the CSI name of the volume from
-                    which a snapshot should be dynamically taken from. This field
+                  description: volumeHandle specifies the "volume_id" of the volume
+                    from which a snapshot should be dynamically taken from. This field
                     is immutable.
                   type: string
               type: object
+            volumeSnapshotClassName:
+              description: name of the VolumeSnapshotClass to which this snapshot
+                belongs.
+              type: string
             volumeSnapshotRef:
               description: volumeSnapshotRef specifies the VolumeSnapshot object to
                 which this VolumeSnapshotContent object is bound. VolumeSnapshot.Spec.VolumeSnapshotContentName
@@ -131,12 +132,13 @@ spec:
               description: creationTime is the timestamp when the point-in-time snapshot
                 is taken by the underlying storage system. In dynamic snapshot creation
                 case, this field will be filled in with the "creation_time" value
-                returned from CSI "CreateSnapshotRequest" gRPC call. For pre-existing
+                returned from CSI "CreateSnapshotRequest" gRPC call. For a pre-existing
                 snapshot, this field will be filled with the "creation_time" value
-                returned from CSI "ListSnapshots" gRPC call if the CSI driver supports.
-                The format of this field is a Unix nanoseconds time encoded as an
-                int64. On Unix, the command `date +%s%N` returns the current time
-                in nanoseconds since 1970-01-01 00:00:00 UTC.
+                returned from the CSI "ListSnapshots" gRPC call if the driver supports
+                it. If not specified, it indicates the creation time is unknown. The
+                format of this field is a Unix nanoseconds time encoded as an int64.
+                On Unix, the command `date +%s%N` returns the current time in nanoseconds
+                since 1970-01-01 00:00:00 UTC.
               format: int64
               type: integer
             error:
@@ -157,21 +159,22 @@ spec:
               description: readyToUse indicates if a snapshot is ready to be used
                 to restore a volume. In dynamic snapshot creation case, this field
                 will be filled in with the "ready_to_use" value returned from CSI
-                "CreateSnapshotRequest" gRPC call. For pre-existing snapshot, this
-                field will be filled with the "read_to_use" value returned from CSI
-                "ListSnapshots" gRPC call if the CSI driver supports. If not specified,
-                it means the readiness of a snapshot is unknown.
+                "CreateSnapshotRequest" gRPC call. For a pre-existing snapshot, this
+                field will be filled with the "ready_to_use" value returned from the
+                CSI "ListSnapshots" gRPC call if the driver supports it, otherwise,
+                this field will be set to "True". If not specified, it means the readiness
+                of a snapshot is unknown.
               type: boolean
             restoreSize:
               description: restoreSize represents the complete size of the snapshot
                 in bytes. In dynamic snapshot creation case, this field will be filled
                 in with the "size_bytes" value returned from CSI "CreateSnapshotRequest"
-                gRPC call. For pre-existing snapshot, this field will be filled with
-                the "size_bytes" value returned from CSI "ListSnapshots" gRPC call
-                if the CSI driver supports. When restoring a volume from this snapshot,
-                the size of the volume MUST NOT be smaller than the restoreSize if
-                it is specified. Otherwise the restoration will fail. If not specified,
-                it indicates that the size is unknown.
+                gRPC call. For a pre-existing snapshot, this field will be filled
+                with the "size_bytes" value returned from the CSI "ListSnapshots"
+                gRPC call if the driver supports it. When restoring a volume from
+                this snapshot, the size of the volume MUST NOT be smaller than the
+                restoreSize if it is specified, otherwise the restoration will fail.
+                If not specified, it indicates that the size is unknown.
               format: int64
               minimum: 0
               type: integer

config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml

@@ -21,9 +21,8 @@ spec:
   preserveUnknownFields: false
   validation:
     openAPIV3Schema:
-      description: VolumeSnapshot is a user's request for taking a point-in-time snapshot
-        of a PersistentVolumeClaim. Upon successful creation of a snapshot by the
-        underlying storage system, it is bound to a corresponding VolumeSnapshotContent.
+      description: VolumeSnapshot is a user's request for either creating a point-in-time
+        snapshot of a persistent volume, or binding to a pre-existing snapshot.
       properties:
         apiVersion:
           description: 'APIVersion defines the versioned schema of this representation
@@ -84,15 +83,14 @@ spec:
                 avoid possible security issues.'
               type: string
             creationTime:
-              description: creationTime, if specified, represents the timestamp when
-                the point-in-time snapshot was successfully cut on the underlying
-                storage system. In dynamic snapshot creation case, it will be filled
-                in upon snapshot creation with the "creation_time" field returned
-                from CSI "CreateSnapshot" gRPC call. For a pre-existing snapshot,
-                it will be set to the "size_byte" value returned from CSI "ListSnapshots"
-                gRPC call if there exists a matching CSI driver that supports it after
-                binding. If not specified, it indicates that the creation time of
-                the snapshot is unknown.
+              description: creationTime is the timestamp when the point-in-time snapshot
+                is taken by the underlying storage system. In dynamic snapshot creation
+                case, this field will be filled in with the "creation_time" value
+                returned from CSI "CreateSnapshotRequest" gRPC call. For a pre-existing
+                snapshot, this field will be filled with the "creation_time" value
+                returned from the CSI "ListSnapshots" gRPC call if the driver supports
+                it. If not specified, it indicates that the creation time of the snapshot
+                is unknown.
               format: date-time
               type: string
             error:
@@ -114,28 +112,24 @@ spec:
               type: object
             readyToUse:
               description: readyToUse indicates if a snapshot is ready to be used
-                to restore a volume. In dynamic snapshot creation case, readyToUse
-                will be set to true after underlying storage system has successfully
-                finished all out-of-bound procedures to make a snapshot ready to be
-                used to restore a volume. For a pre-existing snapshot, readyToUse
-                will be set to the "read_to_use" field returned from CSI "ListSnapshots"
-                gRPC call if there exists a matching CSI driver that supports it after
-                binding. Otherwise, this field will be set to "True". If not specified,
-                it indicates that the readiness of a snapshot is unknown.
+                to restore a volume. In dynamic snapshot creation case, this field
+                will be filled in with the "ready_to_use" value returned from CSI
+                "CreateSnapshotRequest" gRPC call. For a pre-existing snapshot, this
+                field will be filled with the "ready_to_use" value returned from the
+                CSI "ListSnapshots" gRPC call if the driver supports it, otherwise,
+                this field will be set to "True". If not specified, it means the readiness
+                of a snapshot is unknown.
               type: boolean
             restoreSize:
-              description: restoreSize, if specified, represents the complete size
-                of the snapshot in bytes. In dynamic snapshot creation case, restoreSize
-                will be filled with the "size_bytes" value returned from "CreateSnapshot"
-                gRPC call. For a pre-existing snapshot, restoreSize will be filled
-                with the "size_bytes" value returned from CSI "ListSnapshots" gRPC
-                call if there exists a matching  CSI driver that supports it after
-                binding. The purpose of this field is to give user guidance on how
-                much space is needed to restore a volume from this snapshot. When
-                restoring a volume from a snapshot, the size of the volume MUST NOT
-                be less than the restoreSize. Otherwise the restoration will fail.
-                If not specified, it indicates that underlying storage system does
-                not have the information available.
+              description: restoreSize represents the complete size of the snapshot
+                in bytes. In dynamic snapshot creation case, this field will be filled
+                in with the "size_bytes" value returned from CSI "CreateSnapshotRequest"
+                gRPC call. For a pre-existing snapshot, this field will be filled
+                with the "size_bytes" value returned from the CSI "ListSnapshots"
+                gRPC call if the driver supports it. When restoring a volume from
+                this snapshot, the size of the volume MUST NOT be smaller than the
+                restoreSize if it is specified, otherwise the restoration will fail.
+                If not specified, it indicates that the size is unknown.
               type: string
           type: object
       required:

pkg/apis/volumesnapshot/v1beta1/types.go

@@ -26,9 +26,8 @@ import (
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// VolumeSnapshot is a user's request for taking a point-in-time snapshot of a PersistentVolumeClaim.
-// Upon successful creation of a snapshot by the underlying storage system, it is bound to a
-// corresponding VolumeSnapshotContent.
+// VolumeSnapshot is a user's request for either creating a point-in-time
+// snapshot of a persistent volume, or binding to a pre-existing snapshot.
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:scope=Namespaced
 // +kubebuilder:subresource:status
@@ -115,41 +114,34 @@ type VolumeSnapshotStatus struct {
 	// +optional
 	BoundVolumeSnapshotContentName *string `json:"boundVolumeSnapshotContentName,omitempty" protobuf:"bytes,1,opt,name=boundVolumeSnapshotContentName"`
 
-	// creationTime, if specified, represents the timestamp when the point-in-time
-	// snapshot was successfully cut on the underlying storage system.
-	// In dynamic snapshot creation case, it will be filled in upon snapshot creation
-	// with the "creation_time" field returned from CSI "CreateSnapshot" gRPC call.
-	// For a pre-existing snapshot, it will be set to the "size_byte" value returned
-	// from CSI "ListSnapshots" gRPC call if there exists a matching CSI driver that
-	// supports it after binding.
+	// creationTime is the timestamp when the point-in-time snapshot is taken
+	// by the underlying storage system.
+	// In dynamic snapshot creation case, this field will be filled in with the
+	// "creation_time" value returned from CSI "CreateSnapshotRequest" gRPC call.
+	// For a pre-existing snapshot, this field will be filled with the "creation_time"
+	// value returned from the CSI "ListSnapshots" gRPC call if the driver supports it.
 	// If not specified, it indicates that the creation time of the snapshot is unknown.
 	// +optional
 	CreationTime *metav1.Time `json:"creationTime,omitempty" protobuf:"bytes,2,opt,name=creationTime"`
 
 	// readyToUse indicates if a snapshot is ready to be used to restore a volume.
-	// In dynamic snapshot creation case, readyToUse will be set to true after underlying storage
-	// system has successfully finished all out-of-bound procedures to make a snapshot ready to
-	// be used to restore a volume.
-	// For a pre-existing snapshot, readyToUse will be set to the "read_to_use" field
-	// returned from CSI "ListSnapshots" gRPC call if there exists a matching CSI driver
-	// that supports it after binding.
-	// Otherwise, this field will be set to "True".
-	// If not specified, it indicates that the readiness of a snapshot is unknown.
+	// In dynamic snapshot creation case, this field will be filled in with the
+	// "ready_to_use" value returned from CSI "CreateSnapshotRequest" gRPC call.
+	// For a pre-existing snapshot, this field will be filled with the "ready_to_use"
+	// value returned from the CSI "ListSnapshots" gRPC call if the driver supports it,
+	// otherwise, this field will be set to "True".
+	// If not specified, it means the readiness of a snapshot is unknown.
 	// +optional
 	ReadyToUse *bool `json:"readyToUse,omitempty" protobuf:"varint,3,opt,name=readyToUse"`
 
-	// restoreSize, if specified, represents the complete size of the snapshot in bytes.
-	// In dynamic snapshot creation case, restoreSize will be filled with the
-	// "size_bytes" value returned from "CreateSnapshot" gRPC call.
-	// For a pre-existing snapshot, restoreSize will be filled with the "size_bytes"
-	// value returned from CSI "ListSnapshots" gRPC call if there exists a matching
-	//  CSI driver that supports it after binding.
-	// The purpose of this field is to give user guidance on how much space is
-	// needed to restore a volume from this snapshot.
-	// When restoring a volume from a snapshot, the size of the volume MUST NOT
-	// be less than the restoreSize. Otherwise the restoration will fail.
-	// If not specified, it indicates that underlying storage system does not have
-	// the information available.
+	// restoreSize represents the complete size of the snapshot in bytes.
+	// In dynamic snapshot creation case, this field will be filled in with the
+	// "size_bytes" value returned from CSI "CreateSnapshotRequest" gRPC call.
+	// For a pre-existing snapshot, this field will be filled with the "size_bytes"
+	// value returned from the CSI "ListSnapshots" gRPC call if the driver supports it.
+	// When restoring a volume from this snapshot, the size of the volume MUST NOT
+	// be smaller than the restoreSize if it is specified, otherwise the restoration will fail.
+	// If not specified, it indicates that the size is unknown.
 	// +optional
 	RestoreSize *resource.Quantity `json:"restoreSize,omitempty" protobuf:"bytes,4,opt,name=restoreSize"`
 
@@ -279,9 +271,9 @@ type VolumeSnapshotContentSpec struct {
 	// Required.
 	Driver string `json:"driver" protobuf:"bytes,3,opt,name=driver"`
 
-	// name of the SnapshotClass to which this snapshot belongs.
+	// name of the VolumeSnapshotClass to which this snapshot belongs.
 	// +optional
-	SnapshotClassName *string `json:"snapshotClassName,omitempty" protobuf:"bytes,4,opt,name=snapshotClassName"`
+	VolumeSnapshotClassName *string `json:"volumeSnapshotClassName,omitempty" protobuf:"bytes,4,opt,name=volumeSnapshotClassName"`
 
 	// source specifies from where a snapshot will be created.
 	// This field is immutable after creation.
@@ -295,14 +287,14 @@ type VolumeSnapshotContentSpec struct {
 // TODO(xiangqian): Add a webhook to ensure that VolumeSnapshotContentSource members
 // will be immutable once specified.
 type VolumeSnapshotContentSource struct {
-	// volumeHandle specifies the CSI name of the volume from which a snapshot
+	// volumeHandle specifies the "volume_id" of the volume from which a snapshot
 	// should be dynamically taken from.
 	// This field is immutable.
 	// +optional
 	VolumeHandle *string `json:"volumeHandle,omitempty" protobuf:"bytes,1,opt,name=volumeHandle"`
 
-	// snapshotHandle specifies the CSI name of a pre-existing snapshot on the
-	// underlying storage system.
+	// snapshotHandle specifies the "snapshot_id" of a pre-existing snapshot on
+	// the underlying storage system.
 	// This field is immutable.
 	// +optional
 	SnapshotHandle *string `json:"snapshotHandle,omitempty" protobuf:"bytes,2,opt,name=snapshotHandle"`
@@ -320,8 +312,9 @@ type VolumeSnapshotContentStatus struct {
 	// by the underlying storage system.
 	// In dynamic snapshot creation case, this field will be filled in with the
 	// "creation_time" value returned from CSI "CreateSnapshotRequest" gRPC call.
-	// For pre-existing snapshot, this field will be filled with the "creation_time"
-	// value returned from CSI "ListSnapshots" gRPC call if the CSI driver supports.
+	// For a pre-existing snapshot, this field will be filled with the "creation_time"
+	// value returned from the CSI "ListSnapshots" gRPC call if the driver supports it.
+	// If not specified, it indicates the creation time is unknown.
 	// The format of this field is a Unix nanoseconds time encoded as an int64.
 	// On Unix, the command `date +%s%N` returns the current time in nanoseconds
 	// since 1970-01-01 00:00:00 UTC.
@@ -331,11 +324,10 @@ type VolumeSnapshotContentStatus struct {
 	// restoreSize represents the complete size of the snapshot in bytes.
 	// In dynamic snapshot creation case, this field will be filled in with the
 	// "size_bytes" value returned from CSI "CreateSnapshotRequest" gRPC call.
-	// For pre-existing snapshot, this field will be filled with the "size_bytes"
-	// value returned from CSI "ListSnapshots" gRPC call if the CSI driver supports.
+	// For a pre-existing snapshot, this field will be filled with the "size_bytes"
+	// value returned from the CSI "ListSnapshots" gRPC call if the driver supports it.
 	// When restoring a volume from this snapshot, the size of the volume MUST NOT
-	// be smaller than the restoreSize if it is specified.
-	// Otherwise the restoration will fail.
+	// be smaller than the restoreSize if it is specified, otherwise the restoration will fail.
 	// If not specified, it indicates that the size is unknown.
 	// +kubebuilder:validation:Minimum=0
 	// +optional
@@ -344,8 +336,9 @@ type VolumeSnapshotContentStatus struct {
 	// readyToUse indicates if a snapshot is ready to be used to restore a volume.
 	// In dynamic snapshot creation case, this field will be filled in with the
 	// "ready_to_use" value returned from CSI "CreateSnapshotRequest" gRPC call.
-	// For pre-existing snapshot, this field will be filled with the "read_to_use"
-	// value returned from CSI "ListSnapshots" gRPC call if the CSI driver supports.
+	// For a pre-existing snapshot, this field will be filled with the "ready_to_use"
+	// value returned from the CSI "ListSnapshots" gRPC call if the driver supports it,
+	// otherwise, this field will be set to "True".
 	// If not specified, it means the readiness of a snapshot is unknown.
 	// +optional.
 	ReadyToUse *bool `json:"readyToUse,omitempty" protobuf:"varint,4,opt,name=readyToUse"`