WIP OADP-2130: Updating OADP documentation

_attributes/common-attributes.adoc

@@ -43,6 +43,7 @@ endif::openshift-origin[]
 :hybrid-console: Red Hat Hybrid Cloud Console
 :hybrid-console-second: Hybrid Cloud Console
 :oadp-first: OpenShift API for Data Protection (OADP)
+:oadp-full: OpenShift API for Data Protection
 :oc-first: pass:quotes[OpenShift CLI (`oc`)]
 :product-registry: OpenShift image registry
 :rh-storage-first: Red Hat OpenShift Data Foundation
@@ -68,7 +69,7 @@ ifdef::openshift-origin[]
 endif::[]
 // Backup and restore
 :velero-domain: velero.io
-:velero-version: 1.9
+:velero-version: 1.11
 :launch: image:app-launcher.png[title="Application Launcher"]
 :mtc-short: MTC
 :mtc-full: Migration Toolkit for Containers

_topic_maps/_topic_map.yml

@@ -2779,43 +2779,117 @@ Topics:
   File: graceful-cluster-shutdown
 - Name: Restarting a cluster gracefully
   File: graceful-cluster-restart
-- Name: Application backup and restore
+- Name: OADP Application backup and restore
   Dir: application_backup_and_restore
   Topics:
+  - Name: Introduction to OADP
+    File: oadp-intro  
   - Name: OADP release notes
     File: oadp-release-notes
-  - Name: OADP features and plugins
-    File: oadp-features-plugins
-  - Name: Installing and configuring OADP
+  - Name: Installing OADP
     Dir: installing
     Topics:
-    - Name: About installing OADP
+    - Name: Introduction to installing OADP
       File: about-installing-oadp
-    - Name: Installing and configuring OADP with AWS
+    - Name: Installing the OADP Operator
+      File: oadp-installing-operator  
+    - Name: Installing OADP on multiple namespaces
+      File: about-installing-oadp-on-multiple-namespaces    
+  - Name: OADP features and plugins  
+    Dir: features-and-plugins
+    Topics:
+    - Name: OADP features and plugins  
+      File: oadp-features-plugins
+    - Name: OADP features
+      File: oadp-features  
+    - Name: OADP plugins
+      File: oadp-plugins
+    - Name: OADP Velero plugins
+      File: oadp-configuring-velero-plugins
+    - Name: OADP support for IBM Power and IBM zSystems
+      File: oadp-support-for-ibm        
+  - Name: Configuring OADP
+    Dir: installing
+    Topics:   
+    - Name: Configuring OADP with AWS
       File: installing-oadp-aws
-    - Name: Installing and configuring OADP with Azure
+    - Name: Configuring OADP with Azure
       File: installing-oadp-azure
-    - Name: Installing and configuring OADP with GCP
+    - Name: Configuring OADP with GCP
       File: installing-oadp-gcp
-    - Name: Installing and configuring OADP with MCG
+    - Name: Configuring OADP with MCG
       File: installing-oadp-mcg
-    - Name: Installing and configuring OADP with ODF
+    - Name: Configuring OADP with ODF
       File: installing-oadp-ocs
+    - Name: Configuring NooBaa for disaster recovery on ODF
+      File: oadp-configuring-noobaa-for-dr
+  - Name: Uninstalling OADP
+    Dir: installing 
+    Topics:    
     - Name: Uninstalling OADP
       File: uninstalling-oadp
-  - Name: Backing up and restoring
+  - Name: OADP Backing up and restoring
     Dir: backing_up_and_restoring
     Topics:
-    - Name: Backing up applications
+    - Name: Introduction to OADP backing up applications
       File: backing-up-applications
+    - Name: Creating a Backup CR
+      File: oadp-creating-backup-cr-doc
+    - Name: Backing up persistent volumes with CSI snapshots
+      File: oadp-backing-up-pvs-csi-doc 
+    - Name: Backing up applications with Restic
+      File: oadp-backing-up-applications-restic-doc
+    - Name: Creating backup hooks
+      File: oadp-creating-backup-hooks-doc  
+    - Name: Scheduling backups using Schedule CR
+      File: oadp-scheduling-backups-doc
+    - Name: Deleting backups
+      File: oadp-deleting-backups-doc         
     - Name: Restoring applications
       File: restoring-applications
