5.3.2. HOWTO Move a Client to a new Puppet Server

The following provides details on how to move an client to a new Puppet Server.


All commands in this section should be run as the root user. On the Old Puppet Server

The following procedures will archive the agent’s artifacts from all environments, copy them to the new Puppet Server, and clean out the agent’s Hiera data. Archive the agent’s artifacts from all environments

  1. Archive the agent’s artifacts from all SIMP Secondary Environments:

find /var/simp/environments -name "*<agent-fqdn>*" -exec tar --selinux --xattrs -rpvf <agent-fqdn>_transfer.tar {} \;
  1. Archive the agent’s data from all SIMP Writable Environments:

find `puppet config --section server print vardir`/simp -name "*<agent-fqdn>*" -exec tar --selinux --xattrs -rpvf <agent-fqdn>_transfer.tar {} \;
  1. Archive the agent’s Hiera data from all Puppet Environments:


If you deploy your agents’ Hiera data from a Control Repository on the new Puppet server, ensure the agent’s Hiera data is in the relevant branches and skip this step.

find /etc/puppetlabs/code/environments/*/{data,hieradata} -name "<agent-hostname>.yaml" -exec tar --selinux --xattrs -rpvf <agent-hostname>_transfer.tar {} \;
find /etc/puppetlabs/code/environments/*/{data,hieradata} -name "<agent-fqdn>.yaml" -exec tar --selinux --xattrs -rpvf <agent-hostname>_transfer.tar {} \;
  1. Copy <agent-hostname>_transfer.tar to the new Puppet server. Remove agent-specific Hiera data from all environments


Skip this section if you deploy your agents’ Hiera data from a Control Repository

  1. Remove agent-specific Hiera data from all environments

find /etc/puppetlabs/code/environments -name "<agent-fqdn>.yaml" --delete


You may have Hiera YAML files with the short name of the host still in place, but those are too dangerous to automatically delete since they may match multiple hosts.

  1. Reload the puppetserver process after removing the agent’s Hiera data:

puppetserver reload On the New Puppet Server


This assumes that the new Puppet server is set up identically to the old Puppet server. If it isn’t, you will need to verify that the artifacts in the tar file are correctly placed.

  1. Unpack the <agent-hostname>_transfer.tar archive onto the system:

tar --selinux --xattrs -C / -xvf <agent-hostname>_transfer.tar
  1. Reload the puppetserver process:

puppetserver reload On The Agent


Make sure you are running these commands on the agent. If you run them on the server, there is a very high risk they will make your Puppet infrastructure inoperable. Remove the Agent Puppet Certificates

To remove all legacy SSL files, run:

rm -rf $(puppet config print --section agent ssldir) Update the Puppet Config

Update /etc/puppetlabs/puppet/puppet.conf with the following changes:

server = new.puppet.server.fqdn
ca_server = new.puppet.server.fqdn
ca_port = 8141 Run Puppet

Assuming the new Puppet server has been set up to properly accept the agent, execute a full Puppet run using puppet agent --test.

On the new puppet server you will need to sign off the certificate for the new client using puppetserver ca cert sign <new client name.

If everything was done properly, the agent will now be synchronized with the new Puppet server.

If you find issues, refer to the Setting up the Client and Troubleshooting Puppet Issues sections of the documentation, and ensure that the new Puppet CA is set up properly to trust the Puppet agent.