|
| 1 | +# Block Volume Snapshot and Restore using CSI |
| 2 | + |
| 3 | +## Setup |
| 4 | + |
| 5 | +1. Make sure you have installed [CCM](../README.md) and [CSI](../container-storage-interface.md) version v1.26.0 or later |
| 6 | + |
| 7 | +A Kubernetes volume snapshot is a snapshot of a persistent volume on a storage system. You can use a volume snapshot to provision a new persistent volume. For more information, about Kubernetes volume snapshots, see [Volume Snapshots][1] in the Kubernetes documentation. |
| 8 | + |
| 9 | +You can use the CSI volume plugin to provision a volume snapshot in one of two ways: |
| 10 | + |
| 11 | +Dynamically: You can request the creation of a backup of the block volume provisioning a persistent volume. You specify the persistent volume claim using the VolumeSnapshot object, and you specify the parameters to use to create the block volume backup using the VolumeSnapshotClass object. See [Creating Dynamically Provisioned Volume Snapshots](#creating-dynamically-provisioned-volume-snapshots). |
| 12 | + |
| 13 | +Statically: You can provide details of an existing block volume backup using the VolumeSnapshotContent object. See [Creating Statically Provisioned Volume Snapshots](#creating-statically-provisioned-volume-snapshots) |
| 14 | + |
| 15 | +Note the following when creating and using volume snapshots: |
| 16 | + |
| 17 | +* In the case of dynamic volume backups, the CSI volume plugin creates a new block volume backup to provision a dynamic volume snapshot in the same compartment as the cluster. In the case of static volume snapshots, the block volume backup provisioning a static volume snapshot can be in a different compartment to the cluster, provided appropriate policy statements exist to enable the cluster to access that other compartment (see [Prerequisites for Creating Volume Snapshots](#prerequisites-for-creating-volume-snapshots)). |
| 18 | +* You cannot use the CSI volume plugin to re-populate an existing volume with data. In other words, you cannot restore (revert) data in an existing persistent volume to an earlier state by changing the volume snapshot specified in the persistent volume claim's manifest. You can only use the CSI volume plugin to populate a new volume with data. |
| 19 | +* Cross-namespace snapshots are not supported. |
| 20 | + |
| 21 | +### Prerequisites for Creating Volume Snapshots |
| 22 | + |
| 23 | +* The VolumeSnapshot, VolumeSnapshotContent, and VolumeSnapshotClass objects are not part of the core Kubernetes API. Therefore, before you can create volume snapshots using the CSI volume plugin, you have to install the necessary CRD (Custom Resource Definition) files on the cluster, by running the following commands: |
| 24 | + |
| 25 | +```bash |
| 26 | +kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml |
| 27 | +kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshotcontents.yaml |
| 28 | +kubectl apply -f https://raw.githubusercontent.com/kubernetes-csi/external-snapshotter/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshots.yaml |
| 29 | +``` |
| 30 | + |
| 31 | +* If you want to use a statically provisioned volume snapshot to provision a new persistent volume, and the underlying block volume backup is in a different compartment to the cluster, appropriate policy statements must exist to enable the cluster to access the block volume backups in that other compartment. For example: |
| 32 | + |
| 33 | +```bash |
| 34 | +ALLOW any-user to manage volume-backups in compartment <compartment-name> where request.principal.type = 'cluster' |
| 35 | +ALLOW any-user to use volumes in compartment <compartment-name> where request.principal.type = 'cluster' |
| 36 | +``` |
| 37 | + |
| 38 | +## Creating Dynamically Provisioned Volume Snapshots |
| 39 | + |
| 40 | +To dynamically provision a volume snapshot by creating a backup of the block volume provisioning a persistent volume claim, you first define a VolumeSnapshotClass object that specifies the type of block volume backup to create. Having created the VolumeSnapshotClass object, you then define a VolumeSnapshot object that uses the VolumeSnapshotClass. You use the VolumeSnapshot object to specify the persistent volume claim provisioned by the block volume that you want to back up. |
| 41 | + |
| 42 | +For example, you define a persistent volume claim named sample-pvc in a file called csi-mypvctobackup.yaml, provisioned by a block volume: |
| 43 | + |
| 44 | +``` |
| 45 | +apiVersion: v1 |
| 46 | +kind: PersistentVolumeClaim |
| 47 | +metadata: |
| 48 | + name: sample-pvc |
| 49 | +spec: |
| 50 | + accessModes: |
| 51 | + - ReadWriteOnce |
| 52 | + storageClassName: "oci-bv" |
| 53 | + resources: |
| 54 | + requests: |
| 55 | + storage: 50Gi |
| 56 | +``` |
| 57 | +Create the persistent volume claim: |
| 58 | + |
| 59 | +``` |
| 60 | +kubectl create -f csi-mypvctobackup.yaml |
| 61 | +``` |
| 62 | + |
| 63 | +You can use the persistent volume claim when defining other objects, such as pods. For example, the following pod definition instructs the system to use the sample-pvc persistent volume claim as the nginx volume, which is mounted by the pod at /sample-volume. |
| 64 | + |
| 65 | +``` |
| 66 | +apiVersion: v1 |
| 67 | +kind: Pod |
| 68 | +metadata: |
| 69 | + name: sample-pod |
| 70 | +spec: |
| 71 | + containers: |
| 72 | + - name: sample-nginx |
| 73 | + image: nginx |
| 74 | + ports: |
| 75 | + - containerPort: 80 |
| 76 | + name: "http-server" |
| 77 | + volumeMounts: |
| 78 | + - mountPath: "/usr/share/nginx/html" |
| 79 | + name: sample-volume |
| 80 | + volumes: |
| 81 | + - name: sample-volume |
| 82 | + persistentVolumeClaim: |
| 83 | + claimName: sample-pvc |
| 84 | +``` |
| 85 | + |
| 86 | +Having created the new pod, the persistent volume claim is bound to a new persistent volume provisioned by a block volume. |
| 87 | + |
| 88 | +In readiness for creating a backup of the block volume provisioning the persistent volume claim, you set parameters for the block volume backup by defining a VolumeSnapshotClass object named my-snapclass in a file called csi-mysnapshotclass.yaml: |
| 89 | + |
| 90 | +``` |
| 91 | +apiVersion: snapshot.storage.k8s.io/v1 |
| 92 | +kind: VolumeSnapshotClass |
| 93 | +metadata: |
| 94 | + name: my-snapclass |
| 95 | +driver: blockvolume.csi.oraclecloud.com |
| 96 | +parameters: |
| 97 | + backupType: full |
| 98 | +deletionPolicy: Delete |
| 99 | +``` |
| 100 | + |
| 101 | +where: |
| 102 | + |
| 103 | +* driver: blockvolume.csi.oraclecloud.com specifies the CSI volume plugin to provision VolumeSnapshot objects. |
| 104 | +* parameters.backupType: full specifies a block volume backup is to include all changes since the block volume was created. Specify incremental to create a backup with only the changes since the last backup. Note that for data recovery purposes, there is no functional difference between an incremental backup and a full backup. See [Volume Backup Types][3]. |
| 105 | +* deletionPolicy: Delete specifies what happens to a block volume backup if the associated VolumeSnapshot object is deleted. Specify Retain to keep a block volume backup if the associated VolumeSnapshot object is deleted. |
| 106 | + |
| 107 | +By default, the same freeform tags and defined tags that were applied to the source block volume are applied to the block volume backup. However, you can use annotations to apply additional tags to the block volume backup (see Tagging Block Volume Backups). |
| 108 | + |
| 109 | +Create the VolumeSnapshotClass object: |
| 110 | + |
| 111 | +``` |
| 112 | +kubectl create -f csi-mysnapshotclass.yaml |
| 113 | +``` |
| 114 | + |
| 115 | +To create a backup of the block volume provisioning the persistent volume claim, you then define a VolumeSnapshot object as my-snapshot in a file called csi-mysnapshot.yaml: |
| 116 | + |
| 117 | +``` |
| 118 | +apiVersion: snapshot.storage.k8s.io/v1 |
| 119 | +kind: VolumeSnapshot |
| 120 | +metadata: |
| 121 | + name: my-snapshot |
| 122 | + namespace: default |
| 123 | +spec: |
| 124 | + volumeSnapshotClassName: my-snapclass |
| 125 | + source: |
| 126 | + persistentVolumeClaimName: sample-pvc |
| 127 | +``` |
| 128 | + |
| 129 | +where: |
| 130 | + |
| 131 | +* volumeSnapshotClassName: my-snapclass specifies my-snapclass as the VolumeSnapshotClass object from which to obtain parameters to use when creating the block volume backup. Note that you cannot change volumeSnapshotClassName after you have created the VolumeSnapshot object (you have to create a new VolumeSnapshot object). |
| 132 | +* persistentVolumeClaimName: sample-pvc specifies sample-pvc as the persistent volume claim based on the block volume for which you want to create a block volume backup. Note that you cannot change the source after you have created the VolumeSnapshot object (you have to create a new VolumeSnapshot object). |
| 133 | + |
| 134 | +Create the VolumeSnapshot object: |
| 135 | + |
| 136 | +``` |
| 137 | +kubectl create -f csi-mysnapshot.yaml |
| 138 | +``` |
| 139 | + |
| 140 | +The VolumeSnapshot object is created and provisioned by a new block volume backup. You can use the volume snapshot to provision a new persistent volume (see [Using a Volume Snapshot to Provision a New Volume](#using-a-volume-snapshot-to-provision-a-new-volume)). |
| 141 | + |
| 142 | +## Creating Statically Provisioned Volume Snapshots |
| 143 | + |
| 144 | +To statically provision a volume snapshot from an existing block volume backup, you first create the block volume backup (see [Backing Up a Volume][2]). |
| 145 | + |
| 146 | +Having created the block volume backup, define a VolumeSnapshotContent object and specify details (including the OCID) of the existing block volume backup. You can then define a VolumeSnapshot object and specify the VolumeSnapshotContent object that provides details of the existing block volume backup. |
| 147 | + |
| 148 | +For example, you define the VolumeSnapshotContent object as my-static-snapshot-content in a file called csi-mystaticsnapshotcontent.yaml: |
| 149 | + |
| 150 | +``` |
| 151 | +apiVersion: snapshot.storage.k8s.io/v1 |
| 152 | +kind: VolumeSnapshotContent |
| 153 | +metadata: |
| 154 | + name: my-static-snapshot-content |
| 155 | +spec: |
| 156 | + deletionPolicy: Retain |
| 157 | + driver: blockvolume.csi.oraclecloud.com |
| 158 | + source: |
| 159 | + snapshotHandle: ocid1.volumebackup.oc1.iad.aaaaaa______xbd |
| 160 | + volumeSnapshotRef: |
| 161 | + name: my-static-snapshot |
| 162 | + namespace: default |
| 163 | +``` |
| 164 | + |
| 165 | +where: |
| 166 | +* deletionPolicy: Retain specifies what happens to a block volume backup if the associated VolumeSnapshot object is deleted. Specify Delete to delete a block volume backup if the associated VolumeSnapshot object is deleted. |
| 167 | +* driver: blockvolume.csi.oraclecloud.com specifies to use the CSI volume plugin to provision VolumeSnapshot objects. |
| 168 | +* snapshotHandle: ocid1.volumebackup.oc1.iad.aaaaaa______xbd specifies the OCID of the existing block volume backup. |
| 169 | +* volumeSnapshotRef.name: my-static-snapshot specifies the name of the corresponding VolumeSnapshot object to be provisioned from the existing block volume backup. This field is required. Note that the VolumeSnapshot object need not exist when you create the VolumeSnapshotClass object. |
| 170 | +* namespace: default specifies the namespace containing the corresponding VolumeSnapshot object to be provisioned from the existing block volume backup. This field is required. |
| 171 | + |
| 172 | +Create the VolumeSnapshotClass object: |
| 173 | + |
| 174 | +``` |
| 175 | +kubectl create -f csi-mystaticsnapshotcontent.yaml |
| 176 | +``` |
| 177 | + |
| 178 | +You define the statically provisioned VolumeSnapshot object as my-static-snapshot in a file called csi-mystaticsnapshot.yaml: |
| 179 | + |
| 180 | +``` |
| 181 | +apiVersion: snapshot.storage.k8s.io/v1 |
| 182 | +kind: VolumeSnapshot |
| 183 | +metadata: |
| 184 | + name: my-static-snapshot |
| 185 | +spec: |
| 186 | + source: |
| 187 | + volumeSnapshotContentName: static-snapshot-content |
| 188 | +``` |
| 189 | + |
| 190 | +where VolumeSnapshotContentName: static-snapshot-content specifies the name of the VolumeSnapshotContent object you created previously. Note that you cannot change the source after you have created the VolumeSnapshot object (you have to create a new VolumeSnapshot object). |
| 191 | + |
| 192 | +Create the VolumeSnapshot object: |
| 193 | +``` |
| 194 | +kubectl create -f csi-mystaticsnapshot.yaml |
| 195 | +``` |
| 196 | +The VolumeSnapshot object is created and provisioned by the block volume backup specified in the VolumeSnapshotContent object. You can use the volume snapshot to provision a new persistent volume (see [Using a Volume Snapshot to Provision a New Volume](#using-a-volume-snapshot-to-provision-a-new-volume)). |
| 197 | + |
| 198 | +## Using a Volume Snapshot to Provision a New Volume |
| 199 | + |
| 200 | +Having created a dynamically provisioned or statically provisioned volume snapshot, you can specify the volume snapshot as the datasource for a persistent volume claim to provision a new persistent volume. |
| 201 | + |
| 202 | +For example, you define a persistent volume claim named pvc-fromsnapshot in a file called csi-mypvcfromsnapshot.yaml, provisioned by a volume snapshot named test-snapshot: |
| 203 | + |
| 204 | +``` |
| 205 | +apiVersion: v1 |
| 206 | +kind: PersistentVolumeClaim |
| 207 | +metadata: |
| 208 | + name: pvc-fromsnapshot |
| 209 | + namespace: default |
| 210 | +spec: |
| 211 | + storageClassName: oci-bv |
| 212 | + dataSource: |
| 213 | + name: test-snapshot |
| 214 | + kind: VolumeSnapshot |
| 215 | + apiGroup: snapshot.storage.k8s.io |
| 216 | + accessModes: |
| 217 | + - ReadWriteOnce |
| 218 | + resources: |
| 219 | + requests: |
| 220 | + storage: 50Gi |
| 221 | +``` |
| 222 | + |
| 223 | +where: |
| 224 | + |
| 225 | +* datasource.name: test-snapshot specifies test-snapshot as the name of the VolumeSnapshot object to use as the data source for the persistent volume. |
| 226 | +* datasource.apiGroup: snapshot.storage.k8s.io specifies the version of the Kubernetes snapshot storage API to use. |
| 227 | + |
| 228 | +Create the persistent volume claim: |
| 229 | +``` |
| 230 | +kubectl create -f csi-mypvcfromsnapshot.yaml |
| 231 | +``` |
| 232 | +When the persistent volume claim is used to provision another object (such as a pod), a persistent volume is created and the VolumeSnapshot object you specified is used to populate the underlying block volume. For example, you could create a new pod from the following pod definition that instructs the system to use the pvc-fromsnapshot PVC as the nginx volume, which is mounted by the pod at /data. |
| 233 | + |
| 234 | +``` |
| 235 | +apiVersion: v1 |
| 236 | +kind: Pod |
| 237 | +metadata: |
| 238 | + name: sample-pod-restore |
| 239 | +spec: |
| 240 | + containers: |
| 241 | + - name: nginx |
| 242 | + image: nginx:latest |
| 243 | + ports: |
| 244 | + - name: http |
| 245 | + containerPort: 80 |
| 246 | + volumeMounts: |
| 247 | + - name: data |
| 248 | + mountPath: /data |
| 249 | + volumes: |
| 250 | + - name: data |
| 251 | + persistentVolumeClaim: |
| 252 | + claimName: pvc-fromsnapshot |
| 253 | +``` |
| 254 | + |
| 255 | +Having created the new pod, the persistent volume claim is bound to a new persistent volume provisioned by a new block volume populated by the VolumeSnapshot object. |
| 256 | + |
| 257 | +[1]: https://kubernetes.io/docs/concepts/storage/volume-snapshots/ |
| 258 | +[2]: https://docs.oracle.com/en-us/iaas/Content/Block/Tasks/backingupavolume.htm#Backing_Up_a_Volume |
| 259 | +[3]: https://docs.oracle.com/en-us/iaas/Content/Block/Concepts/blockvolumebackups.htm#backuptype |
0 commit comments