Merge pull request #69221 from sbeskin-redhat/OADP_3184

EricPonvelle · web-flow · commit 0b834b9e6d9a · 2024-01-18T10:37:12.000-05:00
OADP-3184: [Doc improvements] - OADP backing up &amp; OADP restoring
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/backing-up-applications.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/backing-up-applications.adoc
@@ -9,25 +9,24 @@ toc::[]
 
 You back up applications by creating a `Backup` custom resource (CR). See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-cr.adoc#oadp-creating-backup-cr-doc[Creating a Backup CR].
 
-The `Backup` CR creates backup files for Kubernetes resources and internal images, on S3 object storage, and snapshots for persistent volumes (PVs), if the cloud provider uses a native snapshot API or the Container Storage Interface (CSI) to create snapshots, such as {rh-storage} 4.
+* The `Backup` CR creates backup files for Kubernetes resources and internal images on S3 object storage.
+* If your cloud provider has a native snapshot API or supports CSI snapshots, the `Backup` CR backs up persistent volumes (PVs) by creating snapshots. For more information about working with CSI snapshots, see xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-pvs-csi-doc.adoc#oadp-backing-up-pvs-csi-doc[Backing up persistent volumes with CSI snapshots].
 
 For more information about CSI volume snapshots, see xref:../../../storage/container_storage_interface/persistent-storage-csi-snapshots.adoc#persistent-storage-csi-snapshots[CSI volume snapshots].
 
 :FeatureName: The `CloudStorage` API for S3 storage
 include::snippets/technology-preview.adoc[]
 
-* If your cloud provider has a native snapshot API or supports CSI snapshots, the `Backup` CR backs up persistent volumes (PVs) by creating snapshots. For more information about working with CSI snapshots, see xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-pvs-csi-doc.adoc#oadp-backing-up-pvs-csi-doc[Backing up persistent volumes with CSI snapshots].
-
-* If your cloud provider does not support snapshots or if your applications are on NFS data volumes, you can create backups by using Restic. See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-applications-restic-doc.adoc#oadp-backing-up-applications-restic-doc[Backing up applications with File System Backup: Kopia or Restic].
+* If your cloud provider does not support snapshots or if your applications are on NFS data volumes, you can create backups by using Kopia or Restic. See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-applications-restic-doc.adoc#oadp-backing-up-applications-restic-doc[Backing up applications with File System Backup: Kopia or Restic].
 
 [IMPORTANT]
 ====
 The {oadp-first} does not support backing up volume snapshots that were created by other software.
 ====
 
-You can create backup hooks to run commands before or after the backup operation. See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-hooks-doc.adoc#backing-up-applications[Creating backup hooks].
+You can create backup hooks to run commands before or after the backup operation. See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-hooks-doc.adoc#oadp-creating-backup-hooks-doc[Creating backup hooks].
 
-You can schedule backups by creating a `Schedule` CR instead of a `Backup` CR. See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-scheduling-backups-doc.adoc#backing-up-applications[Scheduling backups].
+You can schedule backups by creating a `Schedule` CR instead of a `Backup` CR. See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-scheduling-backups-doc.adoc#oadp-scheduling-backups-doc[Scheduling backups using Schedule CR]].
 
 // include::modules/oadp-creating-backup-cr.adoc[leveloffset=+1]
 // include::modules/oadp-backing-up-pvs-csi.adoc[leveloffset=+1]
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-about-kopia.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-about-kopia.adoc
@@ -12,21 +12,22 @@ Kopia supports network and local storage locations, and many cloud or remote sto
 
 * Amazon S3 and any cloud storage that is compatible with S3
 * Azure Blob Storage
-* Google Cloud Storage Platform
+* Google Cloud Storage platform
 
 Kopia uses content-addressable storage for snapshots:
 
-* Each snapshot is always incremental. This means that all data is uploaded once to the repository, based on file content. A file is only uploaded to the repository again if it is modified. 
-
-* Multiple copies of the same file are stored once, meaning deduplication. After moving or renaming large files, Kopia can recognize that they have the same content and does not upload them again.
+* Snapshots are always incremental; data that is already included in previous snapshots is not re-uploaded to the repository. A file is only uploaded to the repository again if it is modified.
+* Stored data is deduplicated; if multiple copies of the same file exist, only one of them is stored.
+* If files are moved or renamed, Kopia can recognize that they have the same content and does not upload them again.
 
 
 [id="oadp-kopia-integration"]
 == OADP integration with Kopia
 
 OADP 1.3 supports Kopia as the backup mechanism for pod volume backup in addition to Restic. You must choose one or the other at installation by setting the `uploaderType` field in the `DataProtectionApplication` custom resource (CR). The possible values are `restic` or `kopia`. If you do not specify an  `uploaderType`, OADP 1.3 defaults to using Kopia as the backup mechanism. The data is written to and read from a unified repository.
 
