How to migrate an OpsWorks for Puppet Enterprise server to Amazon Elastic Compute Cloud (Amazon EC2)

Important

The AWS OpsWorks for Puppet Enterprise service reached end of life on March 31, 2024 and has been disabled for both new and existing customers. We strongly recommend customers migrate their workloads to other solutions as soon as possible. For information about how to migrate your existing Puppet Enterprise servers, see How to migrate an OpsWorks for Puppet Enterprise server to Amazon Elastic Compute Cloud (Amazon EC2). If you have questions about migration, reach out to the AWS Support Team on AWS re:Post or through AWS Premium Support.

The instructions below describe how to migrate existing Puppet Enterprise servers to Amazon EC2, in case you want to continue using Puppet Enterprise for your configuration management needs outside of OpsWorks.

Step 1: Contact Puppet to purchase a license

When you migrate your servers to EC2, the new instance does not come with a Puppet license. To purchase a license key, follow the instructions on the Puppet website.

Step 2: Get details about your OpsWorks for Puppet Enterprise server

Find and save the values for your OpsWorks for Puppet Enterprise server.

1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

   Copy the name of the existing Amazon S3 bucket for your OpsWorks for Puppet Enterprise server. The bucket name has the format: aws-opsworks-cm-server-name-random-string

2. Run the aws opsworks-cm describe-servers command to get the configuration for your OpsWorks for Puppet Enterprise server.

   aws opsworks-cm describe-servers \
      --server-name server-name \
      --region region

   Store the values for InstanceType, KeyPair, SubnetIds, SecurityGroupIds, InstanceProfileArn, and Endpoint from the response.

3. Use SSH to connect to the existing OpsWorks for Puppet Enterprise server. You can use Session Manager in the EC2 console instead of SSH.

   Run the following command.

   rpm -qa | grep opsworks-cm-puppet-enterprise | cut -d '-' -f 5

   The response provides the Puppet Enterprise version (for example, 2019.8.10). Store this value.

You will use SSH or Session manager for the next step.

Step 3: Make a backup of your OpsWorks for Puppet Enterprise server

1. Run the following commands to make a local backup.

   mkdir /tmp/puppet-backup/
   sudo /opt/puppetlabs/bin/puppet-backup create --dir=/tmp/puppet-backup/

2. Run the following command to store the name for the backup.

   ls /tmp/puppet-backup/
   PUPPET_BACKUP=$(ls /tmp/puppet-backup/)

3. Run the following command to upload your backup to an S3 bucket. Replace S3-Bucket with the value from step 1 in Step 2: Get details about your OpsWorks for Puppet Enterprise server.

   aws s3 cp /tmp/puppet-backup/PUPPET_BACKUP s3://S3_Bucket/tmp/puppet-backup/

   Store the PUPPET_BACKUP and S3_BUCKET values. You will import those values to the new EC2 instance.

You can exit the SSH or Session Manager session.

Step 4: Launch a new EC2 instance

Launch a new EC2 instance from the EC2 console at https://console.aws.amazon.com/ec2/ using the same configuration as the OpsWorks for Puppet Enterprise server.

Parameter name	Value
OS	Amazon Linux 2
Instance type	The InstanceType value from step 2 of Step 2: Get details about your OpsWorks for Puppet Enterprise server.
Key pair name	The KeyPair value from step 2 of Step 2: Get details about your OpsWorks for Puppet Enterprise server.
VPC	The VPC of the SubnetIds from step 2 of Step 2: Get details about your OpsWorks for Puppet Enterprise server.
Subnet	The SubnetIds from step 2 of Step 2: Get details about your OpsWorks for Puppet Enterprise server.
Select existing security group -> Common security groups	The SecurityGroupIds from step 2 of Step 2: Get details about your OpsWorks for Puppet Enterprise server.
Storage	At least 120 GB.
IAM instance profile	The InstanceProfileArn from step 2 of Step 2: Get details about your OpsWorks for Puppet Enterprise server.

If you want to create and attach an Elastic IP to the new instance, copy the instance ID of the new instance, and complete the steps in (Optional) Step 4.1: Create and attach an Elastic IP.

(Optional) Step 4.1: Create and attach an Elastic IP

By using an Elastic IP address, you can mask the failure of an instance or software by rapidly remapping the address to another instance in your account.

To create and associate an Elastic IP address

1. Sign in to the AWS Management Console and open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. Choose Elastic IPs.

3. Choose Allocate Elastic IP address.

4. From the Allocate Elastic IP address page, choose Allocate. This creates a Public IPv4 address.

5. Copy the Allocated IPv4 address.

6. From Actions, choose Associate Elastic IP address.

7. For Instance, enter the instance ID for the new instance.

8. Choose Associate.

Step 5: Install Puppet Enterprise on the new EC2 instance

Use SSH to connect to the new EC2 instance. You can use Session Manager in the EC2 console instead of SSH.

# switch to sudo user
sudo -i

# Setup environment variables
PUPPET_ENTERPRISE_VERSION=Puppet Enterprise version from step 2.3
hostname Public IPv4 DNS or Custom Domain if available

# Install Puppet Enterprise
curl -JLO https://pm.puppetlabs.com/puppet-enterprise/$PUPPET_ENTERPRISE_VERSION/puppet-enterprise-$PUPPET_ENTERPRISE_VERSION-el-7-x86_64.tar.gz
tar -xf puppet-enterprise-$PUPPET_ENTERPRISE_VERSION-el-7-x86_64.tar.gz

