Puppet Enterprise 2016.4

In some cases, you may find that you need to regenerate the SSL certificates and security credentials (private and public keys) that are generated by PE’s built-in certificate authority (CA). For example, you may have a Puppet master you need to move to a different network in your infrastructure, or you may find you need to regenerate all the certificates and security credentials in your infrastructure due to an unforeseen security vulnerability.

Regenerating certificates in PE: split installs

You can regenerate all certificates in a split PE deployment including the certificates and keys for the Puppet master, PuppetDB, PE console, and associated services.

See Regenerating certificates: mono installs for instructions on regenerating certificates in a monolithic PE deployment.

Regenerating your certificates involves the following tasks:

  1. Back up certificate directories
  2. (Optional) Delete and recreate the Puppet CA
  3. Regenerate the Puppet master, PE console, and PuppetDB certificates
  4. Configure PE

Before you begin, review the following information.

  • You must be logged in as a root to make these changes.

  • Regenerating your certificates will invalidate all existing authentication tokens. Once the regeneration process is complete, all PE users must generate new authentication tokens.

  • In the following instructions, when <CERTNAME> is used, it refers to the Puppet agent’s certname on each node. To find this value, run puppet config print certname before starting.

Back up certificate directories

If something goes wrong during the regeneration process, you may need to restore these directories so your deployment can stay functional. However, if you needed to regenerate your certs for security reasons and couldn’t, you should contact Puppet support as soon as you restore service so we can help you secure your site.

  1. On the Puppet master, back up the following directories.

    • /etc/puppetlabs/puppet/ssl/
    • /etc/puppetlabs/orchestration-services/ssl
  2. On the PuppetDB node, back up the following directories.

    • /etc/puppetlabs/puppet/ssl/
    • /etc/puppetlabs/puppetdb/ssl/
    • /opt/puppetlabs/server/data/postgresql/9.4/data/certs/
  3. On the PE console, back up the following directories.

    • /etc/puppetlabs/puppet/ssl/
    • /opt/puppetlabs/server/data/console-services/certs/

(Optional) Delete and recreate the Puppet CA

If needed, you can delete and recreate the Puppet CA before regenerating the rest of your split Puppet master certificates. This destroys the certificate authority and all other certificates. This is an optional step and is an meant for use in the event of a total compromise of your site, or some other unusual circumstance.

Run the following commands on the Puppet master.

  1. Delete the CA and clear all certs from your Puppet master.

    rm -rf /etc/puppetlabs/puppet/ssl/*
    
  2. Regenerate the CA.

    puppet cert list -a
    

    You should see this message: Notice: Signed certificate request for ca

Regenerate the Puppet master certificates

In this step, you’ll create the certificates for the split Puppet master.

Run the following commands on the Puppet master.

  1. Remove the Puppet master’s cached catalog.

    rm -f /opt/puppetlabs/puppet/cache/client_data/catalog/<CERTNAME>.json
    
  2. Clear the cert for the Puppet master.

    Tip: This step is not necessary if you deleted and recreated the CA cert.

    puppet cert clean <CERTNAME>
    

Clear the PuppetDB certificates

In this step, you clear the PuppetDB certificate.

  1. Remove PuppetDB’s cached catalog. On the PuppetDB node, run the following command:

    rm -f /opt/puppetlabs/puppet/cache/client_data/catalog/<CERTNAME>.json
    
  2. Clear the cert for the PuppetDB node. On the Puppet master node, run the following command:

    puppet cert clean <CERTNAME>
    
  3. Remove the certificates.

    rm -f /etc/puppetlabs/puppet/ssl/*/<CERTNAME>.pem
    

Clear the PE console certificates

In this step, you clear the PE console certificate.

  1. Remove the Pe console’s cached catalog. On the PE console node, run the following command:

    rm -f /opt/puppetlabs/puppet/cache/client_data/catalog/<CERTNAME>.json
    
  2. Clear the cert for the PE console node. On the Puppet master node, run the following command:

    puppet cert clean <CERTNAME>
    
  3. Remove the certificates.

    rm -f /etc/puppetlabs/puppet/ssl/*/<CERTNAME>.pem
    

Update the configuration of PE

In this step, you configure PE to generate new certificates for the component nodes and update the PE configuration.

  1. On the Puppet master node, run the following command:

    Note: Be sure to specify any DNS alt names you have in the pe_install::puppet_master_dnsaltnames array in /etc/puppetlabs/enterprise/conf.d/pe.conf. You can find the list of your current DNS alt names with puppet cert list <CERTNAME>. By default, PE uses puppet and puppet.domain.

    puppet enterprise configure --no-recover
    
  2. On the PuppetDB node, run the following command:

    puppet enterprise configure --no-recover
    
  3. On the PE console node, run the following command:

    puppet enterprise configure --no-recover
    
  4. Run Puppet on each node in the following order.

    a. Puppet master

    b. PuppetDB

    c. PE console

    A successful Puppet run on each node, in the given order, is necessary to ensure that PE’s services are properly configured.


Related links

Back to top