With the steps provided in this module you'll migrate the following components of your PE installation to a new host:
- PE configuration, including license, classification, and RBAC settings.
- 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.
This module should be installed on the current Puppet Primary Server (MoM).
The tasks provided in this module require the puppet-bolt and rsync packages. You can manually install these packages, or you can apply the pe_migrate::prep class to the Puppet Primary Server. This class will set up the Puppet Tools repository and install both puppet-bolt and rsync. Although you will need to manually install rsync on the target host.
Requirement: Utilization of this module also requires SSH access as root to the new host via an ssh-key.
Please Note: These instructions are for standard installations only. While the tasks provided in this module allow you to backup and restore your Puppet Enterprise installation on a target host, you will need to manually install PE on the target host before restoring the backup.
Additionally:
- If you are migrating from PE 2018.1 or older, you may need to remove the class mcollective_middleware_hosts from the PE Infrastructure node group before moving to PE 2019.x.
- PE 2018.1+ no longer includes MCollective. To prepare, migrate your MCollective work to Puppet orchestrator to automate tasks and create consistent, repeatable administrative processes.
While most of the migration can be automated with the use of these tasks, there are a few manual steps you will need to perform. Please follow the guideline below when performing a migration of your PE installation. The tasks can be ran from the command line as shown, or from the PE Console.
puppet task run pe_migrate::puppet_backup backupdir=</BACKUP/DIR> --nodes <PRIMARY SERVER FQDN>
puppet task run pe_migrate::backup_transfer backupdir=</BACKUP/DIR> targetdir=</BACKUP/DIR/ON/TARGET> targethost=<NEW PRIMARY SERVER FQDN> --nodes <PRIMARY SERVER FQDN>
On the new primary server, install the same version of PE.
puppet task run pe_migrate::puppet_restore privatekey=</PATH/TO/KEY> targetdir=</BACKUP/DIR/ON/TARGET> targethost=<NEW PRIMARY SERVER FQDN> --nodes <PRIMARY SERVER FQDN>
On the new primary server, perform an in-place upgrade to the desired version of PE by following the steps in our documentation here.
puppet task run pe_migrate::agent_migrate targethost=<NEW PRIMARY FQDN> --node-group <PE-Agent node-group-id>
Please Note: The PE Agent node group ID can be found in the PE Console under Node Groups -> PE Agent -> Activity. The ID will be in the very first entry.
If you migrated to a newer version of PE, upgrade the agent nodes.
Before utilizing the advanced steps in this module, please make sure you are unable to use the built-in puppet-backup command to backup and restore your PE installation. An example scenario where you would be unable to use the aforementioned command would be moving to a new host OS that does support the current version of Puppet Enterprise installed.
If you are unable to use the puppet-backup command, you may be able to use the advanced manual migration steps and tasks provided in this module.