-.`DataProtectionApplication` configuration for Kopia
+The following example shows a `DataProtectionApplication` CR configured for using Kopia:
+
 [source,yaml]
 ----
 apiVersion: oadp.openshift.io/v1alpha1
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-applications-restic-doc.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-applications-restic-doc.adoc
@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can use OADP to back up and restore Kubernetes volumes attached to pods from the file system of the volumes. This process is called File System Backup (FSB) or Pod Volume Backup (PVB) and is accomplished by using modules from the following open source backup tools: Restic and Kopia.
+You can use OADP to back up and restore Kubernetes volumes attached to pods from the file system of the volumes. This process is called File System Backup (FSB) or Pod Volume Backup (PVB). It is accomplished by using modules from the open source backup tools Restic or Kopia.
 
 If your cloud provider does not support snapshots or if your applications are on NFS data volumes, you can create backups by using FSB.
 
@@ -16,7 +16,7 @@ If your cloud provider does not support snapshots or if your applications are on
 link:https://restic.net/[Restic] is installed by the OADP Operator by default. If you prefer, you can install link:https://kopia.io/[Kopia] instead.
 ====
 
-FSB integration with OADP provides a solution for backing up and restoring almost any type of Kubernetes volume. This integration is an additional capability of OADP and is not a replacement for existing functionality.
+FSB integration with OADP provides a solution for backing up and restoring almost any type of Kubernetes volumes. This integration is an additional capability of OADP and is not a replacement for existing functionality.
 
 You back up Kubernetes resources, internal images, and persistent volumes with Kopia or Restic by editing the `Backup` custom resource (CR).
 
