Skip to content

Update backup_restore.md #432

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 26, 2024
Merged

Update backup_restore.md #432

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fcef9b2
Update backup_restore.md
J-Hunniford Apr 17, 2024
258618a
fix typo
J-Hunniford Apr 18, 2024
a37fa67
Update documentation/backup_restore.md
J-Hunniford Apr 19, 2024
d991c0e
Merge branch 'SOLARCH-1160' into edit-backup-restore
J-Hunniford Jun 14, 2024
7473bce
Update backup_restore.md
J-Hunniford Jun 14, 2024
75dab54
Update backup_restore.md
J-Hunniford Jun 14, 2024
e64d238
[ITHELP-87329] Update test-backup-restore.yaml (#446)
binford2k Jun 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/test-backup-restore.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name: "Backup and restore test"

on:
pull_request_target:
pull_request:
types: [ready_for_review]

workflow_dispatch:
Expand Down
92 changes: 37 additions & 55 deletions documentation/backup_restore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand All @@ -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": {
Expand All @@ -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
```
Expand Down Expand Up @@ -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.
Loading