Certificates and DNS configuration


Using the master's private VM hostname, PE generates certificates which include the master's public fully qualified domain name and puppet as alternate DNS names.

For more information about EC2 hostnames, see the troubleshooting section.

Managing Azure ARM nodes by their private hostname (rather than the public hostname) keeps their hostnames consistent if, for example, the node is resized or changed to a different VM machine type. This requires less work when administering a virtual network.

Changing the master hostname and regenerating certificates

While not recommended, you can change the hostname of your master and use this hostname to generate new PE certificates. Do this before you connect any agents to the master.

Note: These instructions are specific to the PE installation contained in this image and include some minor variations and simplifications of the instructions outlined in the PE documentation.
  1. Connect to the master:
    ssh -i ~/.ssh/<private key>.pem puppetadmin@<Public IP or FQDN of PE Master>
  2. Wait for PE configuration to complete, and use the check_status.sh script to confirm its status.
  3. Stop all PE services:
    sudo /usr/local/bin/puppet resource service puppet ensure=stopped
    sudo /usr/local/bin/puppet resource service pe-puppetserver ensure=stopped
    sudo /usr/local/bin/puppet resource service pe-activemq ensure=stopped
    sudo /usr/local/bin/puppet resource service mcollective ensure=stopped
    sudo /usr/local/bin/puppet resource service pe-puppetdb ensure=stopped
    sudo /usr/local/bin/puppet resource service pe-postgresql ensure=stopped
    sudo /usr/local/bin/puppet resource service pe-console-services ensure=stopped
    sudo /usr/local/bin/puppet resource service pe-nginx ensure=stopped
    sudo /usr/local/bin/puppet resource service pe-orchestration-services ensure=stopped
    sudo /usr/local/bin/puppet resource service pxp-agent ensure=stopped
  4. Copy the SSL certificate directory /etc/puppetlabs/puppet/ssl/ to a backup location:
    sudo mv /etc/puppetlabs/puppet/ssl /etc/puppetlabs/puppet/ssl.backup

    Should anything go wrong during this process, you can restore certificates and your PE installation.

  5. Delete the local cached catalog, which will be invalidated by the new hostname:
    sudo rm -f /opt/puppetlabs/puppet/cache/client_data/catalog/*
  6. Set the Puppet master's new hostname. This depends on your configuration, and could be as simple as following these instructions, or this might entail configuring a DNS service like AWS's Route 53.
    1. Set the hostname: sudo hostnamectl set-hostname <NEW-MASTER-HOSTNAME>
    2. Add the hostname to /etc/hosts
    3. Add preserve_hostname: true to the main section of /etc/cloud/cloud.cfg, for example, immediately below disable_root: 1
  7. Verify that the master and agents can resolve the new hostname. Puppet must be able to contact this hostname to connect to PE services and complete the certificate generation process. Use the current admin user name if it has been changed from the default:
    ssh puppetadmin@<NEW-MASTER-HOSTNAME>
  8. Edit the master's /etc/puppetlabs/puppet/puppet.conf file and set the certname parameter in both the [main] and [master] sections to the new hostname.
    Note: For best compatibility, limit the certname to letters, numbers, periods, underscores, and dashes.
  9. Optional. To also include alternate DNS names, edit /etc/puppetlabs/enterprise/conf.d/pe.conf and set pe_install::puppet_master_dnsaltnames to a list of desired alternate hostnames.
    Note: If you want to change the alternate DNS names on the master later, you must repeat all of these steps.
  10. Remove the contents of the config files so Puppet can regenerate them with the new hostname:
    echo '' > /etc/puppetlabs/nginx/conf.d/proxy.conf
    echo '' > /etc/puppetlabs/nginx/conf.d/http_redirect.conf
    echo '' > /etc/puppetlabs/puppetdb/certificate-whitelist
    echo '' > /etc/puppetlabs/console-services/rbac-certificate-whitelist
    echo '<beans></beans>' > /etc/puppetlabs/activemq/activemq.xml
  11. Remove the old hostname from /etc/puppetlabs/puppet/autosign.conf.
  12. Use the Puppet Enterprise module to regenerate certificates and restart PE services:
    sudo /usr/local/bin/puppet infrastructure configure --no-recover --modulepath /opt/puppetlabs/server/data/enterprise/modules

    Should anything go wrong during this process, you can restore certificates and your PE installation.

  13. Remove the former master hostname from the list of managed nodes:
    sudo /usr/local/bin/puppet node purge <FORMER-MASTER-HOSTNAME>
  14. Start a local agent run on the master:
    sudo /usr/local/bin/puppet agent -t
  15. To confirm the master's certname at any time, run this command:
    sudo /usr/local/bin/puppet config print certname

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.