pe_migrate

Table of Contents

1. Overview
2. Setup Requirements
   • Limitations
3. Usage
   • Migration Guide
4. Advanced Usage

Overview

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.

Setup

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.

Limitations:

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.

Usage

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.

Migration Steps:

Step One: Backup the PE installation.

puppet task run pe_migrate::puppet_backup backupdir=</BACKUP/DIR> --nodes <PRIMARY SERVER FQDN>

Step Two: Transfer the backup.

puppet task run pe_migrate::backup_transfer backupdir=</BACKUP/DIR> targetdir=</BACKUP/DIR/ON/TARGET> targethost=<NEW PRIMARY SERVER FQDN> --nodes <PRIMARY SERVER FQDN>

Step Three: Install PE

On the new primary server, install the same version of PE.

Step Four: Restore the backup to the new PE installation.

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>

Step Five: Upgrade the new PE installation.

On the new primary server, perform an in-place upgrade to the desired version of PE by following the steps in our documentation here.

Step Six: Point agent nodes at the new primary server.

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.

Step Seven: Upgrade agent nodes.

If you migrated to a newer version of PE, upgrade the agent nodes.

Advanced Usage - Manual Migration

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.

Reference

Table of Contents

Classes

• pe_migrate::prep: Prepares a node for migration by ensuring Puppet package repos are available

Tasks

• agent_migrate: Points your agent nodes to the new primary server
• backup_transfer: Transfer backups to the target host.
• db_backup: Generate a backup of the Databases
• restore_ssldir: Restore the SSLDIR on the target host.
• ssl_backup: Generate a backup of the SSLDIR

Classes

pe_migrate::prep

Prepares a node for migration by ensuring Puppet package repos are available

Examples

include  pe_migrate::prep

Tasks

agent_migrate

Points your agent nodes to the new primary server

Supports noop? false

Parameters

newprimary

Data type: String

Hostname of the new primary server which your agents are being migrated to

backup_transfer

Transfer backups to the target host.

Supports noop? false

Parameters

backupdir

Data type: String

The directory where the backups were generated.

targetdir

Data type: String

The directory on the target host where the backups will be transferred.

targethost

Data type: String

The FQDN of the host you are migrating to.

environment

Data type: String

The environment that this module was installed in.

db_backup

Generate a backup of the Databases

Supports noop? false

Parameters

backupdir

Data type: String

The directory where the backups will be created. Should be the same location used for pe_migrate::ssl_backup.

restore_ssldir

Restore the SSLDIR on the target host.

Supports noop? false

Parameters

targetdir

Data type: String

The directory where the backups were generated.

targethost

Data type: String

The FQDN of the host you are migrating to.

privatekey

Data type: String

The path of the private key configured to access the target host.

ssl_backup

Generate a backup of the SSLDIR

Supports noop? false

Parameters

backupdir

Data type: String

The directory where the backups will be created.

Changelog

All notable changes to this project will be documented in this file.

Release 0.1.0

Features

Bugfixes

Known Issues