snapshot/restore documentation

Signed-off-by: Michael Henriksen <[email protected]>

docs/snapshot-restore.md

@@ -0,0 +1,80 @@
+# KubeVirt Snapshot and Restore API
+
+The `snapshot.kubevirt.io` API Group defines resources for snapshotting and restoring KubeVirt `VirtualMachines`
+
+## Prerequesites
+
+### VolumeSnapshotClass
+
+KubeVirt leverages the `VolumeSnapshot` functionality of Kubernetes [CSI drivers](https://kubernetes-csi.github.io/docs/drivers.html) for capturing persistent `VirtualMachine` state.  So, you should make sure that your `VirtuallMachine` uses `DataVolumes` or `PersistentVolumeClaims` backed by a `StorageClass` that supports `VolumeSnapshots` and a `VolumeSnapshotClass` is properly configured for that `StorageClass`.
+
+To list `VolumeSnapshotClasses`:
+
+```bash
+kubectl get volumesnapshotclass
+```
+
+Make sure that the `provisioner` property of your `StorageClass` matches the `driver` property of the `VolumeSnapshotClass`
+
+Even if you have no `VlumeSnapshotClasses` in your cluster, `VirtualMachineSnapshots` are not totally useless.  They will still backup your `VirtualMachine` configuration.
+
+### Snapshot Feature Gate
+
+Snapshot/Restore are currently considered alpha features and are disabled by default.
+
+```bash
+kubectl patch -n kubevirt kubevirt kubevirt -p '{"spec": {"configuration": { "developerConfiguration": { "featureGates": [ "Snapshot" ] }}}}' -o json --type merge
+```
+
+## Snapshot a VirtualMachine
+
+To snapshot a `VirtualMachine` named `larry`, apply the following yaml.
+
+\* It is currently a requirement that `VirtualMachines` are halted before taking a snapshot.
+
+```yaml
+apiVersion: snapshot.kubevirt.io/v1alpha1
+kind: VirtualMachineSnapshot
+metadata:
+  name: snap-larry
+spec:
+  source:
+    apiGroup: kubevirt.io
+    kind: VirtualMachine
+    name: larry
+```
+
+To wait for a snapshot to complete, execute:
+
+```bash
+kubectl wait vmsnapshot snap-larry --for condition=Ready
+```
+
+## Restoring a VirtualMachine
+
+To restore the `VirtualMachine` `larry` from `VirtualMachineSnapshot` `snap-larry`, apply the following yaml.
+
+```yaml
+apiVersion: snapshot.kubevirt.io/v1alpha1
+kind: VirtualMachineRestore
+metadata:
+  name: restore-larry
+spec:
+  target:
+    apiGroup: kubevirt.io
+    kind: VirtualMachine
+    name: larry
+  virtualMachineSnapshotName: snap-larry
+```
+
+To wait for a restore to complete, execute:
+
+```bash
+kubectl wait vmrestore restore-larry --for condition=Ready
+```
+
+## Cleanup
+
+Keep `VirtualMachineSnapshots` (and their corresponding `VirtualMachineSnapshotContents`) around as long as you may want to restore from them again.
+
+Feel free to delete `larry-restore` as it is not needed once the restore is complete.