Skip to content

Commit

Permalink
more comment updates
Browse files Browse the repository at this point in the history 
VolumeSnapshot comments
rename to VolumeSnapshotClassName
adding license
fix comments
  • Loading branch information
@yuxiangqian
yuxiangqian committed Oct 24, 2019
1 parent ba6ec14 commit be76d8c
Show file tree
Hide file tree
Showing 6 changed files with 93 additions and 103 deletions.
45 changes: 24 additions & 21 deletions config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down
58 changes: 26 additions & 32 deletions config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand Down
79 changes: 36 additions & 43 deletions pkg/apis/volumesnapshot/v1beta1/types.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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"`

Expand Down Expand Up @@ -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.
Expand All @@ -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"`
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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"`
Expand Down
Loading

0 comments on commit be76d8c

Please sign in to comment.