+  - Name: OADP Data Mover     
+    Dir: installing
+    Topics:
+    - Name: Introduction to OADP Data Mover
+      File: data-mover-intro
+    - Name: Using Data Mover for CSI snapshots
+      File: oadp-using-data-mover-for-csi-snapshots-doc  
+    - Name: Using OADP 1.2 Data Mover with Ceph storage
+      File: oadp-12-data-mover-ceph-doc
+    - Name: Cleaning up after a backup using OADP 1.1 Data Mover
+      File: oadp-cleaning-up-after-data-mover-1-1-backup-doc
+  - Name: OADP debugging with Velero     
+    Dir: velero
+    Topics: 
+    - Name: Introduction to Velero
+      File: velero-intro
+    - Name: Installing Velero CLI
+      File: velero-troubleshooting-install-installing
+    - Name: Debugging Velero resources with the OpenShift CLI tool
+      File: oadp-debugging-oc-cli-doc
+    - Name: Debugging Velero resources with the Velero CLI tool
+      File: migration-debugging-velero-resources-doc
+    - Name: Debugging with Velero and admission webhooks
+      File: issues-with-velero-and-admission-workbooks-doc        
   - Name: Troubleshooting
-    File: troubleshooting
+    Dir: troubleshooting
+    Topics:
+    - Name: OADP troubleshooting  
+      File: troubleshooting
+    - Name: Pods crashing or restarting due to lack of memory or CPU
+      File: oadp-pod-crash-resource-request-doc 
+    - Name: OADP installation issues
+      File: oadp-installation-issues-doc
+    - Name: OADP Backup and Restore CR issues
+      File: oadp-backup-restore-cr-issues-doc
+    - Name: Restic issues
+      File: oadp-restic-issues-doc
+    - Name: Using the must-gather tool
+      File: migration-using-must-gather-doc         
   - Name: OADP API
     File: oadp-api
   - Name: Advanced OADP features and functionalities
-    File: oadp-advanced-topics
+    File: oadp-advanced-topics       
 - Name: Control plane backup and restore
   Dir: control_plane_backup_and_restore
   Topics:

backup_and_restore/application_backup_and_restore/backing_up_and_restoring/backing-up-applications.adoc

@@ -1,12 +1,12 @@
 :_content-type: ASSEMBLY
 [id="backing-up-applications"]
-= Backing up applications
+= Introduction to backing up applications
 include::_attributes/common-attributes.adoc[]
 :context: backing-up-applications
 
 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/backing-up-applications.adoc#oadp-creating-backup-cr_backing-up-applications[Creating a Backup CR].
+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-doc.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.
 
@@ -15,25 +15,27 @@ For more information about CSI volume snapshots, see xref:../../../storage/conta
 :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/backing-up-applications.adoc#oadp-backing-up-pvs-csi_backing-up-applications[Backing up persistent volumes with CSI snapshots].
+* 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/backing-up-applications.adoc#oadp-backing-up-applications-restic_backing-up-applications[Backing up applications with Restic].
+* 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 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/backing-up-applications.adoc#oadp-creating-backup-hooks_backing-up-applications[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/backing-up-applications.adoc#oadp-scheduling-backups_backing-up-applications[Scheduling backups].
+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#oadp-scheduling-backups-doc[Scheduling backups].
+////
 include::modules/oadp-creating-backup-cr.adoc[leveloffset=+1]
 include::modules/oadp-backing-up-pvs-csi.adoc[leveloffset=+1]
 include::modules/oadp-backing-up-applications-restic.adoc[leveloffset=+1]
 include::modules/oadp-using-data-mover-for-csi-snapshots.adoc[leveloffset=+1]
+////
 
-[id="oadp-12-data-mover-ceph"]
+////
+[id="oadp-12-data-mover-ceph-mod"]
 == Using OADP 1.2 Data Mover with Ceph storage
 
 You can use OADP 1.2 Data Mover to backup and restore application data for clusters that use CephFS, CephRBD, or both.
@@ -44,10 +46,12 @@ OADP 1.2 Data Mover leverages Ceph features that support large-scale environment
 ====
 The CephFS shallow copy feature is a back up feature. It is not part of restore operations.
 ====
+////
 
-include::modules/oadp-ceph-prerequisites.adoc[leveloffset=+2]
+//include::modules/oadp-ceph-prerequisites.adoc[leveloffset=+2]
 
-[id="defining-crs-for-12-data-mover"]
+////
+[id="defining-crs-for-12-data-mover-doc"]
 === Defining custom resources for use with OADP 1.2 Data Mover
 
 When you install {rh-storage-first}, it automatically creates default CephFS and a CephRBD `StorageClass` and `VolumeSnapshotClass` custom resources (CRs). You must define these CRs for use with OpenShift API for Data Protection (OADP) 1.2 Data Mover.
@@ -103,27 +107,29 @@ The cleanup consists of deleting the following resources:
 * Cluster resources
 * Volume snapshot backups (VSBs) after a backup procedure that is either run by a schedule or is run repetitively
 
-include::modules/oadp-cleaning-up-after-data-mover-snapshots.adoc[leveloffset=+2]
+//include::modules/oadp-cleaning-up-after-data-mover-snapshots.adoc[leveloffset=+2]
 
 [id="deleting-cluster-resources"]
 === Deleting cluster resources
 
 OADP 1.1 Data Mover might leave cluster resources whether or not it successfully backs up your container storage interface (CSI) volume snapshots to a remote object store.
 
