From d86943f11085d5f374f15a22ff4335a7b8ffb391 Mon Sep 17 00:00:00 2001 From: Ivan Sim Date: Mon, 21 Mar 2022 21:40:57 -0700 Subject: [PATCH 1/3] Add CRD API documentation The hack/gen-api.sh script can be used to generate the documentation. The configuration used by the tool is found in the hack/gen-api.json file. Signed-off-by: Ivan Sim --- README.md | 8 + book/src/SUMMARY.md | 2 + book/src/api.md | 1055 +++++++++++++++++++++++++++++++++++++++++++ hack/gen-api.json | 28 ++ hack/gen-api.sh | 43 ++ 5 files changed, 1136 insertions(+) create mode 100644 book/src/api.md create mode 100644 hack/gen-api.json create mode 100755 hack/gen-api.sh diff --git a/README.md b/README.md index 1f5620ff..bd590af2 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 [CSI 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..377e2640 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) +- [Reference]() + - [API Docs](api.md) - [Troubleshooting](troubleshooting.md) diff --git a/book/src/api.md b/book/src/api.md new file mode 100644 index 00000000..28ebc444 --- /dev/null +++ b/book/src/api.md @@ -0,0 +1,1055 @@ +# API Documentation + +

Packages:

+ +

snapshot.storage.k8s.io/v1

+Resource Types: + +

VolumeSnapshot +

+
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+
+ + + + + + + + + +
+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.

+
+
+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 +

+
+

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

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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 +

+
+