@@ -26,7 +26,7 @@ You do not need to specify a snapshot location in the `DataProtectionApplication
 ====
 In OADP version 1.3 and later, you can use either Kopia or Restic for backing up applications.
 
-For the Built-in DataMover you must use Kopia.
+For the Built-in DataMover, you must use Kopia.
 
 In OADP version 1.2 and earlier, you can only use Restic for backing up applications.
 ====
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-pvs-csi-doc.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-pvs-csi-doc.adoc
@@ -8,7 +8,7 @@ toc::[]
 
 You back up persistent volumes with Container Storage Interface (CSI) snapshots by editing the `VolumeSnapshotClass` custom resource (CR) of the cloud storage before you create the `Backup` CR, see xref:../../../storage/container_storage_interface/persistent-storage-csi-snapshots.adoc#persistent-storage-csi-snapshots-overview_persistent-storage-csi-snapshots[CSI volume snapshots].
 
-For more information see xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-cr.adoc#oadp-creating-backup-cr-doc[Creating a Backup CR].
+For more information, see xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-cr.adoc#oadp-creating-backup-cr-doc[Creating a Backup CR].
 
 .Prerequisites
 
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-cr.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-cr.adoc
@@ -77,7 +77,7 @@ spec:
 <2> Optional: Specify an array of resources to include in the backup. Resources might be shortcuts (for example, 'po' for 'pods') or fully-qualified. If unspecified, all resources are included.
 <3> Optional: Specify an array of resources to exclude from the backup. Resources might be shortcuts (for example, 'po' for 'pods') or fully-qualified.
 <4> Specify the name of the `backupStorageLocations` CR.
-<5> Map of {key,value} pairs of backup resources that have *all* of the specified labels.
+<5> Map of {key,value} pairs of backup resources that have *all* the specified labels.
 <6> Map of {key,value} pairs of backup resources that have *one or more* of the specified labels.
 
 . Verify that the status of the `Backup` CR is `Completed`:
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-hooks-doc.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-creating-backup-hooks-doc.adoc
@@ -8,9 +8,7 @@ toc::[]
 
 When performing a backup, it is possible to specify one or more commands to execute in a container within a pod, based on the pod being backed up.
 
-The commands can be configured to performed before any custom action processing (_Pre_ hooks), or after all custom actions have been completed and any additional items specified by the custom action have been backed up.
-
-_Post_ hooks run after the backup.
+The commands can be configured to performed before any custom action processing (_Pre_ hooks), or after all custom actions have been completed and any additional items specified by the custom action have been backed up (_Post_ hooks).
 
 You create backup hooks to run commands in a container in a pod by editing the `Backup` custom resource (CR).
 
@@ -55,7 +53,7 @@ spec:
 <2> Optional: You can specify namespaces to which the hook does not apply.
 <3> Currently, pods are the only supported resource that hooks can apply to.
 <4> Optional: You can specify resources to which the hook does not apply.
-<5> Optional: This hook only applies to objects matching the label. If this value is not specified, the hook applies to all namespaces.
+<5> Optional: This hook only applies to objects matching the label. If this value is not specified, the hook applies to all objects.
 <6> Array of hooks to run before the backup.
 <7> Optional: If the container is not specified, the command runs in the first container in the pod.
 <8> This is the entry point for the `init` container being added.
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-deleting-backups-doc.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-deleting-backups-doc.adoc
@@ -24,14 +24,14 @@ After you delete the `Backup` CR and the associated object storage data, you can
 
 * Choose one of the following actions to delete the `Backup` CR:
 
-** To delete the `Backup` CR and keep the associated object storage data, issue the following command:
+** To delete the `Backup` CR and keep the associated object storage data, run the following command:
 +
 [source,terminal]
 ----
 $ oc delete backup <backup_CR_name> -n <velero_namespace>
 ----
 
-** To delete the `Backup` CR and delete the associated object storage data, issue the following command:
+** To delete the `Backup` CR and delete the associated object storage data, run the following command:
 +
 [source,terminal]
 ----
@@ -40,5 +40,5 @@ $ velero backup delete <backup_CR_name> -n <velero_namespace>
 +
 Where:
 +
-<backup_CR_name>:: Specifies the name of the `Backup` custom resource.
-<velero_namespace>:: Specifies the namespace that contains the `Backup` custom resource.
+<backup_CR_name>:: The name of the `Backup` custom resource.
+<velero_namespace>:: The namespace that contains the `Backup` custom resource.
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-scheduling-backups-doc.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-scheduling-backups-doc.adoc
@@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-The schedule operation allows you to create a backup of your data at a specified time, defined by a Cron expression.
+The schedule operation allows you to create a backup of your data at a particular time, specified by a Cron expression.
 
 You schedule backups by creating a `Schedule` custom resource (CR) instead of a `Backup` CR.
 
diff --git a/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/restoring-applications.adoc b/backup_and_restore/application_backup_and_restore/backing_up_and_restoring/restoring-applications.adoc
@@ -8,7 +8,7 @@ toc::[]
 
 You restore application backups by creating a `Restore` custom resource (CR). See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/restoring-applications.adoc#oadp-creating-restore-cr_restoring-applications[Creating a Restore CR].
 
-You can create restore hooks to run commands in a container in a pod while restoring your application by editing the `Restore` (CR). See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/restoring-applications.adoc#oadp-creating-restore-hooks_restoring-applications[Creating restore hooks]
+You can create restore hooks to run commands in a container in a pod by editing the `Restore` CR. See xref:../../../backup_and_restore/application_backup_and_restore/backing_up_and_restoring/restoring-applications.adoc#oadp-creating-restore-hooks_restoring-applications[Creating restore hooks].
 
 include::modules/oadp-creating-restore-cr.adoc[leveloffset=+1]
 include::modules/oadp-creating-restore-hooks.adoc[leveloffset=+1]
diff --git a/backup_and_restore/application_backup_and_restore/release-notes/oadp-release-notes-1-3.adoc b/backup_and_restore/application_backup_and_restore/release-notes/oadp-release-notes-1-3.adoc
@@ -7,7 +7,7 @@ include::_attributes/attributes-openshift-dedicated.adoc[]
 
 toc::[]
 
-The release notes for OpenShift API for Data Protection (OADP) describe new features and enhancements, deprecated features, product recommendations, known issues, and resolved issues.
+The release notes for OpenShift API for Data Protection (OADP) 1.3 describe new features and enhancements, deprecated features, product recommendations, known issues, and resolved issues.
 
 include::modules/oadp-release-notes-1-3-0.adoc[leveloffset=+1]
 include::modules/oadp-upgrade-from-oadp-data-mover-1-2-0.adoc[leveloffset=+3]
diff --git a/backup_and_restore/index.adoc b/backup_and_restore/index.adoc
@@ -23,7 +23,7 @@ A cluster's certificates expire one year after the installation date. You can sh
 
 You might run into several situations where {product-title}  does not work as expected, such as:
 
-* You have a cluster that is not functional after the restart because of unexpected conditions, such as node failure, or network connectivity issues.
+* You have a cluster that is not functional after the restart because of unexpected conditions, such as node failure or network connectivity issues.
 * You have deleted something critical in the cluster by mistake.
 * You have lost the majority of your control plane hosts, leading to etcd quorum loss.
 
diff --git a/modules/oadp-creating-restore-cr.adoc b/modules/oadp-creating-restore-cr.adoc
@@ -13,7 +13,7 @@ You restore a `Backup` custom resource (CR) by creating a `Restore` CR.
 * You must install the OpenShift API for Data Protection (OADP) Operator.
 * The `DataProtectionApplication` CR must be in a `Ready` state.
 * You must have a Velero `Backup` CR.
-* Adjust the requested size so the persistent volume (PV) capacity matches the requested size at backup time.
+* The persistent volume (PV) capacity must match the requested size at backup time. Adjust the requested size if needed.
 
 .Procedure
 
@@ -40,7 +40,7 @@ spec:
 ----
 <1> Name of the `Backup` CR.
 <2> Optional: Specify an array of resources to include in the restore process. Resources might be shortcuts (for example, `po` for `pods`) or fully-qualified. If unspecified, all resources are included.
-<3> Optional: The `restorePVs` parameter can be set to `false` in order to turn off restore of `PersistentVolumes` from `VolumeSnapshot` of Container Storage Interface (CSI) snapshots, or from native snapshots when `VolumeSnapshotLocation` is configured.
+<3> Optional: The `restorePVs` parameter can be set to `false` to turn off restore of `PersistentVolumes` from `VolumeSnapshot` of Container Storage Interface (CSI) snapshots or from native snapshots when `VolumeSnapshotLocation` is configured.
 
 . Verify that the status of the `Restore` CR is `Completed` by entering the following command:
 +
@@ -66,7 +66,7 @@ $ bash dc-restic-post-restore.sh <restore-name>
 +
 [NOTE]
 ====
-In the course of the restore process, the OADP Velero plug-ins scale down the `DeploymentConfig` objects and restore the pods as standalone pods to prevent the cluster from deleting the restored `DeploymentConfig` pods immediately on restore and to allow Restic and post-restore hooks to complete their actions on the restored pods. The cleanup script removes these disconnected pods and scale any `DeploymentConfig` objects back up to the appropriate number of replicas.
+During the restore process, the OADP Velero plug-ins scale down the `DeploymentConfig` objects and restore the pods as standalone pods. This is done to prevent the cluster from deleting the restored `DeploymentConfig` pods immediately on restore and to allow Restic and post-restore hooks to complete their actions on the restored pods. The cleanup script shown below removes these disconnected pods and scales any `DeploymentConfig` objects back up to the appropriate number of replicas.
 ====
 +
 .`dc-restic-post-restore.sh` cleanup script
diff --git a/modules/oadp-creating-restore-hooks.adoc b/modules/oadp-creating-restore-hooks.adoc
@@ -6,7 +6,7 @@
 [id="oadp-creating-restore-hooks_{context}"]
 = Creating restore hooks
 
-You create restore hooks to run commands in a container in a pod while restoring your application by editing the `Restore` custom resource (CR).
+You create restore hooks to run commands in a container in a pod by editing the `Restore` custom resource (CR).
 
 You can create two types of restore hooks:
 
@@ -67,7 +67,7 @@ spec:
 <1> Optional: Array of namespaces to which the hook applies. If this value is not specified, the hook applies to all namespaces.
 <2> Currently, pods are the only supported resource that hooks can apply to.
 <3> Optional: This hook only applies to objects matching the label selector.
-<4> Optional: Timeout specifies the maximum amount of time Velero waits for `initContainers` to complete.
+<4> Optional: Timeout specifies the maximum length of time Velero waits for `initContainers` to complete.
 <5> Optional: If the container is not specified, the command runs in the first container in the pod.
 <6> This is the entrypoint for the init container being added.
 <7> Optional: How long to wait for a container to become ready. This should be long enough for the container to start and for any preceding hooks in the same container to complete. If not set, the restore process waits indefinitely.

Original file line number	Diff line number	Diff line change
@@ -24,14 +24,14 @@ After you delete the `Backup` CR and the associated object storage data, you can
`24`	`24`
`25`	`25`	* Choose one of the following actions to delete the `Backup` CR:
`26`	`26`
`27`		-** To delete the `Backup` CR and keep the associated object storage data, issue the following command:
	`27`	+** To delete the `Backup` CR and keep the associated object storage data, run the following command:
`28`	`28`	`+`
`29`	`29`	`[source,terminal]`
`30`	`30`	`----`
`31`	`31`	`$ oc delete backup <backup_CR_name> -n <velero_namespace>`
`32`	`32`	`----`
`33`	`33`
`34`		-** To delete the `Backup` CR and delete the associated object storage data, issue the following command:
	`34`	+** To delete the `Backup` CR and delete the associated object storage data, run the following command:
`35`	`35`	`+`
`36`	`36`	`[source,terminal]`
`37`	`37`	`----`
`@@ -40,5 +40,5 @@ $ velero backup delete <backup_CR_name> -n <velero_namespace>`
`40`	`40`	`+`
`41`	`41`	`Where:`
`42`	`42`	`+`
`43`		-<backup_CR_name>:: Specifies the name of the `Backup` custom resource.
`44`		-<velero_namespace>:: Specifies the namespace that contains the `Backup` custom resource.
	`43`	+<backup_CR_name>:: The name of the `Backup` custom resource.
	`44`	+<velero_namespace>:: The namespace that contains the `Backup` custom resource.