Backing up and restoring PE

Keep regular backups of your Puppet Enterprise (PE) infrastructure. Backups allow you to more easily migrate to new primary server hardware, migrate your PE installation after a major OS upgrade, troubleshoot your installation, and quickly recover from system failures.

Note: These instructions are intended only for standard installations without disaster recovery.
Important: Store your backups in a secure, centralized location that you can access if your primary server fails.
You can use the puppet-backup command to back up and restore your primary server. You can't use this command to back up compilers. By default, the backup command creates a backup of:
  • Your PE configuration, including license, classification, and RBAC settings. However, configuration backup does not include Puppet gems or Puppet Server gems.

  • PE CA certificates and the full SSL directory.

  • The Puppet code deployed to your code directory at backup time.

  • PuppetDB data, including facts, catalogs and historical reports.

Each time you create a new backup, PE creates a single, timestamped backup file, named in the format pe_backup-<TIMESTAMP>.tgz. This file includes everything you're backing up. By default, PE writes backup files to /var/puppetlabs/backups, but you can change this location when you run the backup command. When you restore, specify the backup file you want to restore from.

If you are restoring to a previously existing primary server, uninstall and reinstall PE first. If you are restoring or migrating to a primary server with a different hostname, you can redirect your agents to the new primary server during the restore process. In both cases, you must restore to the same PE version used to create your backups. If your installation includes disaster recovery, you must complete the restore process before reprovisioning a new replica.

Customizing backup and restore scope

By default, backup and restore functions include your Puppet configuration, certificates, code, and PuppetDB. However, you can limit the scope of backup and restore with command line options. This allows you to back up to or restore from multiple files. This is useful if you want to back up some parts of your infrastructure more often than others.

For example, if you have frequent code changes, you might back up the code more often than you back up the rest of your infrastructure. When you limit backup scope, the backup file contains only the specified parts of your infrastructure. Be sure to give your backup file a name that identifies the scope so that you always know what a given file contains.

During restore, you must restore all scopes: code, configuration, certificates, and PuppetDB. However, you can restore each scope from different files, either by restoring from backup files with limited scope or by limiting the scope of the restore. For example, by specifying scope when you run the restore command, you could restore code, configuration, and certificates from one backup file and PuppetDB from a different one.

Back up your infrastructure

PE backup creates a copy of your primary server, including configuration, certificates, code, and PuppetDB. Backup can take up to several hours depending on the size of PuppetDB.

Before you begin
To optionally encrypt your backup, you must import your GPG public key to your primary server.
Note: Ensure pg_repack won't run prior to or during the backup/restore process.
By default, PE backs up files to /var/puppetlabs/backups.
  1. On your primary server, run sudo puppet-backup create --dir=<BACKUP_DIRECTORY>, specifying a separate disk as your backup directory.
    You can specify these optional parameters:
    • --name=<BACKUP_NAME> – Specifies a name for the backup file. Default: pe_backup-<TIMESTAMP>.tgz
    • --pe-environment=<ENVIRONMENT> – Specifies an environment to back up. To ensure configuration is recovered correctly, this must be the environment where your primary server is located. Default: production
    • --scope=<SCOPE_LIST> – Specifies the data to back up: certs, code, config, puppetdb. Default: all
    • --gpgkey=<KEY_ID> – Specifies a GPG key ID to use for encrypting the backup file.
    • --force – Bypasses validation checks and ignore warnings.
  2. Back up the secret keys directory located at /etc/puppetlabs/orchestration-services/conf.d/secrets/
    Secure the keys as you would any sensitive information.
    CAUTION: The backup command does not include the secret keys. You must back up this information separately.

Restore your infrastructure

Use the restore commands to migrate your primary server to a new host or to recover from system failure.

