diff --git a/design/pv-cloning.md b/design/pv-cloning.md new file mode 100644 index 000000000..9d4828ee5 --- /dev/null +++ b/design/pv-cloning.md @@ -0,0 +1,54 @@ +# Cloning PVs While Remapping Namespaces + +Status: Approved + +Velero supports restoring resources into different namespaces than they were backed up from. +This enables a user to, among other things, clone a namespace within a cluster. +However, if the namespace being cloned uses persistent volume claims, Velero cannot currently create a second copy of the original persistent volume when restoring. +This limitation is documented in detail in [issue #192](https://github.com/heptio/velero/issues/192). +This document proposes a solution that allows new copies of persistent volumes to be created during a namespace clone. + +## Goals + +- Enable persistent volumes to be cloned when using `velero restore create --namespace-mappings ...` to create a second copy of a namespace within a cluster. + +## Non Goals + +- Cloning of persistent volumes in any scenario other than when using `velero restore create --namespace-mappings ...` flag. +- [CSI-based cloning](https://kubernetes.io/docs/concepts/storage/volume-pvc-datasource/). + +## Background + +(Omitted, see introduction) + +## High-Level Design + +During a restore, Velero will detect that it needs to assign a new name to a persistent volume being restored if and only if both of the following conditions are met: +- the persistent volume is claimed by a persistent volume claim in a namespace that's being remapped using `velero restore create --namespace-mappings ...` +- a persistent volume already exists in the cluster with the original name + +If these conditions exist, Velero will give the persistent volume a new arbitrary name before restoring it. +It will also update the `spec.volumeName` of the related persistent volume claim. + +## Detailed Design + +In `pkg/restore/restore.go`, around [line 872](https://github.com/heptio/velero/blob/master/pkg/restore/restore.go#L872), Velero has special-case code for persistent volumes. +This code will be updated to check for the two preconditions described in the previous section. +If the preconditions are met, the object will be given a new name. +The persistent volume will also be annotated with the original name, e.g. `velero.io/original-pv-name=NAME`. +Importantly, the name change will occur **before** [line 890](https://github.com/heptio/velero/blob/master/pkg/restore/restore.go#L890), where Velero checks to see if it should restore the persistent volume. +Additionally, the old and new persistent volume names will be recorded in a new field that will be added to the `context` struct, `renamedPVs map[string]string`. + +In the special-case code for persistent volume claims starting on [line 987](https://github.com/heptio/velero/blob/master/pkg/restore/restore.go#L987), Velero will check to see if the claimed persistent volume has been renamed by looking in `ctx.renamedPVs`. +If so, Velero will update the persistent volume claim's `spec.volumeName` to the new name. + +## Alternatives Considered + +One alternative approach is to add a new CLI flag and API field for restores, e.g. `--clone-pvs`, that a user could provide to indicate they want to create copies of persistent volumes. +This approach would work fine, but it does require the user to be aware of this flag/field and to properly specify it when needed. +It seems like a better UX to detect the typical conditions where this behavior is needed, and to automatically apply it. +Additionally, the design proposed here does not preclude such a flag/field from being added later, if it becomes necessary to cover other use cases. + +## Security Considerations + +N/A