[WIP] Document OADP backup and restore

docs/modules/ROOT/nav.adoc

@@ -26,3 +26,7 @@
 
 ** OpenShift Compliance
 *** xref:openshift-compliance/howto-export-report.adoc[Review Compliance Scan Results]
+
+** OpenShift APIs for Data Protection
+*** xref:openshift-adp/howto-backup-and-restore.adoc[Create and Restore Backups as Cluster Admin]
+*** xref:openshift-adp/howto-nonadmin-backup-and-restore.adoc[Create and Restore Backups as Namespace Admin]

docs/modules/ROOT/pages/openshift-adp/howto-backup-and-restore.adoc

@@ -0,0 +1,132 @@
+= Application backup and restore using OADF
+
+OpenShift APIs for Data Protection (OADP) allows users to back up their on-cluster resources, including persisten volume data, to external S3 storage.
+
+VSHN offers OADP as an optional cluster add-on.
+
+[NOTE]
+====
+The custom resources that govern OADF backups are called `Backup`, `Schedule` and `Restore`.
+These names often conflict with other custom resources, such as `backup.k8s.mariadb.com` or `backup.k8up.io`.
+For that reason, we recommend to always explicitly specify the API group when accessing OADP resources.
+====
+
+== Prerequisites
+Configuring backups and backup schedules with OADF requires cluster admin permissions.
+To create namespace-scoped backups without cluster admin permissions, see xref:openshift-adp/howto-nonadmin-backup-and-restore.adoc[Create and Restore Backups as Namespace Admin].
+
+
+== Backing up a namespace with OADF
+
+To create a new backup, a `backup.velero.io` resource is created in the `openshift-adp` namespace.
+The `Backup` specifies which resources to include in the backup.
+
+[source,yaml]
+--
+apiVersion: velero.io/v1
+kind: Backup
+metadata:
+  name: my-backup <1>
+  namespace: openshift-adp
+spec:
+  hooks: {} <2>
+  includedNamespaces:
+  - my-namespace <3>
+  includedResources: [] <3>
+  excludedResources: [] <3>
+  ttl: 10h0m0s <4>
+  labelSelector: <5>
+    matchLabels:
+      app: my-app
+--
+<1> Unique name for your backup.
+<2> Optionally configure hooks that are run before or after your backup is performed.
+For more information, see https://docs.redhat.com/en/documentation/openshift_container_platform/4.12/html/backup_and_restore/oadp-application-backup-and-restore#oadp-creating-backup-hooks-doc[the upstream documentation on backup hooks].
+<3> Explicitly list which Kubernetes resources are included or excluded in your backup.
+If these parameters are both omitted, all resources are backed up.
+<4> The TTL, or retention time, of your backup.
+If your backup is older than its TTL, it is automatically deleted.
+<5> If specified, only objects with the appropriate labels are included in the backup.
+If omitted, all objects are included.
+
+Once created, monitor your backup's status:
+
+[source,bash]
+--
+kubectl get backup.velero.io -nopenshift-adp my-backup -o jsonpath="{.status.phase}"
+--
+
+Once the phase is listed as `Completed`, the backup has succeeded.
+
+== Creating a backup schedule
+
+Backups can be created automatically on a schedule using the `schedule.velero.io` custom resource:
+
+[source,yaml]
+--
+apiVersion: velero.io/v1
+kind: Schedule
+metadata:
+  name: my-schedule <1>
+  namespace: openshift-adp
+spec:
+  schedule: 0 7 * * *  1 <2>
+  template: <3>
+    includedNamespaces:
+    - <namespace>
+    ...
+--
+<1> Unique name for your backup schedule
+<2> Cron expression to schedule the backup
+<3> Template for the `backup.velero.io` spec
+
+== Restoring a backup with OADF
+
+WARNING: Restoring a backup will overwrite any existing resources that are part of the backup, even if they are still present on the cluster.
+
+To restore a backup, first identify the name of the backup you want to restore:
+
+[source,bash]
+==
+kubectl get backup.velero.io -nopenshift-adp -o=custom-columns='NAME:metadata.name,PHASE:status.phase
+==
+
+Once you've identified the backup, create a `restore.velero.io` resource to initiate a restore:
+
+[source,yaml]
+==
+apiVersion: velero.io/v1
+kind: Restore
+metadata:
+  name: my-restore <1>
+  namespace: openshift-adp
+spec:
+  backupName: my-backup- <2>
+  excludedResources: <3>
+  - nodes
+  - events
+  - events.events.k8s.io
+  - backups.velero.io
+  - restores.velero.io
+  - resticrepositories.velero.io
+  restorePVs: true <4>
+==
+<1> Unique name for your backup schedule
+<2> Name of the specific `backup.velero.io` resource you wish to restore
+<3> List of resource types to exclude from the restore.
+The given list is a recommendation, as the listed resources can cause problems when restored blindly.
+<4> Whether to restore persistent volume backups as well.
+If set to `false`, the resources are restored with empty PVs.
+
+Monitor the status of the `restore.velero.io` resource:
+[source,bash]
+--
+kubectl get restore.velero.io -nopenshift-adp my-restore -o jsonpath='{.status.phase}'
+--
+
+When the phase becomes `Completed`, the restore has been successful.
+Investigate the restored resources to ensure everything is in working order.
+
+== Further information
+
+For a more in-depth look at OADP, please refer to the https://docs.redhat.com/en/documentation/openshift_container_platform/4.22/html/backup_and_restore/oadp-application-backup-and-restore[upstream documentation].

docs/modules/ROOT/pages/openshift-adp/howto-nonadmin-backup-and-restore.adoc