Before you begin
To decrypt an encrypted backup, you must import the GPG key pair (public and private keys) used for encryption to your new primary server.
Note: Ensure pg_repack won't run prior to or during the backup/restore process.
  1. If you are restoring to an existing primary server, purge any existing PE installation.
    1. On your primary server, uninstall PE by running sudo /opt/puppetlabs/bin/puppet-enterprise-uninstaller -p -d
    2. Ensure that the directories /opt/puppetlabs/ and /etc/puppetlabs/ are no longer present on the system.
  2. Install PE on the primary server you are restoring to. This must be the same PE version used to create the backup files.
    1. If you don't have the PE installer script on the machine you want to restore to, download the installer tarball to the machine from the download site, and unpack it by running tar -xf <TARBALL_FILENAME>
    2. Navigate to the directory containing the install script. The installer script is located in the PE directory created when you unpacked the tarball.
    3. Install PE by running sudo ./puppet-enterprise-installer
  3. On your primary server, run sudo puppet-backup restore <BACKUP-FILENAME> to restore your PE infrastructure.
    You can specify these optional parameters:
    • --pe-environment=<ENVIRONMENT> – Specifies an environment to restore. Default: production
    • --scope=<SCOPE_LIST> – Specifies the data to restore: certs, code, config, puppetdb. Default: all
    • --force – Bypasses validation checks and ignore warnings.
  4. Restore your backup of the secret keys directory used to encrypt and decrypt sensitive data stored in the inventory service.
    The secret keys directory is located at: /etc/puppetlabs/orchestration-services/conf.d/secrets/
    CAUTION: The restore command does not include the secret keys. You must restore this information separately.
  5. Ensure the secret key ownership is pe-orchestration-services:pe-orchestration-services.
  6. Restart the pe-orchestration-services service.
  7. If you restored PE onto a primary server with a different hostname than the original installation, and you have not configured the dns_alt_names setting in the pe.conf file, redirect your agents to the new primary server. An easy way to do this is by running a task with the Bolt task runner.
    1. Download and install Bolt , if you don't already have it installed.
    2. Update the puppet.conf file to point all agents at the new primary server by running:
      bolt task run puppet_conf action=set section=agent setting=server value=<RESTORE_HOSTNAME> --nodes <COMMA-SEPARATED LIST OF NODES>
      bolt task run puppet_conf action=set section=main setting=server value=<RESTORE_HOSTNAME> --nodes <COMMA-SEPARATED LIST OF NODES>
    3. Run puppet agent -t --no-use_cached_catalog on the newly restored primary server twice to apply changes and then restart services.
    4. Run puppet agent -t --no-use_cached_catalog on all agent nodes to test connection to the new primary server.
  8. If your infrastructure had Code Manager enabled when your backup file was created, deploy your code by running:
    puppet-access login
    puppet code deploy --all --wait
  9. If your installation includes disaster recovery, reprovision a new replica.

Directories and data backed up

These are the directories and data included in PE backups.

Scope Directories and databases backed up
certs
  • /etc/puppetlabs/puppet/ssl/

code
  • /etc/puppetlabs/code/

  • /etc/puppetlabs/code-staging/

  • /opt/puppetlabs/server/data/puppetserver/filesync/storage/

config
  • Orchestrator database

  • RBAC database

  • Classifier database

  • /etc/puppetlabs/ , except:

    • /etc/puppetlabs/code/

    • /etc/puppetlabs/code-staging/

    • /etc/puppetlabs/puppet/ssl

  • /opt/puppetlabs/ , except:

    • /opt/puppetlabs/puppet

    • /opt/puppetlabs/server/pe_build

    • /opt/puppetlabs/server/data/packages

    • /opt/puppetlabs/server/apps

    • /opt/puppetlabs/server/data/postgresql

    • /opt/puppetlabs/server/data/enterprise/modules

    • /opt/puppetlabs/server/data/puppetserver/vendored-jruby-gems

    • /opt/puppetlabs/bin

    • /opt/puppetlabs/client-tools

    • /opt/puppetlabs/server/share

    • /opt/puppetlabs/server/data/puppetserver/filesync/storage

    • /opt/puppetlabs/server/data/puppetserver/filesync/client

puppetdb
  • PuppetDB

  • /opt/puppetlabs/server/data/puppetdb
    Note: The stockpile directory is excluded from backup.