Restore

Restore Chef Automate from a filesystem backup or an Amazon S3 bucket backup.

Prerequisites

  1. On the restore host, download and unzip the Chef Automate command-line tool:

         curl https://packages.chef.io/files/current/latest/chef-automate-cli/chef-automate_linux_amd64.zip | gunzip - > chef-automate && chmod +x chef-automate
    
  2. To restore from filesystem backups, Chef Automate requires access to a backup directory in the configured location. Ensure access for the backup type used:

    1. To restore a network-attached filesystem backup, mount the shared backup directory to the same mount point configured at the time of the backup.
    2. To restore a backup directory that is not a network-attached filesystem, copy the backup directory to the configured location at the time of the backup.
    3. To restore a single-file backup archive, copy your archive to the restore host and extract it to the configured backup directory.
  3. To restore a backup to a host with a different fully qualified domain name (FQDN) than the original backup host, create a patch.toml file that specifies the new FQDN and provide it at restore time:

         [global.v1]
         fqdn = "<new-fqdn>"
    
         # To provide a cert and key for the restore host, uncomment and fill
         # these sections.
         # [[global.v1.frontend_tls]]
         # The TLS certificate for the load balancer frontend.
         # cert = """-----BEGIN CERTIFICATE-----
         # <certificate-for-new-fqdn>
         # -----END CERTIFICATE-----
         # """
    
         # The TLS RSA key for the load balancer frontend.
         # key = """-----BEGIN RSA PRIVATE KEY-----
         # <key-for-new-fqdn>
         # -----END RSA PRIVATE KEY-----
         # """
    

Restore From a Filesystem Backup

Meet the required prerequisites before beginning your restore process.

Restore in an Internet-Connected Environment

If you have configured the backup directory to a directory other than the default directory (/var/opt/chef-automate/backups), you must supply the backup directory. Without a backup ID, Chef Automate uses the most recent backup in the backup directory.

chef-automate backup restore </path/to/backups/>BACKUP_ID [--patch-config </path/to/patch.toml>] [--skip-preflight]

Use the --patch-config option with a configuration patch file to restore to a host with a different FQDN than that of the backup host. Use the --skip-preflight option to restore to a host with a pre-existing Chef Automate installation.

Restores from a filesystem backup may fail with incorrect directory permissions. Run the fix-repo-permissions command to address such issues:

sudo chef-automate backup fix-repo-permissions <path>

Restore in an Airgapped Environment

To restore a backup of an airgapped installation, you must specify the Airgap Installation Bundle used by the installation. If you have configured the backup directory to a directory that is not the default /var/opt/chef-automate/backups, then you must supply the backup directory. If you do not provide a backup ID, Chef Automate uses the most recent backup in the backup directory.

chef-automate backup restore --airgap-bundle </path/to/bundle> </path/to/backups/>BACKUP_ID [--patch-config </path/to/patch.toml>] [--skip-preflight]

Use the --patch-config option with a configuration patch file to restore to a host with a different FQDN than that of the backup host. Use the --skip-preflight option to restore to a host with a pre-existing Chef Automate installation.

Restores from a filesystem backup may fail with incorrect directory permissions. Run the fix-repo-permissions command to address such issues:

sudo chef-automate backup fix-repo-permissions <path>

Restore From an S3 Backup

Meet the required prerequisites before beginning your restore process.

To restore from an S3 bucket backup, run:

chef-automate backup restore s3://bucket_name/path/to/backups/BACKUP_ID [--patch-config </path/to/patch.toml>] [--skip-preflight]

Use the --patch-config option with a configuration patch file to restore to a host with a different FQDN than that of the backup host. Use the --skip-preflight option to restore to a host with a pre-existing Chef Automate installation.

Troubleshooting

Set the log level to debug before re-running a failed restore to output debug info to the Chef Automate log:

chef-automate debug set-log-level deployment-service debug

References

See the chef-automate backup restore command reference.