@@ -0,0 +1,125 @@
+= Application backup and restore using OADP Self-Service
+
+OpenShift APIs for Data Protection (OADP) allows users to back up their on-cluster resources, including persisten volume data, to external S3 storage.
+Using OADP normally, however, requires cluster admin permissions.
+
+For users without cluster admin permissions, the self-service mode of OADP can be used, which allows the creation of namespace-scoped backup and restore operations.
+These `NonAdminBackup` and `NonAdminRestore` objects can be created inside a given namespaceby anyone with permission to create objects in said namespace, and they can only back up and restore objects from that namespace.
+
+VSHN offers OADP as an optional cluster add-on.
+If OADP is installed, then the ability to use self-service backups is enabled by default.
+
+== Backing up a namespace with OADF Self-Service
+
+To create a new backup, a `NonAdminBackup` resource is created in the namespace you wish to back up.
+The `NonAdminBackup` specifies which resources to include in the backup.
+
+[source,yaml]
+--
+apiVersion: oadp.openshift.io/v1alpha1
+kind: NonAdminBackup
+metadata:
+  name: my-nonadmin-backup
+  namespace: my-namespace
+spec:
+  backupSpec: <1>
+    hooks: {} <2>
+    includedNamespaces:
+    - my-namespace <3>
+    includedResources: [] <4>
+    excludedResources: [] <4>
+    ttl: 10h0m0s <5>
+    labelSelector: <6>
+      matchLabels:
+        app: my-app
+--
+<1> The self-service backup operator will create a `backup.velero.io` object for you.
+In `spec.backupSpec`, you can define the spec for that object.
+<2> Optionally configure hooks that are run before or after your backup is performed.
+For more information, see https://docs.redhat.com/en/documentation/openshift_container_platform/4.12/html/backup_and_restore/oadp-application-backup-and-restore#oadp-creating-backup-hooks-doc[the upstream documentation on backup hooks].
+<3> List the namespace in which the `NonAdminBackup` is created.
+The backup will fail if this namespace does not match the namespace of the `NonAdminBackup`.
+<4> Explicitly list which Kubernetes resources are included or excluded in your backup.
+If these parameters are both omitted, all resources are backed up.
+<5> The TTL, or retention time, of your backup.
+If your backup is older than its TTL, it is automatically deleted.
+<6> If specified, only objects with the appropriate labels are included in the backup.
+If omitted, all objects are included.
+
+Once created, monitor your backup's status:
+
+[source,bash]
+--
+kubectl get nab my-nonadmin-backup -w
+--
+
+When the backup has succeeded, the `REQUEST-PHASE` will be listed as `Created`, and the `VELERO-PHASE` will say `Completed`.
+
+[NOTE]
+====
+`NonAdminBackups` have to adhere to administrator-imposed restrictions on certain fields in the `.spec.backupSpec`.
+For example, the `ttl` field might be constrained to a specific value.
+
+If your backup's `REQUEST-STATE` gets stuck in `BackingOff`, it might be that your `spec.backupSpec` is violating these constraints.
+To find out why your backup was rejected, check the status conditions of the `NonAdminBackup` object.
+====
+
+== Creating a backup schedule
+
+Currently, the self-service backup operator does not provide a native way to create backups on a schedule.
+As a workaround, a `CronJob` can be used to spawn `Jobs` which in turn generate `NonAdminBackup` objects.
+
+== Restoring a backup with OADP Self-Service
+
+WARNING: Restoring a backup will overwrite any existing resources that are part of the backup, even if they are still present on the cluster.
+
+To restore a backup, first identify the name of the backup you want to restore:
+
+[source,bash]
+==
+kubectl get NonAdminBackup
+==
+
+Once you've identified the backup, create a `NonAdminRestore` resource to initiate a restore:
+
+[source,yaml]
+==
+apiVersion: oadp.openshift.io/v1alpha1
+kind: NonAdminRestore
+metadata:
+  name: my-nonadmin-restore
+  namespace: my-namespace <1>
+spec:
+  restoreSpec: <2>
+    backupName: my-nonadmin-backup <3>
+    excludedResources: <4>
+    - nodes
+    - events
+    - events.events.k8s.io
+    - backups.velero.io
+    - restores.velero.io
+    - resticrepositories.velero.io
+    restorePVs: true <5>
+==
+<1> The `NonAdminRestore` must be created in the same namespace as the corresponding `NonAdminBackup`.
+<2> The self-service backup operator will create a `restore.velero.io` object on your behalf.
+In `.spec.restoreSpec`, you can provide the spec for that object.
+<3> Name of the specific `NonAdminBackup` resource you wish to restore.
+<4> List of resource types to exclude from the restore.
+The given list is a recommendation, as the listed resources can cause problems when restored blindly.
+<5> Whether to restore persistent volume backups as well.
+If set to `false`, the resources are restored with empty PVs.
+
+Monitor the status of the `NonAdminRestore`:
+[source,bash]
+--
+kubectl get nar -w
+--
+
+When the restore has succeeded, the `REQUEST-PHASE` will be listed as `Created`, and the `VELERO-PHASE` will say `Completed`.
+
+== Further information
+
+For more information on OADP Self-Service, please refer to the https://docs.okd.io/4.22/backup_and_restore/application_backup_and_restore/oadp-self-service/oadp-self-service-namespace-admin-use-cases.html[upstream documentation].
+
+For a more in-depth look at OADP in general, please refer to the https://docs.redhat.com/en/documentation/openshift_container_platform/4.22/html/backup_and_restore/oadp-application-backup-and-restore[official OADP documentation].