diff --git a/content/en/docs/concepts/storage/persistent-volumes.md b/content/en/docs/concepts/storage/persistent-volumes.md index f81950f7c26c9..90a7fe37935ea 100644 --- a/content/en/docs/concepts/storage/persistent-volumes.md +++ b/content/en/docs/concepts/storage/persistent-volumes.md @@ -625,6 +625,34 @@ Volume binding matrix for statically provisioned volumes: **Note:** Only statically provisioned volumes are supported for alpha release. Administrators should take care to consider these values when working with raw block devices. {{< /note >}} +## Volume Snapshot and Restore Volume from Snapshot Support + +{{< feature-state for_k8s_version="v1.12" state="alpha" >}} + +Volume snapshot feature was added to support CSI Volume Plugins only. For details, see [volume snapshots](/docs/concepts/storage/volume-snapshots/). + +To enable support for restoring a volume from a volume snapshot data source, enable the +`VolumeSnapshotDataSource` feature gate on the apiserver, controller-manager and the kubelet. + +### Create Persistent Volume Claim from Volume Snapshot +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: restore-pvc +spec: + storageClassName: csi-hostpath-sc + dataSource: + name: new-snapshot-test + kind: VolumeSnapshot + apiGroup: snapshot.storage.k8s.io + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +``` + ## Writing Portable Configuration If you're writing configuration templates or examples that run on a wide range of clusters @@ -652,4 +680,4 @@ and need persistent storage, we recommend that you use the following pattern: or the cluster has no storage system (in which case the user cannot deploy config requiring PVCs). -{{% /capture %}} \ No newline at end of file +{{% /capture %}} diff --git a/content/en/docs/concepts/storage/volume-snapshot-classes.md b/content/en/docs/concepts/storage/volume-snapshot-classes.md new file mode 100644 index 0000000000000..eacefa8797eec --- /dev/null +++ b/content/en/docs/concepts/storage/volume-snapshot-classes.md @@ -0,0 +1,63 @@ +--- +reviewers: +- jsafrane +- saad-ali +- thockin +- msau42 +title: Volume Snapshot Classes +content_template: templates/concept +weight: 30 +--- + +{{% capture overview %}} + +This document describes the concept of `VolumeSnapshotClass` in Kubernetes. Familiarity +with [volume snapshots](/docs/concepts/storage/volume-snapshots/) and +[storage classes](/docs/concepts/storage/storage-classes) is suggested. + +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + +## Introduction + +Just like `StorageClass` provides a way for administrators to describe the "classes" +of storage they offer when provisioning a volume, `VolumeSnapshotClass` provides a +way to describe the "classes" of storage when provisioning a volume snapshot. + +## The VolumeSnapshotClass Resource + +Each `VolumeSnapshotClass` contains the fields `snapshotter` and `parameters`, +which are used when a `VolumeSnapshot` belonging to the class needs to be +dynamically provisioned. + +The name of a `VolumeSnapshotClass` object is significant, and is how users can +request a particular class. Administrators set the name and other parameters +of a class when first creating `VolumeSnapshotClass` objects, and the objects cannot +be updated once they are created. + +Administrators can specify a default `VolumeSnapshotClass` just for VolumeSnapshots +that don't request any particular class to bind to. + +```yaml +apiVersion: snapshot.storage.k8s.io/v1alpha1 +kind: VolumeSnapshotClass +metadata: + name: csi-hostpath-snapclass +snapshotter: csi-hostpath +``` + +### Snapshotter + +Volume snapshot classes have a snapshotter that determines what CSI volume plugin is +used for provisioning VolumeSnapshots. This field must be specified. + +## Parameters + +Volume snapshot classes have parameters that describe volume snapshots belonging to +the volume snapshot class. Different parameters may be accepted depending on the +`snapshotter`. + +{{% /capture %}} diff --git a/content/en/docs/concepts/storage/volume-snapshots.md b/content/en/docs/concepts/storage/volume-snapshots.md new file mode 100644 index 0000000000000..3cee93fde257a --- /dev/null +++ b/content/en/docs/concepts/storage/volume-snapshots.md @@ -0,0 +1,121 @@ +--- +reviewers: +- jsafrane +- saad-ali +- thockin +- msau42 +title: Volume Snapshots +content_template: templates/concept +weight: 20 +--- + +{{% capture overview %}} + +This document describes the current state of `VolumeSnapshots` in Kubernetes. Familiarity with [persistent volumes](/docs/concepts/storage/persistent-volumes/) is suggested. + +{{% /capture %}} + +{{< toc >}} + +{{% capture body %}} + +## Introduction + +Similar to how API resources `PersistentVolume` and `PersistentVolumeClaim` are used to provision volumes for users and administrators, `VolumeSnapshotContent` and `VolumeSnapshot` API resources are provided to create volume snapshots for users and administrators. + +A `VolumeSnapshotContent` is snapshot taken from a volume in the cluster that has been provisioned by an administrator. It is a resource in the cluster just like a PersistentVolume is a cluster resource. + +A `VolumeSnapshot` is a request for snapshot of a volume by a user. It is similar to a PersistentVolumeClaim. + +While `VolumeSnapshots` allow a user to consume abstract storage resources, cluster administrators +need to be able to offer a variety of `VolumeSnapshotContents` without exposing +users to the details of how those volume snapshots should be provisioned. For these needs +there is the `VolumeSnapshotClass` resource. + + +## Lifecycle of a volume snapshot and volume snapshot content + +VolumeSnapshotContents are resources in the cluster. VolumeSnapshots are requests for those resources. The interaction between VolumeSnapshotContents and VolumeSnapshots follows this lifecycle: + +### Provisioning Volume Snapshot + +There are two ways snapshots may be provisioned: statically or dynamically. + +#### Static +A cluster administrator creates a number of VolumeSnapshotContents. They carry the details of the real storage which is available for use by cluster users. They exist in the Kubernetes API and are available for consumption. + +#### Dynamic +When none of the static VolumeSnapshotContents the administrator created matches a user's `VolumeSnapshot`, +the cluster may try to dynamically provision a volume snapshot specially for the VolumeSnapshot object. +This provisioning is based on `VolumeSnapshotClasses`: the VolumeSnapshot must request a +[volume snapshot class](/docs/concepts/storage/volume-snapshot-classes/) and +the administrator must have created and configured that class in order for dynamic +provisioning to occur. VolumeSnapshots that request the class `""` effectively disable +dynamic provisioning for themselves. + +### Binding + +A user creates, or has already created in the case of dynamic provisioning, a `VolumeSnapshot` with a specific amount of storage requested and with certain access modes. A control loop watches for new VolumeSnapshots, finds a matching VolumeSnapshotContnet (if possible), and binds them together. If a VolumeSnapshotContent was dynamically provisioned for a new VolumeSnapshot, the loop will always bind that VolumeSnapshotContent to the VolumeSnapshot. Once bound, `VolumeSnapshot` binds are exclusive, regardless of how they were bound. A VolumeSnapshot to VolumeSnapshotContent binding is a one-to-one mapping. + +VolumeSnapshots will remain unbound indefinitely if a matching VolumeSnapshotContent does not exist. VolumeSnapshots will be bound as matching VolumeSnapshotContents become available. + +### Delete + +Deletion removes both the `VolumeSnapshotContent` object from Kubernetes, as well as the associated storage asset in the external infrastructure, + +## Volume Snapshot Contents + +Each VolumeSnapshotContent contains a spec, which is the specification of the volume snapshot. + +```yaml +apiVersion: snapshot.storage.k8s.io/v1alpha1 +kind: VolumeSnapshotContent +metadata: + name: new-snapshot-content-test +spec: + snapshotClassName: csi-hostpath-snapclass + source: + name: pvc-test + kind: PersistentVolumeClaim + volumeSnapshotSource: + csiVolumeSnapshotSource: + creationTime: 1535478900692119403 + driver: csi-hostpath + restoreSize: 10Gi + snapshotHandle: 7bdd0de3-aaeb-11e8-9aae-0242ac110002 +``` + +### Class + +A VolumeSnapshotContent can have a class, which is specified by setting the +`snapshotClassName` attribute to the name of a +[VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/). +A VolumeSnapshotContent of a particular class can only be bound to VolumeSnapshots requesting +that class. A VolumeSnapshotContent with no `snapshotClassName` has no class and can only be bound +to VolumeSnapshots that request no particular class. + +## PersistentVolumeClaims + +Each VolumeSnapshot contains a spec and status, which is the specification and status of the volume snapshot. + +```yaml +apiVersion: snapshot.storage.k8s.io/v1alpha1 +kind: VolumeSnapshot +metadata: + name: new-snapshot-test +spec: + snapshotClassName: csi-hostpath-snapclass + source: + name: pvc-test + kind: PersistentVolumeClaim +``` + +### Class + +A volume snapshot can request a particular class by specifying the name of a +[VolumeSnapshotClass](/docs/concepts/storage/volume-snapshot-classes/) +using the attribute `snapshotClassName`. +Only VolumeSnapshotContents of the requested class, ones with the same `snapshotClassName` +as the VolumeSnapshot, can be bound to the VolumeSnapshot. + +{{% /capture %}}