From 68020d0e4bae0ba3bfbd0d6b2bf14a65170f07aa Mon Sep 17 00:00:00 2001
From: Steve Kriss <steve@heptio.com>
Date: Wed, 6 Jun 2018 12:01:44 -0700
Subject: [PATCH] restic quickstart doc for alpha testing

Signed-off-by: Steve Kriss <steve@heptio.com>
---
 docs/restic.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 docs/restic.md

diff --git a/docs/restic.md b/docs/restic.md
new file mode 100644
index 000000000..35814ad77
--- /dev/null
+++ b/docs/restic.md
@@ -0,0 +1,92 @@
+# Restic Integration
+
+Ark now has support for backups/restores of pod volume data using [restic][1], an open-source tool for doing
+backups and restores of filesystem data. This enables you to take backups of additional Kubernetes volume 
+types beyond those with snapshot APIs that are integrated with Ark (i.e. AWS EBS, GCP PD, Azure PD). It also lays 
+the foundation for future work to support cross-cloud stateful migrations. Note that the details of this feature,
+including names, commands, etc., may change as we receive feedback and refine our implementation. 
+
+Two new Ark custom resources have been created to support this feature: `PodVolumeBackup` and `PodVolumeRestore`.
+Additionally, a new Ark daemonset has been created that runs two controllers, one for each of the two new CRDs, on
+each node in the cluster. When an Ark backup is created that includes pods annotated for restic backup, the main Ark 
+backup controller will create a `PodVolumeBackup` custom resource that's owned by the `Backup`. The pod volume backup
+controller running on the pod's node will observe the new custom resource, and will run a restic backup of the volume 
+(accessing the volume's data via a hostPath mount of `/var/lib/kubelet/pods`). The main Ark backup controller will 
+wait for the `PodVolumeBackup` to complete before completing the Ark backup. Restores proceed similarly with some 
+minor differences to account for the fact that a new pod/volume is being created.
+
+## Setup
+
+This setup guide assumes you already have a working Ark v0.8.1+ installation. If not, go [here][2] for instructions.
+
+1. From the Ark root directory, run the following to create new custom resource definitions:
+```bash
+kubectl apply -f examples/common/00-prereqs.yaml
+```
+
+2. Run one of the following for your platform to create the daemonset:
+
+    - AWS: `kubectl apply -f examples/aws/20-restic-daemonset.yaml`
+    - Azure: `kubectl apply -f examples/azure/20-restic-daemonset.yaml`
+    - GCP: `kubectl apply -f examples/gcp/20-restic-daemonset.yaml`
+    - Minio: `kubectl apply -f examples/minio/30-restic-daemonset.yaml`
+
+3. Use the `master` image tag for both the Ark deployment and daemonset:
+```bash
+kubectl -n heptio-ark set image deployment/ark ark=gcr.io/heptio-images/ark:master
+kubectl -n heptio-ark set image daemonset/restic ark=gcr.io/heptio-images/ark:master
+```
+
+4. Create a new bucket for restic to store its data in, and give the `heptio-ark` IAM user access to it, similarly to
+the main Ark bucket you've already set up.
+
+5. Update the Ark config to specify the restic bucket:
+```bash
+kubectl -n heptio-ark get config default -o json | \
+jq '.backupStorageProvider.resticLocation = "YOUR_RESTIC_BUCKET_NAME"' |\
+kubectl apply -f -
+```
+
+6. For each namespace that has pod volumes to be backed up using restic, configure a restic encryption key using
+one of the following commands:
+
+```bash
+# provide the encryption key on the command line
+ark restic init-repository --namespace YOUR_NAMESPACE --key-data YOUR_ENCRYPTION_KEY
+```
+
+```bash
+# provide the encryption key via file
+ark restic init-repository --namespace YOUR_NAMESPACE --key-file YOUR_ENCRYPTION_KEY_FILE
+```
+
+```bash
+# have Ark generate a random encryption key
+ark restic init-repository --namespace YOUR_NAMESPACE --key-size ENCRYPTION_KEY_SIZE
+```
+
+**IMPORTANT**: store this key safely and securely. All restic backup data is encrypted and cannot be accessed
+without this key. We will be adding support for key rotation shortly.
+
+## Run
+
+1. Run the following for each pod containing a volume that you'd like to backup using restic:
+```bash
+kubectl -n YOUR_POD_NAMESPACE annotate pod/YOUR_POD_NAME backup.ark.heptio.com/backup-volumes=YOUR_VOLUME_NAME_1,YOUR_VOLUME_NAME_2,...
+```
+
+Note that this annotation can also be provided in the pod template spec if using a deployment, daemonset, etc.
+to manage your pods.
+
+2. Take an Ark backup as usual:
+```bash
+ark backup create NAME OPTIONS...
+```
+
+3. When the backup has completed, view information about your pod volume backups:
+```bash
+kubectl -n heptio-ark get podvolumebackups -l ark.heptio.com/backup-name=YOUR_BACKUP_NAME -o yaml
+```
+
+[1]: https://github.com/restic/restic
+[2]: https://heptio.github.io/ark/v0.8.1/cloud-common
\ No newline at end of file