add restore hooks doc (#2862)

Signed-off-by: Ashish Amarnath <ashisham@vmware.com>

site/content/docs/main/hooks.md → site/content/docs/main/backup-hooks.md

 ---
-title: "Hooks"
+title: "Backup Hooks"
 layout: docs
 ---
 

site/content/docs/main/how-velero-works.md

@@ -17,8 +17,8 @@ The **backup** operation:
 
 1. Calls the cloud provider API to make disk snapshots of persistent volumes, if specified.
 
-You can optionally specify hooks to be executed during the backup. For example, you might
-need to tell a database to flush its in-memory buffers to disk before taking a snapshot. [More about hooks][10].
+You can optionally specify backup hooks to be executed during the backup. For example, you might
+need to tell a database to flush its in-memory buffers to disk before taking a snapshot. [More about backup hooks][10].
 
 Note that cluster backups are not strictly atomic. If Kubernetes objects are being created or edited at the time of backup, they might not be included in the backup. The odds of capturing inconsistent information are low, but it is possible.
 
@@ -36,6 +36,8 @@ The default name of a restore is `<BACKUP NAME>-<TIMESTAMP>`, where `<TIMESTAMP>
 
 By default, backup storage locations are created in read-write mode. However, during a restore, you can configure a backup storage location to be in read-only mode, which disables backup creation and deletion for the storage location. This is useful to ensure that no backups are inadvertently created or deleted during a restore scenario.
 
+You can optionally specify restore hooks to be executed during a restore or after resources are restored. For example, you might need to perform a custom database restore operation before the database application containers start. [More about restore hooks][11].
+
 ## Backup workflow
 
 When you run `velero backup create test-backup`:
@@ -77,7 +79,8 @@ This allows restore functionality to work in a cluster migration scenario, where
 
 Likewise, if a backup object exists in Kubernetes but not in object storage, it will be deleted from Kubernetes since the backup tarball no longer exists.
 
-[10]: hooks.md
+[10]: backup-hooks.md
+[11]: restore-hooks.md
 [19]: img/backup-process.png
 [20]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions
 [21]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/#custom-controllers

site/content/docs/main/restore-hooks.md

+---
+title: "Restore Hooks"
+layout: docs
+---
+
+Velero supports Restore Hooks, custom actions that can be executed during or after the restore process. There are two kinds of Restore Hooks:
+
+1. InitContainer Restore Hooks: These will add init containers into restored pods to perform any necessary setup before the application containers of the restored pod can start.
+1. Exec Restore Hooks: These can be used to execute custom commands or scripts in containers of a restored Kubernetes pod.
+
+Only InitContainer Restore Hooks is supported and support for Exec Restore Hooks is coming soon.
+
+## InitContainer Restore Hooks
+
+Use an `InitContainer` hook to add init containers into a pod before it's restored. You can use these init containers to run any setup needed for the pod to resume running from its backed-up state.
+
+There are two ways to specify `InitContainer` restore hooks:
+1. Specifying restore hooks in annotations
+1. Specifying restore hooks in the restore spec
+
+### Specifying Restore Hooks As Pod Annotations
+
+Below are the annotations that can be added to a pod to specify restore hooks:
+* `init.hook.restore.velero.io/container-image`
+    * The container image for the init container to be added.
+* `init.hook.restore.velero.io/container-name`
+    * The name for the init container that is being added.
+* `init.hook.restore.velero.io/command`
+    * This is the `ENTRYPOINT` for the init container being added. This command is not executed within a shell and the container image's `ENTRYPOINT` is used if this is not provided.
+
+#### Example
+
+Use the below commands to add annotations to the pods before taking a backup.
+
+```bash
+$ kubectl annotate pod -n <POD_NAMESPACE> <POD_NAME> \
+    init.hook.restore.velero.io/container-name=restore-hook \
+    init.hook.restore.velero.io/container-image=alpine:latest \
+    init.hook.restore.velero.io/command='["/bin/ash", "-c", "date"]'
+```
+
+With the annotation above, Velero will add the following init container to the pod when it's restored.
+
+```json
+{
+  "command": [
+    "/bin/ash",
+    "-c",
+    "date"
+  ],
+  "image": "alpine:latest",
+  "imagePullPolicy": "Always",
+  "name": "restore-hook"
+  ...
+}
+```
+
+### Specifying Restore Hooks In Restore Spec
+
+Init container restore hooks can also be specified using the `RestoreSpec`.
+Please refer to the documentation on the [Restore API Type][1] for how to specify hooks in the Restore spec.
+
+#### Example
+
+Below is an example of specifying restore hooks in `RestoreSpec`
+
+```yaml
+apiVersion: velero.io/v1
+kind: Restore
+metadata:
+  name: r2
+  namespace: velero
+spec:
+  backupName: b2
+  excludedResources:
+  ...
+  includedNamespaces:
+  - '*'
+  hooks:
+    resources:
+    - name: restore-hook-1
+      includedNamespaces:
+      - app
+      postHooks:
+      - init:
+          initContainers:
+          - name: restore-hook-init1
+            image: alpine:latest
+            volumeMounts:
+            - mountPath: /restores/pvc1-vm
+              name: pvc1-vm
+            command:
+            - /bin/ash
+            - -c
+            - echo -n "FOOBARBAZ" >> /restores/pvc1-vm/foobarbaz
+          - name: restore-hook-init2
+            image: alpine:latest
+            volumeMounts:
+            - mountPath: /restores/pvc2-vm
+              name: pvc2-vm
+            command:
+            - /bin/ash
+            - -c
+            - echo -n "DEADFEED" >> /restores/pvc2-vm/deadfeed
+```
+
+The `hooks` in the above `RestoreSpec`, when restored, will add two init containers to every pod in the `app` namespace
+
+```json
+{
+  "command": [
+    "/bin/ash",
+    "-c",
+    "echo -n \"FOOBARBAZ\" >> /restores/pvc1-vm/foobarbaz"
+  ],
+  "image": "alpine:latest",
+  "imagePullPolicy": "Always",
+  "name": "restore-hook-init1",
+  "resources": {},
+  "terminationMessagePath": "/dev/termination-log",
+  "terminationMessagePolicy": "File",
+  "volumeMounts": [
+    {
+      "mountPath": "/restores/pvc1-vm",
+      "name": "pvc1-vm"
+    }
+  ]
+  ...
+}
+```
+
+and
+
+```json
+{
+  "command": [
+    "/bin/ash",
+    "-c",
+    "echo -n \"DEADFEED\" >> /restores/pvc2-vm/deadfeed"
+  ],
+  "image": "alpine:latest",
+  "imagePullPolicy": "Always",
+  "name": "restore-hook-init2",
+  "resources": {},
+  "terminationMessagePath": "/dev/termination-log",
+  "terminationMessagePolicy": "File",
+  "volumeMounts": [
+    {
+      "mountPath": "/restores/pvc2-vm",
+      "name": "pvc2-vm"
+    }
+  ]
+  ...
+}
+```
+
+[1]: api-types/restore.md

site/content/docs/v1.5-pre/hooks.md → site/content/docs/v1.5-pre/backup-hooks.md

 ---
-title: "Hooks"
+title: "Backup Hooks"
 layout: docs
 ---
 
-Velero currently supports executing commands in containers in pods during a backup.
+Velero supports executing commands in containers in pods during a backup.
 
 ## Backup Hooks
 
@@ -49,10 +49,10 @@ spec.
 
 ## Hook Example with fsfreeze
 
-We are going to walk through using both pre and post hooks for freezing a file system. Freezing the
+This examples walks you through using both pre and post hooks for freezing a file system. Freezing the
 file system is useful to ensure that all pending disk I/O operations have completed prior to taking a snapshot.
 
-We will be using [examples/nginx-app/with-pv.yaml][2] for this example. Follow the [steps for your provider][3] to
+This example uses [examples/nginx-app/with-pv.yaml][2]. Follow the [steps for your provider][3] to
 setup this example.
 
 ### Annotations

site/content/docs/v1.5-pre/how-velero-works.md

@@ -7,7 +7,7 @@ Each Velero operation -- on-demand backup, scheduled backup, restore -- is a cus
 
 You can back up or restore all objects in your cluster, or you can filter objects by type, namespace, and/or label.
 
-Velero is ideal for the disaster recovery use case, as well as for snapshotting your application state, prior to performing system operations on your cluster (e.g. upgrades).
+Velero is ideal for the disaster recovery use case, as well as for snapshotting your application state, prior to performing system operations on your cluster, like upgrades.
 
 ## On-demand backups
 
@@ -17,8 +17,8 @@ The **backup** operation:
 
 1. Calls the cloud provider API to make disk snapshots of persistent volumes, if specified.
 
-You can optionally specify hooks to be executed during the backup. For example, you might
-need to tell a database to flush its in-memory buffers to disk before taking a snapshot. [More about hooks][10].
+You can optionally specify backup hooks to be executed during the backup. For example, you might
+need to tell a database to flush its in-memory buffers to disk before taking a snapshot. [More about backup hooks][10].
 
 Note that cluster backups are not strictly atomic. If Kubernetes objects are being created or edited at the time of backup, they might not be included in the backup. The odds of capturing inconsistent information are low, but it is possible.
 
@@ -36,6 +36,8 @@ The default name of a restore is `<BACKUP NAME>-<TIMESTAMP>`, where `<TIMESTAMP>
 
 By default, backup storage locations are created in read-write mode. However, during a restore, you can configure a backup storage location to be in read-only mode, which disables backup creation and deletion for the storage location. This is useful to ensure that no backups are inadvertently created or deleted during a restore scenario.
 
+You can optionally specify restore hooks to be executed during a restore or after resources are restored. For example, you might need to perform a custom database restore operation before the database application containers start. [More about restore hooks][11].
+
 ## Backup workflow
 
 When you run `velero backup create test-backup`:
@@ -67,7 +69,7 @@ When you create a backup, you can specify a TTL (time to live) by adding the fla
 * All PersistentVolume snapshots
 * All associated Restores
 
-The TTL flag allows the user to specify the backup retention period with the value specified in hours, minutes and seconds in the form `--ttl 24h0m0s`. If not specified, a default TTL value of 30 days will be applied. 
+The TTL flag allows the user to specify the backup retention period with the value specified in hours, minutes and seconds in the form `--ttl 24h0m0s`. If not specified, a default TTL value of 30 days will be applied.
 
 ## Object storage sync
 
@@ -77,9 +79,9 @@ This allows restore functionality to work in a cluster migration scenario, where
 
 Likewise, if a backup object exists in Kubernetes but not in object storage, it will be deleted from Kubernetes since the backup tarball no longer exists.
 
-[10]: hooks.md
+[10]: backup-hooks.md
+[11]: restore-hooks.md
 [19]: img/backup-process.png
 [20]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/#customresourcedefinitions
 [21]: https://kubernetes.io/docs/concepts/api-extension/custom-resources/#custom-controllers
 [22]: https://github.com/coreos/etcd
-

site/content/docs/v1.5-pre/restore-hooks.md

+---
+title: "Restore Hooks"
+layout: docs
+---
+
+Velero supports Restore Hooks, custom actions that can be executed during or after the restore process. There are two kinds of Restore Hooks:
+
+1. InitContainer Restore Hooks: These will add init containers into restored pods to perform any necessary setup before the application containers of the restored pod can start.
+1. Exec Restore Hooks: These can be used to execute custom commands or scripts in containers of a restored Kubernetes pod.
+
+Only InitContainer Restore Hooks is supported and support for Exec Restore Hooks is coming soon.
+
+## InitContainer Restore Hooks
+
+Use an `InitContainer` hook to add init containers into a pod before it's restored. You can use these init containers to run any setup needed for the pod to resume running from its backed-up state.
+
+There are two ways to specify `InitContainer` restore hooks:
+1. Specifying restore hooks in annotations
+1. Specifying restore hooks in the restore spec
+
+### Specifying Restore Hooks As Pod Annotations
+
+Below are the annotations that can be added to a pod to specify restore hooks:
+* `init.hook.restore.velero.io/container-image`
+    * The container image for the init container to be added.
+* `init.hook.restore.velero.io/container-name`
+    * The name for the init container that is being added.
+* `init.hook.restore.velero.io/command`
+    * This is the `ENTRYPOINT` for the init container being added. This command is not executed within a shell and the container image's `ENTRYPOINT` is used if this is not provided.
+
+#### Example
+
+Use the below commands to add annotations to the pods before taking a backup.
+
+```bash
+$ kubectl annotate pod -n <POD_NAMESPACE> <POD_NAME> \
+    init.hook.restore.velero.io/container-name=restore-hook \
+    init.hook.restore.velero.io/container-image=alpine:latest \
+    init.hook.restore.velero.io/command='["/bin/ash", "-c", "date"]'
+```
+
+With the annotation above, Velero will add the following init container to the pod when it's restored.
+
+```json
+{
+  "command": [
+    "/bin/ash",
+    "-c",
+    "date"
+  ],
+  "image": "alpine:latest",
+  "imagePullPolicy": "Always",
+  "name": "restore-hook"
+  ...
+}
+```
+
+### Specifying Restore Hooks In Restore Spec
+
+Init container restore hooks can also be specified using the `RestoreSpec`.
+Please refer to the documentation on the [Restore API Type][1] for how to specify hooks in the Restore spec.
+
+#### Example
+
+Below is an example of specifying restore hooks in `RestoreSpec`
+
+```yaml
+apiVersion: velero.io/v1
+kind: Restore
+metadata:
+  name: r2
+  namespace: velero
+spec:
+  backupName: b2
+  excludedResources:
+  ...
+  includedNamespaces:
+  - '*'
+  hooks:
+    resources:
+    - name: restore-hook-1
+      includedNamespaces:
+      - app
+      postHooks:
+      - init:
+          initContainers:
+          - name: restore-hook-init1
+            image: alpine:latest
+            volumeMounts:
+            - mountPath: /restores/pvc1-vm
+              name: pvc1-vm
+            command:
+            - /bin/ash
+            - -c
+            - echo -n "FOOBARBAZ" >> /restores/pvc1-vm/foobarbaz
+          - name: restore-hook-init2
+            image: alpine:latest
+            volumeMounts:
+            - mountPath: /restores/pvc2-vm
+              name: pvc2-vm
+            command:
+            - /bin/ash
+            - -c
+            - echo -n "DEADFEED" >> /restores/pvc2-vm/deadfeed
+```
+
+The `hooks` in the above `RestoreSpec`, when restored, will add two init containers to every pod in the `app` namespace
+
+```json
+{
+  "command": [
+    "/bin/ash",
+    "-c",
+    "echo -n \"FOOBARBAZ\" >> /restores/pvc1-vm/foobarbaz"
+  ],
+  "image": "alpine:latest",
+  "imagePullPolicy": "Always",
+  "name": "restore-hook-init1",
+  "resources": {},
+  "terminationMessagePath": "/dev/termination-log",
+  "terminationMessagePolicy": "File",
+  "volumeMounts": [
+    {
+      "mountPath": "/restores/pvc1-vm",
+      "name": "pvc1-vm"
+    }
+  ]
+  ...
+}
+```
+
+and
+
+```json
+{
+  "command": [
+    "/bin/ash",
+    "-c",
+    "echo -n \"DEADFEED\" >> /restores/pvc2-vm/deadfeed"
+  ],
+  "image": "alpine:latest",
+  "imagePullPolicy": "Always",
+  "name": "restore-hook-init2",
+  "resources": {},
+  "terminationMessagePath": "/dev/termination-log",
+  "terminationMessagePolicy": "File",
+  "volumeMounts": [
+    {
+      "mountPath": "/restores/pvc2-vm",
+      "name": "pvc2-vm"
+    }
+  ]
+  ...
+}
+```
+
+[1]: api-types/restore.md

site/data/docs/main-toc.yml

@@ -35,12 +35,14 @@ toc:
         url: /resource-filtering
       - page: Backup reference
         url: /backup-reference
+      - page: Backup hooks
+        url: /backup-hooks
       - page: Restore reference
         url: /restore-reference
+      - page: Restore hooks
+        url: /restore-hooks
       - page: Run in any namespace
         url: /namespace
-      - page: Extend with hooks
-        url: /hooks
       - page: CSI Support (beta)
         url: /csi
       - page: Verifying Self-signed Certificates

site/data/docs/v1-5-pre-toc.yml

@@ -35,12 +35,14 @@ toc:
         url: /resource-filtering
       - page: Backup reference
         url: /backup-reference
+      - page: Backup hooks
+        url: /backup-hooks
       - page: Restore reference
         url: /restore-reference
+      - page: Restore hooks
+        url: /restore-hooks
       - page: Run in any namespace
         url: /namespace
-      - page: Extend with hooks
-        url: /hooks
       - page: CSI Support (beta)
         url: /csi
       - page: Verifying Self-signed Certificates