From 7abd2c6db92ee1c2fde2b21a5080641361ddff2f Mon Sep 17 00:00:00 2001 From: Ashish Amarnath Date: Tue, 16 Jun 2020 14:37:18 -0700 Subject: [PATCH] doc updates Signed-off-by: Ashish Amarnath --- pkg/controller/backup_controller.go | 2 +- site/docs/master/api-types/backup.md | 2 + site/docs/master/contributions/ibm-config.md | 3 +- site/docs/master/customize-installation.md | 9 ++ site/docs/master/restic.md | 97 +++++++++++++++++--- site/docs/master/velero-install.md | 1 + 6 files changed, 101 insertions(+), 13 deletions(-) diff --git a/pkg/controller/backup_controller.go b/pkg/controller/backup_controller.go index 79d8017b1..974696cc7 100644 --- a/pkg/controller/backup_controller.go +++ b/pkg/controller/backup_controller.go @@ -114,6 +114,7 @@ func NewBackupController( backupTracker: backupTracker, backupLocationLister: backupLocationLister, defaultBackupLocation: defaultBackupLocation, + defaultVolumesToRestic: defaultVolumesToRestic, defaultBackupTTL: defaultBackupTTL, snapshotLocationLister: volumeSnapshotLocationLister, defaultSnapshotLocations: defaultSnapshotLocations, @@ -122,7 +123,6 @@ func NewBackupController( volumeSnapshotLister: volumeSnapshotLister, volumeSnapshotContentLister: volumeSnapshotContentLister, newBackupStore: persistence.NewObjectBackupStore, - defaultVolumesToRestic: defaultVolumesToRestic, } c.syncHandler = c.processBackup diff --git a/site/docs/master/api-types/backup.md b/site/docs/master/api-types/backup.md index 70120a921..e0addb97a 100644 --- a/site/docs/master/api-types/backup.md +++ b/site/docs/master/api-types/backup.md @@ -70,6 +70,8 @@ spec: # a default value of 30 days will be used. The default can be configured on the velero server # by passing the flag --default-backup-ttl. ttl: 24h0m0s + # Whether restic should be used to take a backup of all pod volumes by default. + defaultVolumesToRestic: true # Actions to perform at different times during a backup. The only hook currently supported is # executing a command in a container in a pod using the pod exec API. Optional. hooks: diff --git a/site/docs/master/contributions/ibm-config.md b/site/docs/master/contributions/ibm-config.md index 69d34420c..140face6d 100644 --- a/site/docs/master/contributions/ibm-config.md +++ b/site/docs/master/contributions/ibm-config.md @@ -68,7 +68,7 @@ velero install \ Velero does not currently have a volume snapshot plugin for IBM Cloud, so creating volume snapshots is disabled. -Additionally, you can specify `--use-restic` to enable restic support, and `--wait` to wait for the deployment to be ready. +Additionally, you can specify `--use-restic` to enable [restic support][16], and `--wait` to wait for the deployment to be ready. (Optional) Specify [CPU and memory resource requests and limits][15] for the Velero/restic pods. @@ -94,3 +94,4 @@ Uncomment `storageClassName: ` and replace with your `S [5]: https://console.bluemix.net/docs/containers/container_index.html#container_index [14]: http://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html [15]: customize-installation.md#customize-resource-requests-and-limits +[16]: restic.md diff --git a/site/docs/master/customize-installation.md b/site/docs/master/customize-installation.md index fcd17d774..59fca8cbc 100644 --- a/site/docs/master/customize-installation.md +++ b/site/docs/master/customize-installation.md @@ -5,6 +5,7 @@ - [Install in any namespace](#install-in-any-namespace) - [Use non-file-based identity mechanisms](#use-non-file-based-identity-mechanisms) - [Enable restic integration](#enable-restic-integration) + - [Enable default use of restic to backup pod volumes](#default-pod-volume-backup-to-restic) - [Enable features](#enable-features) - [Enable server side features](#enable-server-side-features) - [Enable client side features](#enable-client-side-features) @@ -45,6 +46,14 @@ By default, `velero install` does not install Velero's [restic integration][3]. If you've already run `velero install` without the `--use-restic` flag, you can run the same command again, including the `--use-restic` flag, to add the restic integration to your existing install. +## Default Pod Volume backup to restic + +By default, `velero install` does not enable use of restic to take backups of all pod volumes. An annotation has to be applied on every pod which contains volumes to be backed up by restic. + +To backup all pod volumes using restic without having to apply annotation on the pod, run the `velero install` command with the `--default-volumes-to-restic` flag. + +Using this flag requires restic integration to be enabled with the `--use-restic` flag. Please refer to the [restic integration][3] page for more information. + ## Enable features New features in Velero will be released as beta features behind feature flags which are not enabled by default. A full listing of Velero feature flags can be found [here][11]. diff --git a/site/docs/master/restic.md b/site/docs/master/restic.md index 762933f57..ac63ca993 100644 --- a/site/docs/master/restic.md +++ b/site/docs/master/restic.md @@ -158,7 +158,87 @@ kubectl patch storageclass/ \ You're now ready to use Velero with restic. -## Back up +## To back up + +Velero supports two approaches of discovering pod volumes that need to be backed up using restic: + +- Opt-in approach: Where every pod containing a volume to be backed up using restic must be annotated with the volume's name. +- Opt-out approach: Where all pod volumes are backed up using restic, with the ability to opt-out any volumes that should not be backed up. + +The following sections provide more details on the two approaches. + +### Using the opt-out approach + +In this approach, Velero will back up all pod volumes using restic with the exception of: + +- Volumes mounting the default service account token +- Hostpath volumes + +It is possible to exclude volumes from being backed up using the `backup.velero.io/backup-volumes-excludes` annotation on the pod. + +Instructions to back up using this approach are as follows: + +1. Run the following command on each pod that contains volumes that should **not** be backed up using restic + + ```bash + kubectl -n YOUR_POD_NAMESPACE annotate pod/YOUR_POD_NAME backup.velero.io/backup-volumes-excludes=YOUR_VOLUME_NAME_1,YOUR_VOLUME_NAME_2,... + ``` + where the volume names are the names of the volumes in the pod sepc. + + For example, in the following pod: + + ```yaml + apiVersion: v1 + kind: Pod + metadata: + name: app1 + namespace: sample + spec: + containers: + - image: k8s.gcr.io/test-webserver + name: test-webserver + volumeMounts: + - name: pvc1-vm + mountPath: /volume-1 + - name: pvc2-vm + mountPath: /volume-2 + volumes: + - name: pvc1-vm + persistentVolumeClaim: + claimName: pvc1 + - name: pvc2-vm + claimName: pvc2 + ``` + to exclude restic backup of volume `pvc1-vm`, you would run: + + ```bash + kubectl -n sample annotate pod/app1 backup.velero.io/backup-volumes-excludes=pvc1-vm + ``` + +2. Take a Velero backup: + + ```bash + velero backup create BACKUP_NAME --default-volumes-to-restic OTHER_OPTIONS + ``` + + The above steps uses the opt-out approach on a per backup basis. + + Alternatively, this behavior may be enabled on all velero backups running the `velero install` command with the `--default-volumes-to-restic` flag. Refer [install overview][11] for details. + +3. When the backup completes, view information about the backups: + + ```bash + velero backup describe YOUR_BACKUP_NAME + ``` + ```bash + kubectl -n velero get podvolumebackups -l velero.io/backup-name=YOUR_BACKUP_NAME -o yaml + ``` + +### Using opt-in pod volume backup + +Velero, by default, uses this approach to discover pod volumes that need to be backed up using restic, where every pod containing a volume to be backed up using restic must be annotated with the volume's name. + +Instructions to back up using this approach are as follows: 1. Run the following for each pod that contains a volume to back up: @@ -216,7 +296,9 @@ You're now ready to use Velero with restic. kubectl -n velero get podvolumebackups -l velero.io/backup-name=YOUR_BACKUP_NAME -o yaml ``` -## Restore +## To restore + +Regardless of how volumes are discovered for backup using restic, the process of restoring remains the same. 1. Restore from your Velero backup: @@ -370,8 +452,7 @@ on that node. The controller executes `restic restore` commands to restore pod v ### Backup -1. The main Velero backup process checks each pod that it's backing up for the annotation specifying a restic backup -should be taken (`backup.velero.io/backup-volumes`) +1. Based on configuration, the main Velero backup process uses the opt-in or opt-out approach to check each pod that it's backing up for the volumes to be backed up using restic. 1. When found, Velero first ensures a restic repository exists for the pod's namespace, by: - checking if a `ResticRepository` custom resource already exists - if not, creating a new one, and waiting for the `ResticRepository` controller to init/check it @@ -418,12 +499,6 @@ Velero does not currently provide a mechanism to detect persistent volume claims To solve this, a controller was written by Thomann Bits&Beats: [velero-pvc-watcher][7] -### Add backup annotation - -Velero does not currently provide a single command or automatic way to backup all volume resources in the cluster without annotating pods or pod templates. - -The [velero-volume-controller][10] written by duyanghao helps to solve this problem by adding backup annotation to pods with volumes automatically. - [1]: https://github.com/restic/restic [2]: customize-installation.md#enable-restic-integration [3]: https://github.com/vmware-tanzu/velero/releases/ @@ -433,4 +508,4 @@ The [velero-volume-controller][10] written by duyanghao helps to solve this prob [7]: https://github.com/bitsbeats/velero-pvc-watcher [8]: https://docs.microsoft.com/en-us/azure/aks/azure-files-dynamic-pv [9]: https://github.com/restic/restic/issues/1800 -[10]: https://github.com/duyanghao/velero-volume-controller \ No newline at end of file +[11]: customize-installation.md#default-pod-volume-backup-to-restic diff --git a/site/docs/master/velero-install.md b/site/docs/master/velero-install.md index 58718d16c..d0793bf0c 100644 --- a/site/docs/master/velero-install.md +++ b/site/docs/master/velero-install.md @@ -19,6 +19,7 @@ velero install \ --velero-pod-cpu-limit \ --velero-pod-mem-limit \ [--use-restic] \ + [--default-volumes-to-restic] \ [--restic-pod-cpu-request ] \ [--restic-pod-mem-request ] \ [--restic-pod-cpu-limit ] \