VolumeSnapshotContent represents the actual “on-disk” snapshot object in the +underlying storage system

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+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
+ + +SourceVolumeMode + + +		 +(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.

+
+
+status
+ + +VolumeSnapshotContentStatus + + +		 +(Optional) +

status represents the current information of a snapshot.

+
+

DeletionPolicy +(string alias)

+

+(Appears on:VolumeSnapshotClass, VolumeSnapshotContentSpec) +

+
+

DeletionPolicy describes a policy for end-of-life maintenance of volume snapshot contents

+
+ + + + + + + + + + + + +
ValueDescription

"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.

+
+

SourceVolumeMode +(string alias)

+

+(Appears on:VolumeSnapshotContentSpec) +

+
+

SourceVolumeMode describes the volume mode of the source volume from which a snapshot was created.

+
+ + + + + + + + + + + + +
ValueDescription

"Block"

SourceVolumeModeBlock describes a snapshot that is created from a raw block volume.

+

"Filesystem"

SourceVolumeModeFilesystem describes a snapshot that is created from a filesystem volume.

+
+

VolumeSnapshotContentSource +

+

+(Appears on:VolumeSnapshotContentSpec) +

+
+

VolumeSnapshotContentSource represents the CSI source of a snapshot. +Exactly one of its members must be set. +Members in VolumeSnapshotContentSource are immutable. +TODO(xiangqian): Add a webhook to ensure that VolumeSnapshotContentSource members +will be immutable once specified.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotContentSpec +

+

+(Appears on:VolumeSnapshotContent) +

+
+

VolumeSnapshotContentSpec is the specification of a VolumeSnapshotContent

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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
+ + +SourceVolumeMode + + +		 +(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.

+
+

VolumeSnapshotContentStatus +

+

+(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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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 date +%s%N returns the current time in nanoseconds +since 1970-01-01 00:00:00 UTC.

+
+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.

+
+

VolumeSnapshotError +

+

+(Appears on:VolumeSnapshotContentStatus, VolumeSnapshotStatus) +

+
+

VolumeSnapshotError describes an error encountered during snapshot creation.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotSource +

+

+(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.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotSpec +

+

+(Appears on:VolumeSnapshot) +

+
+

VolumeSnapshotSpec describes the common attributes of a volume snapshot.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotStatus +

+

+(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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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 041cd467. +

\ No newline at end of file diff --git a/hack/gen-api.json b/hack/gen-api.json new file mode 100644 index 00000000..83febcb4 --- /dev/null +++ b/hack/gen-api.json @@ -0,0 +1,28 @@ +{ + "hideMemberFields": [ + "TypeMeta" + ], + "hideTypePatterns": [ + "ParseError$", + "List$" + ], + "externalPackages": [ + { + "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" + }, + { + "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis|apimachinery/pkg/api)/", + "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" + }, + { + "typeMatchPrefix": "^k8s\\.io/api/core/v1/\\.ObjectReference$", + "docsURLTemplate": "https://pkg.go.dev/k8s.io/api/core/v1#ObjectReference" + } + ], + "typeDisplayNamePrefixOverrides": { + "k8s.io/api/": "Kubernetes ", + "k8s.io/apimachinery/pkg/apis/": "Kubernetes " + }, + "markdownDisabled": false +} diff --git a/hack/gen-api.sh b/hack/gen-api.sh new file mode 100755 index 00000000..24f7426c --- /dev/null +++ b/hack/gen-api.sh @@ -0,0 +1,43 @@ +#!/bin/sh -e + +# This script uses the gen-crd-api-reference-docs tool to generate a markdown +# document for the CSI CRD API. +# +# It clones the gen-crd-reference-docs and external-snapshotter repositories +# into two separate temporary folders. The references of the repositories are +# defaulted to master. They can be overwritten by using the: +# - CSI_REF +# - GEN_CRD_REF +# variables. +# +# The tool parses the Go files in the external-snapshotter's CRD package and +# writes the content to the book/src/api.md file. The configuration of the tool +# can be found in the hack/gen-api.json file. + +GEN_TOOL_REF=${GEN_TOOL_REF:-master} +CSI_REF=${CSI_REF:-master} + +curr_dir=$(pwd) +gen_tool_dir=$(mktemp -d) +csi_dir=$(mktemp -d) +# trap 'rm -rf "$gen_tool_dir" "$csi_dir"' EXIT + +config_path=$(find . -iname "*gen-api.json") + +git clone git@github.com:ahmetb/gen-crd-api-reference-docs.git "$gen_tool_dir" +git clone git@github.com:kubernetes-csi/external-snapshotter.git "$csi_dir" + +cd "$gen_tool_dir" +git co "$GEN_TOOL_REF" +go build "$gen_tool_dir" + +cd "$csi_dir" +git co "$CSI_REF" +$gen_tool_dir/gen-crd-api-reference-docs \ + -config="$curr_dir/$config_path" \ + -api-dir="./client/apis/volumesnapshot/v1" \ + -template-dir="$gen_tool_dir/template" \ + -out-file="out.html" + +# add title to page +printf "# API Documentation\n\n%s" "$(cat out.html)" > "$curr_dir"/book/src/api.md From 83494a5e54acb247c7d47a5e2f2e0da9d6006953 Mon Sep 17 00:00:00 2001 From: Ivan Sim Date: Wed, 13 Apr 2022 20:17:04 -0700 Subject: [PATCH 2/3] Move volume snapshot CRDs to the new 'api' subfolder Signed-off-by: Ivan Sim --- README.md | 2 +- book/src/SUMMARY.md | 4 +- book/src/api.md | 1058 +------------------------------ book/src/api/volume-snapshot.md | 1036 ++++++++++++++++++++++++++++++ hack/gen-api.sh | 6 +- 5 files changed, 1046 insertions(+), 1060 deletions(-) create mode 100644 book/src/api/volume-snapshot.md diff --git a/README.md b/README.md index bd590af2..957addcb 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ To update the [CRD API documentation](book/src/api.md), run: ./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 [CSI CRD API](https://github.com/kubernetes-csi/external-snapshotter/tree/master/client/apis/volumesnapshot/v1). See the script for more information and supported configuration. +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 diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 377e2640..e09d87db 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -46,6 +46,6 @@ - [Unit Testing](unit-testing.md) - [Functional Testing](functional-testing.md) - [Drivers](drivers.md) -- [Reference]() - - [API Docs](api.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 index 28ebc444..fcc64b89 100644 --- a/book/src/api.md +++ b/book/src/api.md @@ -1,1055 +1,5 @@ -# API Documentation +# API Reference -

Packages:

- -

snapshot.storage.k8s.io/v1

-Resource Types: - -

VolumeSnapshot -

-
-

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.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-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.

-
-
- - - - - - - - - -
-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.

-
-
-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 -

-
-

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

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-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 -

-
-

VolumeSnapshotContent represents the actual “on-disk” snapshot object in the -underlying storage system

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-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.

-
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
-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
- - -SourceVolumeMode - - -		 -(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.

-
-
-status
- - -VolumeSnapshotContentStatus - - -		 -(Optional) -

status represents the current information of a snapshot.

-
-

DeletionPolicy -(string alias)

-

-(Appears on:VolumeSnapshotClass, VolumeSnapshotContentSpec) -

-
-

DeletionPolicy describes a policy for end-of-life maintenance of volume snapshot contents

-
- - - - - - - - - - - - -
ValueDescription

"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.

-
-

SourceVolumeMode -(string alias)

-

-(Appears on:VolumeSnapshotContentSpec) -

-
-

SourceVolumeMode describes the volume mode of the source volume from which a snapshot was created.

-
- - - - - - - - - - - - -
ValueDescription

"Block"

SourceVolumeModeBlock describes a snapshot that is created from a raw block volume.

-

"Filesystem"

SourceVolumeModeFilesystem describes a snapshot that is created from a filesystem volume.

-
-

VolumeSnapshotContentSource -

-

-(Appears on:VolumeSnapshotContentSpec) -

-
-

VolumeSnapshotContentSource represents the CSI source of a snapshot. -Exactly one of its members must be set. -Members in VolumeSnapshotContentSource are immutable. -TODO(xiangqian): Add a webhook to ensure that VolumeSnapshotContentSource members -will be immutable once specified.

-
- - - - - - - - - - - - - - - - - -
FieldDescription
-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.

-
-

VolumeSnapshotContentSpec -

-

-(Appears on:VolumeSnapshotContent) -

-
-

VolumeSnapshotContentSpec is the specification of a VolumeSnapshotContent

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-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
- - -SourceVolumeMode - - -		 -(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.

-
-

VolumeSnapshotContentStatus -

-

-(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.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-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 date +%s%N returns the current time in nanoseconds -since 1970-01-01 00:00:00 UTC.

-
-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.

-
-

VolumeSnapshotError -

-

-(Appears on:VolumeSnapshotContentStatus, VolumeSnapshotStatus) -

-
-

VolumeSnapshotError describes an error encountered during snapshot creation.

-
- - - - - - - - - - - - - - - - - -
FieldDescription
-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.

-
-

VolumeSnapshotSource -

-

-(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.

-
- - - - - - - - - - - - - - - - - -
FieldDescription
-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.

-
-

VolumeSnapshotSpec -

-

-(Appears on:VolumeSnapshot) -

-
-

VolumeSnapshotSpec describes the common attributes of a volume snapshot.

-
- - - - - - - - - - - - - - - - - -
FieldDescription
-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.

-
-

VolumeSnapshotStatus -

-

-(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.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldDescription
-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 041cd467. -

\ No newline at end of file +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..b70f77b8 --- /dev/null +++ b/book/src/api/volume-snapshot.md @@ -0,0 +1,1036 @@ +# Volume Snapshot + +

Packages:

+ +

snapshot.storage.k8s.io/v1

+Resource Types: + +

VolumeSnapshot +

+
+

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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+
+ + + + + + + + + +
+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.

+
+
+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 +

+
+

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

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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 +

+
+

VolumeSnapshotContent represents the actual “on-disk” snapshot object in the +underlying storage system

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
+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.

+
+
+status
+ + +VolumeSnapshotContentStatus + + +		 +(Optional) +

status represents the current information of a snapshot.

+
+

DeletionPolicy +(string alias)

+

+(Appears on:VolumeSnapshotClass, VolumeSnapshotContentSpec) +

+
+

DeletionPolicy describes a policy for end-of-life maintenance of volume snapshot contents

+
+ + + + + + + + + + + + +
ValueDescription

"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.

+
+

VolumeSnapshotContentSource +

+

+(Appears on:VolumeSnapshotContentSpec) +

+
+

VolumeSnapshotContentSource represents the CSI source of a snapshot. +Exactly one of its members must be set. +Members in VolumeSnapshotContentSource are immutable. +TODO(xiangqian): Add a webhook to ensure that VolumeSnapshotContentSource members +will be immutable once specified.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotContentSpec +

+

+(Appears on:VolumeSnapshotContent) +

+
+

VolumeSnapshotContentSpec is the specification of a VolumeSnapshotContent

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotContentStatus +

+

+(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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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 date +%s%N returns the current time in nanoseconds +since 1970-01-01 00:00:00 UTC.

+
+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.

+
+

VolumeSnapshotError +

+

+(Appears on:VolumeSnapshotContentStatus, VolumeSnapshotStatus) +

+
+

VolumeSnapshotError describes an error encountered during snapshot creation.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotSource +

+

+(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.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotSpec +

+

+(Appears on:VolumeSnapshot) +

+
+

VolumeSnapshotSpec describes the common attributes of a volume snapshot.

+
+ + + + + + + + + + + + + + + + + +
FieldDescription
+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.

+
+

VolumeSnapshotStatus +

+

+(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.

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+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 edf5a7b3. +

\ No newline at end of file diff --git a/hack/gen-api.sh b/hack/gen-api.sh index 24f7426c..05e32d82 100755 --- a/hack/gen-api.sh +++ b/hack/gen-api.sh @@ -11,8 +11,8 @@ # variables. # # The tool parses the Go files in the external-snapshotter's CRD package and -# writes the content to the book/src/api.md file. The configuration of the tool -# can be found in the hack/gen-api.json file. +# writes the content to the book/api folder. The configuration of the tool can +# be found in the hack/gen-api.json file. GEN_TOOL_REF=${GEN_TOOL_REF:-master} CSI_REF=${CSI_REF:-master} @@ -40,4 +40,4 @@ $gen_tool_dir/gen-crd-api-reference-docs \ -out-file="out.html" # add title to page -printf "# API Documentation\n\n%s" "$(cat out.html)" > "$curr_dir"/book/src/api.md +printf "# Volume Snapshot\n\n%s" "$(cat out.html)" > "$curr_dir"/book/src/api/volume-snapshot.md From 670decf770e5bafc5c73957db3371153c5be7194 Mon Sep 17 00:00:00 2001 From: Ivan Sim Date: Sun, 17 Apr 2022 20:13:45 -0700 Subject: [PATCH 3/3] Re-generate doc to include latest 'master' updates Signed-off-by: Ivan Sim --- book/src/api/volume-snapshot.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/book/src/api/volume-snapshot.md b/book/src/api/volume-snapshot.md index b70f77b8..3f4b5e06 100644 --- a/book/src/api/volume-snapshot.md +++ b/book/src/api/volume-snapshot.md @@ -458,9 +458,7 @@ state on release from its volume snapshot.

VolumeSnapshotContentSource represents the CSI source of a snapshot. Exactly one of its members must be set. -Members in VolumeSnapshotContentSource are immutable. -TODO(xiangqian): Add a webhook to ensure that VolumeSnapshotContentSource members -will be immutable once specified.

+Members in VolumeSnapshotContentSource are immutable.

@@ -1032,5 +1030,5 @@ snapshot creation. Upon success, this error field will be cleared.

Generated with gen-crd-api-reference-docs -on git commit edf5a7b3. +on git commit b20011c8.

\ No newline at end of file