-include::modules/oadp-deleting-cluster-resources-following-success.adoc[leveloffset=+3]
-include::modules/oadp-deleting-cluster-resources-following-failure.adoc[leveloffset=+3]
+//include::modules/oadp-deleting-cluster-resources-following-success.adoc[leveloffset=+3]
+//include::modules/oadp-deleting-cluster-resources-following-failure.adoc[leveloffset=+3]
 
 include::modules/oadp-vsb-cleanup-after-scheduler.adoc[leveloffset=+2]
-
+////
 [role="_additional-resources"]
 .Additional resources
 * xref:../../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-installing-operators-from-operatorhub_olm-adding-operators-to-a-cluster[Installing Operators on clusters for administrators]
 * xref:../../../operators/user/olm-installing-operators-in-namespace.adoc#olm-installing-operators-in-namespace[Installing Operators in namespaces for non-administrators]
 
+////
 include::modules/oadp-creating-backup-hooks.adoc[leveloffset=+1]
 include::modules/oadp-scheduling-backups.adoc[leveloffset=+1]
 include::modules/oadp-deleting-backups.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
-* xref:../../../backup_and_restore/application_backup_and_restore/troubleshooting.adoc#velero-obtaining-by-downloading_oadp-troubleshooting[Downloading the Velero CLI tool]
+* xref:../../../backup_and_restore/application_backup_and_restore/velero/velero-troubleshooting-install-installing.adoc#velero-troubleshooting-install-installing[Downloading the Velero CLI tool]
+////

backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-applications-restic-doc.adoc

@@ -0,0 +1,54 @@
+// Module included in the following assemblies:
+//
+// * backup_and_restore/application_backup_and_restore/backing_up_and_restoring/backing-up-applications.adoc
+
+:_content-type: PROCEDURE
+[id="oadp-backing-up-applications-restic-doc"]
+= Backing up applications with Restic
+include::_attributes/common-attributes.adoc[]
+:context: backing-up-applications
+
+toc::[]
+
+If your cloud provider does not support snapshots or if your applications are on NFS data volumes, you can create backups by using Restic.
+
+[NOTE]
+====
+link:https://restic.net/[Restic] is installed by the OADP Operator by default.
+====
+
+Restic integration with OADP provides a solution for backing up and restoring almost any type of Kubernetes volume. This integration is an addition to OADP’s capabilities, not a replacement for existing functionality.
+
+You back up Kubernetes resources, internal images, and persistent volumes with Restic by editing the `Backup` custom resource (CR).
+
+You do not need to specify a snapshot location in the `DataProtectionApplication` CR.
+
+[IMPORTANT]
+====
+Restic does not support backing up `hostPath` volumes. For more information, see link:https://{velero-domain}/docs/v{velero-version}/restic/#limitations[additional Restic limitations].
+====
+
+.Prerequisites
+
+* You must install the OpenShift API for Data Protection (OADP) Operator.
+* You must not disable the default Restic installation by setting `spec.configuration.restic.enable` to `false` in the `DataProtectionApplication` CR.
+* The `DataProtectionApplication` CR must be in a `Ready` state.
+
+.Procedure
+
+* Edit the `Backup` CR, as in the following example:
++
+[source,yaml]
+----
+apiVersion: velero.io/v1
+kind: Backup
+metadata:
+  name: <backup>
+  labels:
+    velero.io/storage-location: default
+  namespace: openshift-adp
+spec:
+  defaultVolumesToRestic: true <1>
+...
+----
+<1> Add `defaultVolumesToRestic: true` to the `spec` block.

backup_and_restore/application_backup_and_restore/backing_up_and_restoring/oadp-backing-up-pvs-csi-doc.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * backup_and_restore/application_backup_and_restore/backing_up_and_restoring/backing-up-applications.adoc
+
+:_content-type: PROCEDURE
+[id="oadp-backing-up-pvs-csi-doc"]
+= Backing up persistent volumes with CSI snapshots
+include::_attributes/common-attributes.adoc[]
+:context: backing-up-applications
+
+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.
+
+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].
+
+.Prerequisites
+
+* The cloud provider must support CSI snapshots.
+* You must enable CSI in the `DataProtectionApplication` CR.
+
+.Procedure
+
+* Add the `metadata.labels.velero.io/csi-volumesnapshot-class: "true"` key-value pair to the `VolumeSnapshotClass` CR:
++
+[source,yaml,subs="attributes+"]
+----
+apiVersion: snapshot.storage.k8s.io/v1
+kind: VolumeSnapshotClass
+metadata:
+  name: <volume_snapshot_class_name>
+  labels:
+    velero.io/csi-volumesnapshot-class: "true"
+driver: <csi_driver>
+deletionPolicy: Retain
+----
+
+You can now create a `Backup` CR.