draft design doc for cloning PVs while remapping namespaces

Signed-off-by: Steve Kriss <[email protected]>

design/pv-cloning.md

@@ -0,0 +1,52 @@
+# Cloning PVs While Remapping Namespaces
+
+Status: Draft
+
+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. 
+
+## 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.
+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