Regenerate infrastructure certificates

Regenerating certificates and security credentials—both private and public keys—created by the built-in PE certificate authority can help ensure the security of your installation in certain cases.

The process for regenerating certificates varies depending on your goal.
If your goal is to... Do this...
Upgrade to the intermediate certificate architecture introduced in Puppet 6.0.
Complete these tasks in order:

  1. Delete and recreate the certificate authority

  2. Regenerate compiler certificates, if applicable

  3. Regenerate agent certificates

  4. Regenerate replica certificates
Fix a compromised or damaged certificate authority.
Fix a compromised compiler certificate or troubleshoot SSL errors on compilers. Regenerate compiler certificates
Fix a compromised agent certificate or troubleshoot SSL errors on agent nodes. Regenerate agent certificates
Specify a new DNS alt name or other trusted data. Regenerate primary server certificates
Note: To support recovery, backups of your certificates are saved and the location of the backup directory is output to the console. If the command fails after deleting the certificates, you can restore your certificates with the contents of this backup directory.

Regenerate primary server certificates

Regenerate primary server certificates to specify a new DNS alt name or other trusted data. This process regenerates the certificates for all primary infrastructure nodes, including standalone PE-PostgreSQL nodes.

Before you begin

The puppet infrastructure run command leverages built-in Bolt plans to automate certain management tasks. To use this command, you must be able to connect using SSH from your primary server to any nodes that the command modifies. You can establish an SSH connection using key forwarding, a local key file, or by specifying keys in .ssh/config on your primary server. For more information, see Bolt OpenSSH configuration options.

To view all available parameters, use the --help flag. The logs for all puppet infrastructure run Bolt plans are located at /var/log/puppetlabs/installer/bolt_info.log.

On your primary server, log in as root, and run: 
puppet infrastructure run regenerate_primary_certificate
You can specify these optional parameters:
  • Use dns_alt_names to provide a comma-separated list of alternate DNS names to be added to the certificates generated for your primary server.
    Important: To ensure naming consistency, if your puppet.conf file includes a dns_alt_names entry, you must include the dns_alt_names parameter and pass in all alternative names included in the entry when regenerating your primary server certificate.
  • Use --tmpdir to specify a path to a directory to use for uploading and executing temporary files.
    Tip: You might need to set this parameter if the task fails with a permission denied error.
  • Use --force to force certificate regeneration in situations where your infrastructure is unhealthy due to a damaged certificate.

Regenerate compiler certificates

Regenerate compiler certificates to fix a compromised certificate or troubleshoot SSL errors on compilers, or if you recreated your certificate authority.

On your primary server, log in as root, and run the following command. Specify any additional parameters required for your environment and use case. 
puppet infrastructure run regenerate_compiler_certificate target=<COMPILER_HOSTNAME>
  • If you use DNS alternative names, specify dns_alt_names as a comma-separated list of names to add to agent certificates.
    Important: To ensure naming consistency, if your puppet.conf file includes a dns_alt_names entry, you must include the dns_alt_names parameter and pass in all alternative names included in the entry when regenerating your agent certificates.
  • If you recreated your certificate authority, or are otherwise unable to connect to the compiler with the orchestrator, specify --use-ssh and any additional parameters needed to connect over SSH.
Results
The compiler's SSL directory is backed up to /etc/puppetlabs/puppet/ssl_bak, its certificate is regenerated and signed, a Puppet run completes, and the compiler resumes its role in your deployment.

Regenerate agent certificates

Regenerate *nix or Windows agent certificates to fix a compromised certificate or troubleshoot SSL errors on agents, or if you recreated your certificate authority.

On your primary server, log in as root (or the administrator), and run the following command. Specify any additional parameters required for your environment and use case. 
puppet infrastructure run regenerate_agent_certificate agent=<AGENT_HOSTNAME_1>,<AGENT_HOSTNAME_2>
  • If you use DNS alternative names: Specify dns_alt_names as a comma-separated list of names to add to agent certificates.
    Important: To ensure naming consistency, if your puppet.conf file includes a dns_alt_names entry, you must include the dns_alt_names parameter and pass in all alternative names included in the entry when regenerating your agent certificates.
  • If you recreated your certificate authority or can't connect to nodes with the orchestrator: Specify clean_crl=true and --use-ssh, as well as any additional parameters needed to connect over SSH.
  • If you want to use a PuppetDB query to generate certificates for multiple agents: Specify the agent_pdb_query parameter to provide a query to use to collect a list of agents for which you want to regenerate certificates. Make sure the query only returns certnames, such as:
    facts[certname] { name='domain' and value ~ 'agent.node.com' }
    If you specify both agent and agent_pdb_query, the query results are combined with the specified agents.
  • If you want to include custom attributes or extension requests in regenerated certificates: Ensure that agents have the csr_attributes.yaml file containing the necessary custom attributes and extension requests, or specify the optional custom_attributes and extension_requests parameters in the plan. For example:
    puppet infrastructure run regenerate_agent_certificate agent=<agent_certname> extension_requests='{"pp_environment": "development"}'
    For more information, see CSR attributes and certificate extensions.
Results
Agent SSL directories are backed up to /etc/puppetlabs/puppet/ssl_bak (*nix) or C:/ProgramData/PuppetLabs/puppet/etc/ssl_bak (Windows), their certificates are regenerated and signed, a Puppet run completes, and the agents resume their role in your deployment.

Regenerate replica certificates

Regenerate replica certificates for your disaster recovery installation to specify a new DNS alt name or other trusted data, or if you recreated your certificate authority.

On your primary server, log in as root, and run the following command. Specify any additional parameters required for your environment and use case. 
puppet infrastructure run regenerate_replica_certificate target=<REPLICA_HOSTNAME>
  • If you use DNS alternative names, specify dns_alt_names as a comma-separated list of names to add to agent certificates.
    Important: To ensure naming consistency, if your puppet.conf file includes a dns_alt_names entry, you must include the dns_alt_names parameter and pass in all alternative names included in the entry when regenerating your agent certificates.
  • If you recreated your certificate authority, or are otherwise unable to connect to the replica with the orchestrator, specify --use-ssh and any additional parameters needed to connect over SSH.
Results
The replica's SSL directory is backed up to /etc/puppetlabs/puppet/ssl_bak, its certificate is regenerated and signed, a Puppet run completes, and the replica resumes its role in your deployment.

Delete and recreate the certificate authority

Recreate the certificate authority only if you're upgrading to the new certificate architecture introduced in Puppet 6.0, or if your certificate authority was compromised or damaged beyond repair.

Before you begin

The puppet infrastructure run command leverages built-in Bolt plans to automate certain management tasks. To use this command, you must be able to connect using SSH from your primary server to any nodes that the command modifies. You can establish an SSH connection using key forwarding, a local key file, or by specifying keys in .ssh/config on your primary server. For more information, see Bolt OpenSSH configuration options.

CAUTION: Replacing your certificate authority invalidates all existing certificates in your environment. Complete this task only if and when you're prepared to regenerate certificates for both your infrastructure nodes (including external PE-PostgreSQL in extra-large installations) and your entire agent fleet.
On your primary server, log in as root and run: 
puppet infrastructure run rebuild_certificate_authority
Results
The SSL and cert directories on your CA server are backed up with "_bak" appended to the end, CA files are removed and certificates are rebuilt, and a Puppet run completes.