Claim Adoption Doc

Signed-off-by: Michael Henriksen <mhenriks@redhat.com>

doc/datavolume-claim-adoption.md

@@ -0,0 +1,52 @@
+# DataVolume Claim Adoption
+
+## Summary
+
+Historically, it has been an error to create a `DataVolume` with the same name as an existing `PersistentVolumeClaim`.
+
+```bash
+✗ k get dv dv1
+Error from server (NotFound): datavolumes.cdi.kubevirt.io "dv1" not found
+
+k get pvc dv1
+NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS AGE
+dv1 Bound pvc-de8b1186-fdd1-4372-8135-9c904ecf73bc 7Gi RWX rook-ceph-block 9m7s
+
+✗ k create -f dv.yaml
+Error from server: error when creating "dv.yaml": admission webhook "datavolume-validate.cdi.kubevirt.io" denied the request: Destination PVC default/dv1 already exists
+```
+
+However in certain cases, this behavior is not desirable. It is often problematic when restoring from a backup. In that case, the restore process will typically create a new `PersistentVolumeClaim` from a `VolumeSnapshot` and then fail when the corresponding `DataVolume` is created later. In order to have a proper running application it is important to ensure all resources and their ownership relations are restored correctly.
+
+We now offer two options for `DataVolumes` to "adopt" existing `PersistentVolumeClaims`. When a `DataVolume` adopts an existing claim, the DataVolume is instantly marked `Succeeded` and an `OwnershipReference` is added to the `PersistentVolumeClaim`.
+
+## cdi.kubevirt.io/allowClaimAdoption Annotation
+
+Add this annotation to your DataVolume when you want to support claim adoption on a granular level.
+
+```yaml
+apiVersion: cdi.kubevirt.io/v1beta1
+kind: DataVolume
+metadata:
+ name: dv1
+ annotations:
+ cdi.kubevirt.io/allowClaimAdoption: "true"
+ ...
+```
+
+## DataVolumeClaimAdoption Feature Gate
+
+Enable this feature gate to have claim adoption applied automatically for all DataVolumes by default. However, the `cdi.kubevirt.io/allowClaimAdoption` annotation has precedence over the feature gate. Setting the value to `false` will disable claim adoption even if the feature gate is set.
+
+```yaml
+apiVersion: cdi.kubevirt.io/v1beta1
+kind: CDI
+metadata:
+ name: cdi
+...
+spec:
+ config:
+ featureGates:
+ - DataVolumeClaimAdoption
+ ...
+```