remove CSIVolumeSnapshotSource and VolumeSnapshotSource and flatten t…

…he information into VolumeSnapshotContentSpec, comments enhancement
xing-yang · Aug 30, 2019 · df77c9a · df77c9a
1 parent fefe96a
commit df77c9a
Show file tree

Hide file tree

Showing 4 changed files with 103 additions and 105 deletions.
diff --git a/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml b/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
@@ -36,7 +36,8 @@ spec:
           - Retain
           type: string
         driver:
-          description: driver is the name of the driver that handles this VolumeSnapshotClass.
+          description: driver is the name of the storage driver that handles this
+            VolumeSnapshotClass.
           type: string
         kind:
           description: 'Kind is a string value representing the REST resource this

diff --git a/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml b/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
@@ -31,46 +31,20 @@ spec:
           type: object
         spec:
           description: spec defines properties of a VolumeSnapshotContent created
-            by underlying storage system.
+            by the underlying storage system.
           properties:
-            csi:
-              description: csi represents a volume snapshot created by a CSI(Container
-                Storage Interface) driver.
-              properties:
-                creationTime:
-                  description: creationTime is the timestamp when the point-in-time
-                    snapshot is taken by the underlying storage system. This timestamp
-                    is returned by the CSI driver after the snapshot is cut. 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 (aka, epoch time) since 1970-01-01 00:00:00 UTC.
-                  format: int64
-                  type: integer
-                driver:
-                  description: driver is the name of the CSI driver used to create
-                    the physical snapshot on the underlying storage system. This MUST
-                    be the same name returned by the CSI GetPluginName() call for
-                    that driver. Required.
-                  type: string
-                restoreSize:
-                  description: restoreSize specifies the number of bytes that the
-                    snapshot's data would consume when restored to a volume. When
-                    restoring a volume from a snapshot, the volume size needs to be
-                    equal to or larger than the RestoreSize if it is specified.
-                  format: int64
-                  type: integer
-                snapshotHandle:
-                  description: snapshotHandle is the snapshot id returned by the CSI
-                    driver in the CreateSnapshotResponse and is used as the snapshot
-                    identifier for all subsequent CSI calls. Required.
-                  type: string
-              required:
-              - driver
-              - snapshotHandle
-              type: object
+            creationTime:
+              description: creationTime is the timestamp when the point-in-time snapshot
+                is taken by the underlying storage system. This timestamp is returned
+                by the CSI driver after the snapshot is cut. 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 (aka, epoch time)
+                since 1970-01-01 00:00:00 UTC.
+              format: int64
+              type: integer
             deletionPolicy:
               description: deletionPolicy determines whether this VolumeSnapshotContent
-                and its bound physical snapshot on the underlying storage system should
+                and its physical snapshot on the underlying storage system should
                 be deleted when its VolumeSnapshot is deleted. Supported values are
                 "Retain" and "Delete". "Retain" means that the VolumeSnapshotContent
                 and its physical snapshot on underlying storage system are kept. "Delete"
@@ -81,13 +55,35 @@ spec:
               - Delete
               - Retain
               type: string
+            driver:
+              description: driver is the name of the CSI driver used to create the
+                physical snapshot on the underlying storage system. This MUST be the
+                same as the name returned by the CSI GetPluginName() call for that
+                driver. Required.
+              type: string
+            restoreSize:
+              description: restoreSize specifies the number of bytes that the snapshot's
+                data would consume when restored to a volume. When restoring a volume
+                from a snapshot, the volume size needs to be equal to or larger than
+                the restoreSize if it is specified. Otherwise the restoration will
+                fail.
+              format: int64
+              type: integer
+            snapshotHandle:
+              description: snapshotHandle is the snapshot id returned by the CSI driver
+                in the CreateSnapshotResponse and is used as the snapshot identifier
+                for all subsequent CSI calls. Required.
+              type: string
             volumeSnapshotRef:
               description: volumeSnapshotRef specifies the VolumeSnapshot object that
                 this VolumeSnapshotContent is bound with. The VolumeSnapshot.Spec.VolumeSnapshotContentName
-                field must reference this VolumeSnapshotContent name for the binding
-                to be considered valid(a.k.a bi-directional binding). If the referenced
-                VolumeSnapshot object does not exist(i.e., deleted by user), then
-                the VolumeSnapshotContent.Spec.DeletionPolicy is triggered.
+                field must reference this VolumeSnapshotContent name for the bidirectional
+                binding to be considered valid. If the referenced VolumeSnapshot object
+                does not exist(i.e., deleted by user) AND the UID of the referent
+                is not empty(i.e., volumeSnapshotRef.UID != ""), then the VolumeSnapshotContent.Spec.DeletionPolicy
+                is triggered. To statically bind a pre-existing snapshot, user MUST
+                leave volumeSnapshotRef.UID empty to avoid triggering undesired VolumeSnapshotContent
+                object deletion.
               properties:
                 apiVersion:
                   description: API version of the referent.