./puppet-enterprise-$PUPPET_ENTERPRISE_VERSION-el-7-x86_64/puppet-enterprise-installer

You can keep your SSH or Session Manager session open for the next step.

Step 6: Restore the backup on the new EC2 instance

# Setup environment variables
S3_BUCKET=S3 bucket name from step 2.1
PUPPET_BACKUP=Puppet backup file name from step 3.2

# download backup
aws s3 cp s3://$S3_BUCKET/tmp/puppet-backup/$PUPPET_BACKUP

# Prepare Puppet Enterprise backup to remove OpsWorks metadata
mkdir output
tar -xf $PUPPET_BACKUP -C output/
cd output/
rm -f opt/puppetlabs/facter/facts.d/opsworks.json
tar -cf ../$PUPPET_BACKUP *
cd ..
rm -rf output/

# Restore from backup
PATH=$PATH:/opt/puppetlabs/puppet/bin/
puppet-backup restore $PUPPET_BACKUP
puppet agent -t

You can access the Puppet console for the restored EC2 instance at https://Public IPv4 of the instance. You can find the Public IPv4 DNS on the instance's details page in the EC2 console. The login credentials are the same credentials you use to access your OpsWorks for Puppet Enterprise server.

You can keep your SSH or Session Manager session open for the next step.

Step 7: Configure your Puppet license

Follow the steps on the Puppet website to configure your license.

You can keep your SSH or Session Manager session open for the next step.

Step 8: Migrate your nodes

There are two types of domains supported by the OpsWorks for Puppet Enterprise servers:

• BYODC (Bring Your Own Domain and Certificate)

• OpsWorks endpoint

Step 8.1: For BYODC (Bring Your Own Domain and Certificate)

For these nodes, all you need to do is point the Custom Domain in your DNS provider to the Public IPv4 DNS or Public IPv4 address of the new EC2 instance.

Step 8.2: For OpsWorks endpoint

For an OpsWorks endpoint, the Puppet documentation recommends to uninstall the Puppet agent on the node and then install the Puppet agent using the newly restored Puppet Enterprise server.

Note

While Puppet doesn’t have an automated procedure to move an agent node, there are a few modules that Puppet community members have published on the Puppet Forge website to accomplish automated node migration. These modules include the pe_migrate module and a second migrate module by a different author. The modules on the Puppet Forge website are not supported by Puppet or OpsWorks unless explicitly noted within the Forge module. We recommend using caution with these modules and testing them before using widely.

The following sections provide the steps to uninstall and reinstall Puppet agents on Linux instances.

Topics

• Step 8.2.1: Copy the uninstaller from the Puppet server
• Step 8.2.2: Download the uninstaller and run it on a node
• Step 8.2.3: Reinstall the Puppet agent on a node

Step 8.2.1: Copy the uninstaller from the Puppet server

Before you uninstall the agent, be sure the node's IAM instance profile provides S3 ReadOnly permissions.

Run the following command to copy the uninstaller from the Puppet server to the S3 bucket.

aws s3 cp \
   /opt/puppetlabs/bin/puppet-enterprise-uninstaller \
   s3://$S3_BUCKET/tmp/puppet-enterprise-uninstaller

After running the command, you can log out of the Puppet server's SSH or Session Manager session.

Step 8.2.2: Download the uninstaller and run it on a node

Use SSH to connect to the node. You can use Session Manager in the EC2 console instead of SSH if the node is an EC2 instance.

sudo -i

S3_BUCKET=aws-opsworks-cm-abcdefg-uuhtyn6messn
aws s3 cp s3://$S3_BUCKET/tmp/puppet-enterprise-uninstaller /opt/puppetlabs/bin/
chmod 700 /opt/puppetlabs/bin/puppet-enterprise-uninstaller
/opt/puppetlabs/bin/puppet-enterprise-uninstaller

You can keep your SSH or Session Manager session open for the next step.

Step 8.2.3: Reinstall the Puppet agent on a node

Complete the following steps to reinstall the Puppet agent on a node.

Topics

• Step 8.2.3.1: Install the Puppet agent with the correct configuration
• Step 8.2.3.2: Accept the certificate in the Puppet console
• Step 8.2.3.3: Check the node into the Puppet Enterprise server

Step 8.2.3.1: Install the Puppet agent with the correct configuration

Run the following command to install the Puppet agent.

curl -k https://Public_IPv4_DNS:8140/packages/current/install.bash | bash

You can keep your SSH or Session Manager session open for step 8.2.2.3.

Step 8.2.3.2: Accept the certificate in the Puppet console

1. Go to the Puppet server's console at https://Public_IPv4_DNS.

2. Choose Certificates, and then Unsigned certificates.

3. Choose Accept to sign the Puppet agent's certificate.

Step 8.2.3.3: Check the node into the Puppet Enterprise server

Run the following command on the node to check it into the server.

puppet agent -t

The node should now be visible in the Puppet server's console.

Step 9: Delete your OpsWorks for Puppet Enterprise server

You can use either the OpsWorks console or AWS CLI to delete your OpsWorks for Puppet Enterprise server.

To delete your server using the OpsWorks console

1. Sign in to the AWS Management Console and open the AWS OpsWorks console at https://console.aws.amazon.com/opsworks/.

2. Choose Puppet Enterprise servers from the navigation pane.

3. On the Puppet Enterprise servers page, choose the server you want to delete.

4. From Actions, choose Delete Puppet Enterprise server.

To delete your server using the AWS CLI

Run the following command.

aws opsworks-cm delete-server \
   --server-name server-name \
   --region region