From 26a41768b64f77276e50578b20f1eeef6011bbe0 Mon Sep 17 00:00:00 2001 From: Aline Abler Date: Tue, 8 Sep 2026 12:10:18 +0200 Subject: [PATCH] [WIP] Document OADP backup and restore --- docs/modules/ROOT/nav.adoc | 4 + .../howto-backup-and-restore.adoc | 132 ++++++++++++++++++ .../howto-nonadmin-backup-and-restore.adoc | 125 +++++++++++++++++ 3 files changed, 261 insertions(+) create mode 100644 docs/modules/ROOT/pages/openshift-adp/howto-backup-and-restore.adoc create mode 100644 docs/modules/ROOT/pages/openshift-adp/howto-nonadmin-backup-and-restore.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 1e467f7..175546c 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/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] diff --git a/docs/modules/ROOT/pages/openshift-adp/howto-backup-and-restore.adoc b/docs/modules/ROOT/pages/openshift-adp/howto-backup-and-restore.adoc new file mode 100644 index 0000000..630a1f6 --- /dev/null +++ b/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: + - + ... +-- +<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]. diff --git a/docs/modules/ROOT/pages/openshift-adp/howto-nonadmin-backup-and-restore.adoc b/docs/modules/ROOT/pages/openshift-adp/howto-nonadmin-backup-and-restore.adoc new file mode 100644 index 0000000..fd81606 --- /dev/null +++ b/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].