@@ -122,6 +118,9 @@ spec:
                   description: 'UID of the referent. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#uids'
                   type: string
               type: object
+          required:
+          - driver
+          - snapshotHandle
           type: object
       required:
       - spec

diff --git a/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml b/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
@@ -37,10 +37,10 @@ spec:
             source:
               description: source specifies where a snapshot should be created from.
                 Currently, PersistentVolumeClaim is the only supported source type.
-                If specified, and VolumeSnapshotContentName is not specified(i.e.,
+                If specified, and volumeSnapshotContentName is not specified(i.e.,
                 nil), snapshot will be dynamically created from the given source.
-                If not specified, and VolumeSnapshotContentName is not specified,
-                system controller will fail on dynamic snapshot creation.
+                If both source and volumeSnapshotContentName are not specified, dynamic
+                snapshot creation will fail.
               properties:
                 apiGroup:
                   description: APIGroup is the group for the resource being referenced.
@@ -61,8 +61,8 @@ spec:
               description: 'volumeSnapshotClassName is the name of the VolumeSnapshotClass
                 requested by the VolumeSnapshot. If not specified, the default snapshot
                 class will be used if there exists one. If not specified, and there
-                is no default snapshot class, dynamic VolumeSnapshot creation will
-                fail. More info: https://kubernetes.io/docs/concepts/storage/volume-snapshot-classes'
+                is no default snapshot class, dynamic snapshot creation will fail.
+                More info: https://kubernetes.io/docs/concepts/storage/volume-snapshot-classes'
               type: string
             volumeSnapshotContentName:
               description: volumeSnapshotContentName is the name of the VolumeSnapshotContent
@@ -74,16 +74,19 @@ spec:
           type: object
         status:
           description: 'status represents the current information of a snapshot. NOTE:
-            status can be modified by sources other than system controllers,       and
-            must not be depended upon for accuracy.       Controllers should only
-            be using information from the VolumeSnapshotContent object       after
-            verifying that the binding is accurate and complete.'
+            status can be modified by sources other than system controllers, and must
+            not be depended upon for accuracy. Controllers should only be using information
+            from the VolumeSnapshotContent object after verifying that the binding
+            is accurate and complete.'
           properties:
             creationTime:
               description: 'creationTime, if not nil, represents the timestamp when
-                a snapshot was successfully cut by the underlying storage system.
-                In static binding, CreationTime might not be available. NOTE: Controllers
-                MUST NOT rely on this field programmatically'
+                the snapshot was successfully cut by the underlying storage system.
+                When dynamically creating a snapshot, this will be filled in upon
+                creation. For pre-existing snapshot, it will be filled in upon the
+                VolumeSnapshot object has been successfully bound to a VolumeSnapshotContent
+                object and the underlying storage system have the information available.
+                NOTE: Controllers MUST NOT rely on this field programmatically.'
               format: date-time
               type: string
             error:
@@ -105,22 +108,23 @@ spec:
               type: object
             readyToUse:
               description: 'readyToUse is an informational flag which provides transparency
-                to users. In dynamic snapshot creation case, ReadyToUse will be set
+                to users. In dynamic snapshot creation case, readyToUse will be set
                 to true when underlying storage system has successfully finished all
-                procedures out-of-bound to make a snapshot available AND snapshot
-                controller has bound the VolumeSnapshot to a VolumeSnapshotContent
-                successfully. If not specified(i.e., nil), it means the readiness
-                of the VolumeSnapshot is unknown to system controllers. NOTE: Controllers
-                MUST NOT rely on this field programmatically'
+                out-of-bound procedures to make a snapshot ready to consume, i.e.,
+                restoring a PersistentVolumeClaim from the snapshot. TODO(@xiangqian):
+                Adding the case for pre-existing snapshots after the logic has been
+                fully sorted out. If not specified(i.e., nil), it means the readiness
+                of the snapshot is unknown to system controllers. NOTE: Controllers
+                MUST NOT rely on this field programmatically.'
               type: boolean
             restoreSize:
               description: 'restoreSize specifies the number of bytes that the snapshot''s
                 data would consume when restored to a volume. When restoring a volume
                 from a snapshot, the volume size needs to be equal to or larger than
-                the RestoreSize if it is specified. The field could be nil if the
-                underlying storage system does not have the information available,
-                or in cases like static binding. NOTE: Controllers MUST NOT rely on
-                this field programmatically'
+                the restoreSize if it is specified. Otherwise the restoration will
+                fail. The field could be nil if the underlying storage system does
+                not have the information available. NOTE: Controllers MUST NOT rely
+                on this field programmatically.'
               type: string
           type: object
       type: object