Update backup_restore.md (#432)

* Update backup_restore.md

* fix typo

* Update documentation/backup_restore.md

* Update backup_restore.md

Integrating the extra note (added to SOLARCH 1160 branch) that was causing the conflict into my changes.

* Update backup_restore.md

* [ITHELP-87329] Update test-backup-restore.yaml (#446)

This looks like it should work with the `pull_request` event

---------

Co-authored-by: Ben Ford <[email protected]>

Author: J-Hunniford

documentation/backup_restore.md

@@ -14,63 +14,46 @@ If your PE installation is managed by PEADM, you can back up and restore PE usin
 1. Use the `peadm::backup` plan to create a backup of your primary server.
 2. Use the `peadm::restore` plan to restore PE from a `peadm::backup`.
 
-**Important:** If your PE installation is not managed by PEADM, you cannot use the `peadm::backup` and `peadm::restore` plans. For information on converting to a PEADM-managed installation, see [Convert](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/convert.md).  
+**Important:** If your PE installation is not managed by PEADM, you cannot use the `peadm::backup` and `peadm::restore` plans. For information about converting to a PEADM-managed installation, see [Convert](https://github.com/puppetlabs/puppetlabs-peadm/blob/main/documentation/convert.md).  
 
-When running the backup and restore plans, you can define the `backup_type` and `restore_type` parameters with either of the following values:
-* `recovery`: Use this type to create a full backup of your primary server, including data for all services. This allows you to restore your primary server and all services (including database services running on external servers) to the exact state they were in at the time of the backup.
-* `custom`: Use this type when you want to selectively back up and restore data for specific services. 
+You can specify the type of backup or restore plan you want to use. There are two types:  
+-	`recovery`: Use this type to create a full backup of your primary server, including data for all services. The recovery option allows you to restore your primary server and all services (including database services running on external servers) to the exact state they were in at the time of the backup.
+-	`custom`: Use this type when you want to back up and restore data for specific services.
 
 If no type is specified, the default is `recovery`.
 
-(When running the restore plan, you can use the `recovery-db` restore type to recover a failed database server (see [Recovering a broken database server in an extra-large installation](#recovering-a-broken-database-server-in-an-extra-large-installation)).)
-
-When backing up or restoring PE, you must use the `--targets` option to specify the hostname (FQDN) of your primary server.
-**Note**: the hostname of your primary server you are restoring to _must be equal_ to the hostname of the primary server you created the backup from.
-In other words, you can't change the hostname of your primary server during the recovery process.
- 
-The backup file created is named `pe-backup-YYYY-MM-DDTHHMMSSZ.tar.gz` and placed by default in `/tmp`. To specify a different location for the backup file, you can define the `output_directory` parameter.
-
-This example shows how to run a `recovery` backup which places the backup file in a custom location.  
-```
-bolt plan run peadm::backup --targets my.primary.vm backup_type=recovery output_directory=/custom_path
-```
-
-When restoring PE, you must define the `input_file` parameter to specify the path to the backup file you want to use. For example:
-```
-bolt plan run peadm::restore --targets my.primary.vm input_file="/tmp/my_backup.tar.gz"
-```
+**Important**: When restoring your installation, the hostname of the primary server you are restoring to _must be the same as_ the hostname of the primary server you created the backup from.
+You cannot successfully restore your installation if you change the hostname of your primary server during the recovery process.
 
 ## Using `recovery` backup and restore
 
 When you run a `recovery` backup plan, the primary server configuration is backed up in full. In the event of a primary server failure, this backup can be used to to restore your primary server and all services (including database services running on external servers) to the exact state they were in at the time of the backup.
 
-You can create a `recovery` backup as follows:
+### Create a `recovery` backup
+Run one of the following commands:
+- To create the backup file in the default location, run the `peadm::backup` plan, including the `--targets` option to specify the hostname (FQDN) of your primary server:
 ```
 bolt plan run peadm::backup --targets my.primary.vm backup_type=recovery
 ```
-Alternatively, because `recovery` is the default type, you can use this simplified command:
+- Alternatively, because `recovery` is the default type, you can use this simplified command:
 ```
 bolt plan run peadm::backup --targets my.primary.vm
 ```
-
-To restore your installation from this backup, run:
+- To place the backup file in a custom location, define the `output_directory` parameter. For example:
+```
+bolt plan run peadm::backup --targets my.primary.vm backup_type=recovery output_directory=/custom_path
+```
+### Restore your installation from a `recovery` backup
+Run the `peadm::restore` plan, including the `--targets` option to specify the hostname (FQDN) of your primary server and defining the `input_file` parameter to specify the path to the backup file you want to use. For example.  
 ```
 bolt plan run peadm::restore --targets my.primary.vm input_file="/tmp/my_backup.tar.gz"
 ```
-
-**Tip**: Restoring from a `recovery` backup restarts any services that are unavailable on the primary server.
+**Note**: Restoring from a `recovery` backup restarts any services that are unavailable on the primary server.
 
 ## Using `custom` backup and restore
-
-To specify the items that are backed up and restored, define the `backup_type` or `restore_type` parameters as `custom`.
-Otherwise, the default type is `recovery`.
-
-**Note:** To customize the list of items that are backed up and restored, you must define the `backup` and `restore` parameters, specifying the items you want to exclude.
-
-To specify the `custom` items, you can create and reference `params.json` files as shown in the following examples.
-
-To specify custom backup options:
-```json
+### Create a `custom` backup.
+To customize the items you back up, first create a JSON file in which you define the `backup_type` parameter as `custom` and define the `backup` parameter by specifying which items you want to exclude. For example:
+```
 {
   "backup_type" : "custom",
   "backup": {
@@ -85,15 +68,13 @@ To specify custom backup options:
   }
 }
 ```
-
-To create a backup using the options specified in this parameter file, run:
+When you have created the JSON file specifying your custom backup, run the `peadm::backup` plan, including the `--params` option and specifying the relevant filename (and file path if necessary). For example:  
 ```
 bolt plan run peadm::backup --targets my.primary.vm --params @params.json
 ```
-
-To specify custom restore options:
-
-```json
+### Restore custom items
+To customize the items you restore, create a JSON file in which you define the `restore_type` parameter as `custom`, define the `restore` parameter by specifying the items you want to exclude, and define the `input_file` parameter by specifying the path to the relevant backup file. For example,
+```
 {
   "restore_type" : "custom",
   "restore": {
@@ -110,7 +91,7 @@ To specify custom restore options:
 }
 ```
 
-To restore PE using the options specified in this parameter file, run:
+When you have created the JSON file specifying your custom restore options, run the `peadm::restore` plan, including the `--params` option and specifying the relevant filename (and file path if necessary). For example:
 ```
 bolt plan run peadm::restore --targets my.primary.vm --params @params.json
 ```
@@ -160,21 +141,22 @@ To do this, use the plan `peadm::util::init_db_server` as follows:
     bolt plan run peadm::util::init_db_server db_host=my.primary_db.vm pe_version=2023.5.0 install_pe=true pe_platform=el-8-x86_64
     ```
 
-    This plan will perform the following:
+    This plan performs the following tasks:
 
-     1. Clean the current certificate for the database server from the primary server.
-     1. Request a new certificate for the database server with the right extensions (peadm_role = puppet/puppetdb-database, peadm_availability_group=A).
-     1. Stop the puppetdb service on the compilers.
-     1. Prepare a `pe.conf` file on the database server for database installation
-     1. Install PE on the database server using the generated `pe.conf` file.
-     1. Configure the database as the primary puppetdb database in the XL installation.
-     1. Run puppet on the compilers to allow puppetdb on the compilers to be reconfigured with the new primary database server.
-     1. Start the puppetdb service on the compilers.
-     1. Restart the puppetserver service on the compilers.
+     1. Cleans the current certificate for the database server from the primary server.
+     1. Requests a new certificate for the database server with the right extensions (`peadm_role = puppet/puppetdb-database`, `peadm_availability_group=A`).
+     1. Stops the puppetdb service on the compilers.
+     1. Prepares a `pe.conf` file on the database server for database installation
+     1. Installs PE on the database server using the generated `pe.conf` file.
+     1. Configures the database as the primary puppetdb database in the XL installation.
+     1. Runs puppet on the compilers to allow puppetdb on the compilers to be reconfigured with the new primary database server.
+     1. Starts the puppetdb service on the compilers.
+     1. Restarts the puppetserver service on the compilers.
 
 1. Perform a `recovery-db` restore of your database server, specifying the backup file that you want to use. For example:
     ```
     bolt plan run peadm::restore --targets my.primary.vm input_file="/tmp/my_backup.tar.gz" restore_type=recovery-db
     ```
-   **Important**: You must use the `restore_type=recovery-db` parameter to recover the database server. 
+   **Important**: You must use the `restore_type=recovery-db` parameter to recover the database server.
+   
    **Important**: You must specify the primary server host node (not the database server host node) as the target for the restore plan.