diff --git a/README.md b/README.md index 1f5620ff..957addcb 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,14 @@ To make changes to the documentation, modify the files in [book/src](https://git Once the PR is reviewed and merged, the CI will automatically generate (using [mdbook](https://github.com/rust-lang-nursery/mdBook)) the HTML to serve and check it in to [src/_book](https://github.com/kubernetes-csi/docs/tree/master/book/src/_book). +To update the [CRD API documentation](book/src/api.md), run: + +```sh +./hack/gen-api.sh +``` + +The script uses the [gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs/) tool to generate a markdown document for the [VolumeSnapshot CRD API](https://github.com/kubernetes-csi/external-snapshotter/tree/master/client/apis/volumesnapshot/v1). See the script for more information and supported configuration. + ## Community, discussion, contribution, and support Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/). diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 02c705e3..e09d87db 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -46,4 +46,6 @@ - [Unit Testing](unit-testing.md) - [Functional Testing](functional-testing.md) - [Drivers](drivers.md) +- [API Reference](api.md) + - [Volume Snapshot](api/volume-snapshot.md) - [Troubleshooting](troubleshooting.md) diff --git a/book/src/api.md b/book/src/api.md new file mode 100644 index 00000000..fcc64b89 --- /dev/null +++ b/book/src/api.md @@ -0,0 +1,5 @@ +# API Reference + +The following is the list of CSI APIs: + +* [Volume Snapshot](api/volume-snapshot.md) diff --git a/book/src/api/volume-snapshot.md b/book/src/api/volume-snapshot.md new file mode 100644 index 00000000..3f4b5e06 --- /dev/null +++ b/book/src/api/volume-snapshot.md @@ -0,0 +1,1034 @@ +# Volume Snapshot + +
Packages:
+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.
+Field | +Description | +||||
---|---|---|---|---|---|
+apiVersion +string |
+
+
+snapshot.storage.k8s.io/v1
+
+ |
+||||
+kind +string + |
+VolumeSnapshot |
+||||
+metadata + + +Kubernetes meta/v1.ObjectMeta + + + |
+
+(Optional)
+ Standard object’s metadata. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata +Refer to the Kubernetes API documentation for the fields of the +metadata field.
+ |
+||||
+spec + + +VolumeSnapshotSpec + + + |
+
+ spec defines the desired characteristics of a snapshot requested by a user. +More info: https://kubernetes.io/docs/concepts/storage/volume-snapshots#volumesnapshots +Required. ++ +
|
+||||
+status + + +VolumeSnapshotStatus + + + |
+
+(Optional)
+ status represents the current information of a snapshot. +Consumers must verify binding between VolumeSnapshot and +VolumeSnapshotContent objects is successful (by validating that both +VolumeSnapshot and VolumeSnapshotContent point at each other) before +using this object. + |
+
VolumeSnapshotClass specifies parameters that a underlying storage system uses when +creating a volume snapshot. A specific VolumeSnapshotClass is used by specifying its +name in a VolumeSnapshot object. +VolumeSnapshotClasses are non-namespaced
+Field | +Description | +
---|---|
+apiVersion +string |
+
+
+snapshot.storage.k8s.io/v1
+
+ |
+
+kind +string + |
+VolumeSnapshotClass |
+
+metadata + + +Kubernetes meta/v1.ObjectMeta + + + |
+
+(Optional)
+ Standard object’s metadata. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata +Refer to the Kubernetes API documentation for the fields of the +metadata field.
+ |
+
+driver + +string + + |
+
+ driver is the name of the storage driver that handles this VolumeSnapshotClass. +Required. + |
+
+parameters + +map[string]string + + |
+
+(Optional)
+ parameters is a key-value map with storage driver specific parameters for creating snapshots. +These values are opaque to Kubernetes. + |
+
+deletionPolicy + + +DeletionPolicy + + + |
+
+ deletionPolicy determines whether a VolumeSnapshotContent created through +the VolumeSnapshotClass should be deleted when its bound 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” means that the VolumeSnapshotContent and its physical snapshot on underlying storage system are deleted. +Required. + |
+
VolumeSnapshotContent represents the actual “on-disk” snapshot object in the +underlying storage system
+Field | +Description | +||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+apiVersion +string |
+
+
+snapshot.storage.k8s.io/v1
+
+ |
+||||||||||||
+kind +string + |
+VolumeSnapshotContent |
+||||||||||||
+metadata + + +Kubernetes meta/v1.ObjectMeta + + + |
+
+(Optional)
+ Standard object’s metadata. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata +Refer to the Kubernetes API documentation for the fields of the +metadata field.
+ |
+||||||||||||
+spec + + +VolumeSnapshotContentSpec + + + |
+
+ spec defines properties of a VolumeSnapshotContent created by the underlying storage system. +Required. ++ +
|
+||||||||||||
+status + + +VolumeSnapshotContentStatus + + + |
+
+(Optional)
+ status represents the current information of a snapshot. + |
+
string
alias)+(Appears on:VolumeSnapshotClass, VolumeSnapshotContentSpec) +
+DeletionPolicy describes a policy for end-of-life maintenance of volume snapshot contents
+Value | +Description | +
---|---|
"Delete" |
+volumeSnapshotContentDelete means the snapshot will be deleted from the +underlying storage system on release from its volume snapshot. + |
+
"Retain" |
+volumeSnapshotContentRetain means the snapshot will be left in its current +state on release from its volume snapshot. + |
+
+(Appears on:VolumeSnapshotContentSpec) +
+VolumeSnapshotContentSource represents the CSI source of a snapshot. +Exactly one of its members must be set. +Members in VolumeSnapshotContentSource are immutable.
+Field | +Description | +
---|---|
+volumeHandle + +string + + |
+
+(Optional)
+ volumeHandle specifies the CSI “volume_id” of the volume from which a snapshot +should be dynamically taken from. +This field is immutable. + |
+
+snapshotHandle + +string + + |
+
+(Optional)
+ snapshotHandle specifies the CSI “snapshot_id” of a pre-existing snapshot on +the underlying storage system for which a Kubernetes object representation +was (or should be) created. +This field is immutable. + |
+
+(Appears on:VolumeSnapshotContent) +
+VolumeSnapshotContentSpec is the specification of a VolumeSnapshotContent
+Field | +Description | +
---|---|
+volumeSnapshotRef + + +Kubernetes core/v1.ObjectReference + + + |
+
+ volumeSnapshotRef specifies the VolumeSnapshot object to which this +VolumeSnapshotContent object is bound. +VolumeSnapshot.Spec.VolumeSnapshotContentName field must reference to +this VolumeSnapshotContent’s name for the bidirectional binding to be valid. +For a pre-existing VolumeSnapshotContent object, name and namespace of the +VolumeSnapshot object MUST be provided for binding to happen. +This field is immutable after creation. +Required. + |
+
+deletionPolicy + + +DeletionPolicy + + + |
+
+ deletionPolicy determines whether this VolumeSnapshotContent and its physical snapshot on +the underlying storage system should be deleted when its bound 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” means that the VolumeSnapshotContent and its physical snapshot on underlying storage system are deleted. +For dynamically provisioned snapshots, this field will automatically be filled in by the +CSI snapshotter sidecar with the “DeletionPolicy” field defined in the corresponding +VolumeSnapshotClass. +For pre-existing snapshots, users MUST specify this field when creating the +VolumeSnapshotContent object. +Required. + |
+
+driver + +string + + |
+
+ 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. + |
+
+volumeSnapshotClassName + +string + + |
+
+(Optional)
+ name of the VolumeSnapshotClass from which this snapshot was (or will be) +created. +Note that after provisioning, the VolumeSnapshotClass may be deleted or +recreated with different set of values, and as such, should not be referenced +post-snapshot creation. + |
+
+source + + +VolumeSnapshotContentSource + + + |
+
+ source specifies whether the snapshot is (or should be) dynamically provisioned +or already exists, and just requires a Kubernetes object representation. +This field is immutable after creation. +Required. + |
+
+sourceVolumeMode + + +Kubernetes core/v1.PersistentVolumeMode + + + |
+
+(Optional)
+ SourceVolumeMode is the mode of the volume whose snapshot is taken. +Can be either “Filesystem” or “Block”. +If not specified, it indicates the source volume’s mode is unknown. +This field is immutable. +This field is an alpha field. + |
+
+(Appears on:VolumeSnapshotContent) +
+VolumeSnapshotContentStatus is the status of a VolumeSnapshotContent object +Note that CreationTime, RestoreSize, ReadyToUse, and Error are in both +VolumeSnapshotStatus and VolumeSnapshotContentStatus. Fields in VolumeSnapshotStatus +are updated based on fields in VolumeSnapshotContentStatus. They are eventual +consistency. These fields are duplicate in both objects due to the following reasons: +- Fields in VolumeSnapshotContentStatus can be used for filtering when importing a +volumesnapshot. +- VolumsnapshotStatus is used by end users because they cannot see VolumeSnapshotContent. +- CSI snapshotter sidecar is light weight as it only watches VolumeSnapshotContent +object, not VolumeSnapshot object.
+Field | +Description | +
---|---|
+snapshotHandle + +string + + |
+
+(Optional)
+ snapshotHandle is the CSI “snapshot_id” of a snapshot on the underlying storage system. +If not specified, it indicates that dynamic snapshot creation has either failed +or it is still in progress. + |
+
+creationTime + +int64 + + |
+
+(Optional)
+ 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 by the
+CSI snapshotter sidecar with the “creation_time” value returned from CSI
+“CreateSnapshot” 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 the creation time is unknown.
+The format of this field is a Unix nanoseconds time encoded as an int64.
+On Unix, the command |
+
+restoreSize + +int64 + + |
+
+(Optional)
+ restoreSize represents the complete size of the snapshot in bytes. +In dynamic snapshot creation case, this field will be filled in by the +CSI snapshotter sidecar with the “size_bytes” value returned from CSI +“CreateSnapshot” 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. + |
+
+readyToUse + +bool + + |
+
+ 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 by the +CSI snapshotter sidecar with the “ready_to_use” value returned from CSI +“CreateSnapshot” 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. + |
+
+error + + +VolumeSnapshotError + + + |
+
+(Optional)
+ error is the last observed error during snapshot creation, if any. +Upon success after retry, this error field will be cleared. + |
+
+(Appears on:VolumeSnapshotContentStatus, VolumeSnapshotStatus) +
+VolumeSnapshotError describes an error encountered during snapshot creation.
+Field | +Description | +
---|---|
+time + + +Kubernetes meta/v1.Time + + + |
+
+(Optional)
+ time is the timestamp when the error was encountered. + |
+
+message + +string + + |
+
+(Optional)
+ message is a string detailing the encountered error during snapshot +creation if specified. +NOTE: message may be logged, and it should not contain sensitive +information. + |
+
+(Appears on:VolumeSnapshotSpec) +
+VolumeSnapshotSource specifies whether the underlying snapshot should be +dynamically taken upon creation or if a pre-existing VolumeSnapshotContent +object should be used. +Exactly one of its members must be set. +Members in VolumeSnapshotSource are immutable.
+Field | +Description | +
---|---|
+persistentVolumeClaimName + +string + + |
+
+(Optional)
+ persistentVolumeClaimName specifies the name of the PersistentVolumeClaim +object representing the volume from which a snapshot should be created. +This PVC is assumed to be in the same namespace as the VolumeSnapshot +object. +This field should be set if the snapshot does not exists, and needs to be +created. +This field is immutable. + |
+
+volumeSnapshotContentName + +string + + |
+
+(Optional)
+ volumeSnapshotContentName specifies the name of a pre-existing VolumeSnapshotContent +object representing an existing volume snapshot. +This field should be set if the snapshot already exists and only needs a representation in Kubernetes. +This field is immutable. + |
+
+(Appears on:VolumeSnapshot) +
+VolumeSnapshotSpec describes the common attributes of a volume snapshot.
+Field | +Description | +
---|---|
+source + + +VolumeSnapshotSource + + + |
+
+ source specifies where a snapshot will be created from. +This field is immutable after creation. +Required. + |
+
+volumeSnapshotClassName + +string + + |
+
+(Optional)
+ VolumeSnapshotClassName is the name of the VolumeSnapshotClass +requested by the VolumeSnapshot. +VolumeSnapshotClassName may be left nil to indicate that the default +SnapshotClass should be used. +A given cluster may have multiple default Volume SnapshotClasses: one +default per CSI Driver. If a VolumeSnapshot does not specify a SnapshotClass, +VolumeSnapshotSource will be checked to figure out what the associated +CSI Driver is, and the default VolumeSnapshotClass associated with that +CSI Driver will be used. If more than one VolumeSnapshotClass exist for +a given CSI Driver and more than one have been marked as default, +CreateSnapshot will fail and generate an event. +Empty string is not allowed for this field. + |
+
+(Appears on:VolumeSnapshot) +
+VolumeSnapshotStatus is the status of the VolumeSnapshot +Note that CreationTime, RestoreSize, ReadyToUse, and Error are in both +VolumeSnapshotStatus and VolumeSnapshotContentStatus. Fields in VolumeSnapshotStatus +are updated based on fields in VolumeSnapshotContentStatus. They are eventual +consistency. These fields are duplicate in both objects due to the following reasons: +- Fields in VolumeSnapshotContentStatus can be used for filtering when importing a +volumesnapshot. +- VolumsnapshotStatus is used by end users because they cannot see VolumeSnapshotContent. +- CSI snapshotter sidecar is light weight as it only watches VolumeSnapshotContent +object, not VolumeSnapshot object.
+Field | +Description | +
---|---|
+boundVolumeSnapshotContentName + +string + + |
+
+(Optional)
+ boundVolumeSnapshotContentName is the name of the VolumeSnapshotContent +object to which this VolumeSnapshot object intends to bind to. +If not specified, it indicates that the VolumeSnapshot object has not been +successfully bound to a VolumeSnapshotContent object yet. +NOTE: To avoid possible security issues, consumers must verify binding between +VolumeSnapshot and VolumeSnapshotContent objects is successful (by validating that +both VolumeSnapshot and VolumeSnapshotContent point at each other) before using +this object. + |
+
+creationTime + + +Kubernetes meta/v1.Time + + + |
+
+(Optional)
+ 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 by the +snapshot controller with the “creation_time” value returned from CSI +“CreateSnapshot” 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 may indicate that the creation time of the snapshot is unknown. + |
+
+readyToUse + +bool + + |
+
+(Optional)
+ readyToUse indicates if the snapshot is ready to be used to restore a volume. +In dynamic snapshot creation case, this field will be filled in by the +snapshot controller with the “ready_to_use” value returned from CSI +“CreateSnapshot” 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. + |
+
+restoreSize + + +k8s.io/apimachinery/pkg/api/resource.Quantity + + + |
+
+(Optional)
+ restoreSize represents the minimum size of volume required to create a volume +from this snapshot. +In dynamic snapshot creation case, this field will be filled in by the +snapshot controller with the “size_bytes” value returned from CSI +“CreateSnapshot” 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. + |
+
+error + + +VolumeSnapshotError + + + |
+
+(Optional)
+ error is the last observed error during snapshot creation, if any. +This field could be helpful to upper level controllers(i.e., application controller) +to decide whether they should continue on waiting for the snapshot to be created +based on the type of error reported. +The snapshot controller will keep retrying when an error occurs during the +snapshot creation. Upon success, this error field will be cleared. + |
+
+Generated with gen-crd-api-reference-docs
+on git commit b20011c8
.
+