Change the hostname of a primary server in Puppet Enterprise

Follow these steps to change the hostname of your Puppet Enterprise primary server. These steps are not tested for installations that have a separate PE-PostgreSQL node.

If you want to change the DNS alt name of your primary server instead (a shorter, simpler process), follow the steps in our documentation to regenerate your primary server certificate.

Version and installation information

PE version: 2019.8 and later
Installation type: Supported architectures with or without disaster recovery. Not tested for installations that have a separate PE-PostgreSQL node.

Solution

Complete all of these steps on the primary server unless otherwise noted.

1. If you have a replica, use these steps to forget the replica. You will reprovision your replica on the same node in a later step.

   1. On the replica, stop all PE services.

       puppet resource service puppet ensure=stopped;
       puppet resource service pxp-agent ensure=stopped;
       puppet resource service pe-postgresql ensure=stopped;
       puppet resource service pe-puppetdb ensure=stopped;
       puppet resource service pe-puppetserver ensure=stopped;
       puppet resource service pe-console-services ensure=stopped;
       puppet resource service puppet ensure=stopped;

   2. On the primary server, run puppet infrastructure forget <REPLICA CERTNAME>

   3. Clean up pglogical artifacts. On the primary server, run

      puppet apply -e 'class {"puppet_enterprise":};["pe-classifier","pe-inventory","pe-activity","pe-rbac","pe-orchestrator"].each |$db| { puppet_enterprise::psql{ "Drop pglogical on ${db}": db => $db, command => "DROP EXTENSION pglogical CASCADE"}}'

2. On the primary server, to ensure that /etc/puppetlabs/enterprise/conf.d/user_data.conf is up to date, run puppet infrastructure recover_configuration

3. Disable Puppet runs by running puppet agent --disable

4. In the console, make the following changes.

   1. In the PE Agent, PE Infrastructure Agent, and PE Master node groups, in all class parameters, change each instance of the old certname to the new hostname.

   2. Unpin the old certname from the following node groups

      • PE Certificate Authority
      • PE Console
      • PE Database
      • PE Master
      • PE Orchestrator
      • PE PuppetDB

   3. Commit the changes.

      Note Do not apply them with a puppet run.

5. Run puppet node purge <OLD CERTNAME>

6. Stop all PE services. On the primary server, run

    puppet resource service puppet ensure=stopped;
    puppet resource service pxp-agent ensure=stopped;
    puppet resource service pe-postgresql ensure=stopped;
    puppet resource service pe-puppetdb ensure=stopped;
    puppet resource service pe-puppetserver ensure=stopped;
    puppet resource service pe-orchestration-services ensure=stopped;
    puppet resource service pe-console-services ensure=stopped;
    puppet resource service pe-nginx ensure=stopped;
    puppet resource service pe-bolt-server ensure=stopped;
    puppet resource service pe-ace-server ensure=stopped;

7. Change your primary server hostname. This varies by OS. For example, run hostnamectl set-hostname <NEW HOSTNAME>; systemctl restart network

8. On the primary server and replica (if you have one), replace all instances of the old certname with the new hostname in the following files:

   • /etc/puppetlabs/puppet/puppet.conf
   • /etc/puppetlabs/puppet/puppetdb.conf
   • /etc/puppetlabs/enterprise/conf.d/pe.conf
   • /etc/puppetlabs/enterprise/conf.d/user_data.conf

9. In /etc/puppetlabs/enterprise/conf.d/pe.conf, if you are using the default value for puppet_enterprise::puppet_master_host (which is %{::trusted.certname}), replace it with the new hostname.

10. Remove the following files. They will be regenerated in a later step with correct values for the new hostname.

    • /etc/puppetlabs/nginx/conf.d/proxy.conf
    • /etc/puppetlabs/nginx/conf.d/http_redirect.conf
    • /etc/puppetlabs/puppetdb/certificate-whitelist
    • /etc/puppetlabs/puppetdb/certificate-allowlist
    • /etc/puppetlabs/console-services/rbac-certificate-whitelist
    • /etc/puppetlabs/console-services/rbac-certificate-allowlist
    • /opt/puppetlabs/puppet/cache/client_data/catalog/<CERTNAME>.json

11. Make a backup of the existing cert and keys located at /etc/puppetlabs/puppet/ssl. Run

    mv /etc/puppetlabs/puppet/ssl/ <SOME OTHER DIRECTORY>/backup

    Note: Cert information is removed from /etc/puppetlabs/ in the next step, so back up the cert and keys to another directory.

12. Delete unneeded artifacts and configuration for the old certname. Run:

    • find /etc/puppetlabs/ -name <OLD CERTNAME>.* -delete

    • find /opt/puppetlabs/ -name <OLD CERTNAME>.* -delete

13. To generate a new certificate, run /opt/puppetlabs/bin/puppetserver ca generate --certname <NEW HOSTNAME> --ca-client --force

    You can safely ignore the warning about Puppet Server being offline.

14. Run puppet infrastructure configure --no-recover

    You can safely ignore errors generated by this command.

15. To enable the agent, run puppet agent --enable

16. Run puppet agent -t twice.

17. On all compilers

    1. Stop the pe-puppetserver and pe-puppetdb services. Run

       puppet resource service pe-puppetdb ensure=stopped;
       puppet resource service pe-puppetserver ensure=stopped;

    2. Delete the allowlist files etc/puppetlabs/puppetdb/certificate-whitelist and /etc/puppetlabs/puppetdb/certificate-allowlist, if they exist.

    3. Run puppet agent -t --server_list <NEW HOSTNAME>

18. Run puppet infrastructure status and check the output to ensure that all services are running normally on the primary server and any compilers.

19. If you have a replica, complete the following steps.

    1. On the replica, replace all instances of the old certname with the new hostname in /etc/puppetlabs/pxp-agent/pxp-agent.conf and /etc/puppetlabs/puppet/puppet.conf

    2. On the replica, delete the following allowlist files, if they exist:

       • /etc/puppetlabs/puppetdb/certificate-whitelist
       • /etc/puppetlabs/puppetdb/certificate-allowlist
       • /etc/puppetlabs/console-services/rbac-certificate-whitelist
       • /etc/puppetlabs/console-services/rbac-certificate-allowlist

    3. On the replica, generate a new certificate signing request (CSR) by running:

       1. puppet ssl clean

       2. puppet agent -t

    4. On the primary server, sign the CSR for the replica by running puppetserver ca sign --certname <REPLICA CERTNAME>

    5. On the replica, run puppet agent -t

       The Puppet run should restart pxp-agent service. Ensure that it is running with puppet resource service pxp-agent

    6. To start the puppet service, run puppet resource service puppet ensure=running

    7. On the primary server, to reprovision the replica, run puppet infrastructure provision replica --enable <REPLICA CERTNAME>