From 129b3f46647d8d982ea8d450d9669b2519ea8fb4 Mon Sep 17 00:00:00 2001
From: alegrey91 <ale_grey_91@hotmail.it>
Date: Fri, 2 Jul 2021 08:58:23 +0200
Subject: [PATCH] docs(velero): add documentation about velero-restore script

---
 docs/operator/use-cases/overview.md           |  1 +
 .../use-cases/velero-backup-restoration.md    | 19 +++++++++++++++++++
 hack/velero-restore.sh                        |  5 +++++
 3 files changed, 25 insertions(+)
 create mode 100644 docs/operator/use-cases/velero-backup-restoration.md

diff --git a/docs/operator/use-cases/overview.md b/docs/operator/use-cases/overview.md
index a085e01c..50d37646 100644
--- a/docs/operator/use-cases/overview.md
+++ b/docs/operator/use-cases/overview.md
@@ -39,6 +39,7 @@ Bill, at Acme Corp. can use Capsule to address any of the following scenarios:
 * [Taint Namespaces](./taint-namespaces.md)
 * [Assign multiple Tenants to an owner](./multiple-tenants.md)
 * [Cordoning a Tenant](./cordoning-tenant.md)
+* [Velero Backup Restoration](./velero-backup-restoration.md)
 
 > NB: as we improve Capsule, more use cases about multi-tenancy and cluster governance will be covered.
 
diff --git a/docs/operator/use-cases/velero-backup-restoration.md b/docs/operator/use-cases/velero-backup-restoration.md
new file mode 100644
index 00000000..1c9ca83e
--- /dev/null
+++ b/docs/operator/use-cases/velero-backup-restoration.md
@@ -0,0 +1,19 @@
+# Velero Backup Restoration
+
+Velero is a backup system that perform disaster recovery, and migrate Kubernetes cluster resources and persistent volumes.
+
+Using this in a Kubernetes cluster where Capsule is installed can lead to an incomplete restore of the cluster's Tenants. This is due to the fact that Velero omits the `ownerReferences` section from the tenant's namespace manifests when backup them.
+
+To avoid this problem you can use the script `velero-restore.sh` under the `hack/` folder.
+
+Below are some examples on how to use the script to avoid incomplete restorations.
+
+## Getting Started
+
+In case of a data loss, the right thing to do is to restore the cluster with **Velero** at first. Once Velero has finished, you can proceed using the script to complete the restoration.
+
+```bash
+./velero-restore.sh --kubeconfing /path/to/your/kubeconfig restore
+```
+
+Running this command, we are going to patch the tenant's namespaces manifests that are actually `ownerReferences`-less. Once the command has finished its run, you got the cluster back.
\ No newline at end of file
diff --git a/hack/velero-restore.sh b/hack/velero-restore.sh
index 8cf3843a..3f59fa17 100755
--- a/hack/velero-restore.sh
+++ b/hack/velero-restore.sh
@@ -14,6 +14,11 @@ KUBECFGFILE="~/.kube/config"
 KUBEOPTIONS="--kubeconfig=$KUBECFGFILE"
 TMPDIR=/tmp
 
+# Print usage to stdout.
+# Arguments:
+#   None
+# Outputs:
+#   print usage with examples.
 usage () {
    printf "Usage: $0 [flags] commands\n" 
    printf "Flags:\n"