Certificate authority and SSL

Puppet can use its built-in certificate authority (CA) and public key infrastructure (PKI) tools or use an existing external CA for all of its secure socket layer (SSL) communications.

Puppet uses certificates to verify the the identity of nodes. These certificates are issued by the certificate authority (CA) service of a Puppet primary server. When a node checks into the Puppet v for the first time, it requests a certificate. The Puppet primary server examines this request, and if it seems safe, creates a certificate for the node. When the agent node picks up this certificate, it knows it can trust the Puppet primary server, and it can now identify itself later when requesting a catalog.

After installing the Puppet Server, before starting it for the first time, use the puppetserver ca setup command to create a default intermediate CA. For more complex use cases, see the Intermediate and External CA documentation.

For backward compatibility, starting Puppet Server before running puppetserver ca setup creates the old single-cert CA. This configuration is not recommended, so if you are using Puppet 6, use the setup command instead.

Puppet provides two command line tools for performing SSL tasks:

  • puppetserver ca signs certificate requests and revokes certificates.

  • puppet ssl performs agent-side tasks, such as submitting a certificate request or downloading a node certificate.

What's changed in Puppet 6

Puppet 6 removes the puppet cert command and its associated certificate-related faces. In Puppet 6 you must use the new subcommands listed above instead.

Puppet 6 also introduces full support for intermediate CAs, the recommended architecture. This requires changes on both the server and the agent, so using it requires both the server and the agent to be updated to Puppet 6.

  • Puppet Server CA commands

    Puppet Server has a puppetserver ca command that performs certificate authority (CA) tasks like signing and revoking certificates. Most of its actions are performed by making HTTP requests to Puppet Server’s CA API, specifically the certificate_status endpoint. You must have Puppet Server running in order to sign or revoke certificates.

  • Intermediate CA

  • Autosigning certificate requests

    Before Puppet agent nodes can retrieve their configuration catalogs, they require a signed certificate from the local Puppet certificate authority (CA). When using Puppet’s built-in CA instead of an external CA, agents submit a certificate signing request (CSR) to the CA to retrieve a signed certificate after it's available.

  • CSR attributes and certificate extensions

    When Puppet agent nodes request their certificates, the certificate signing request (CSR) usually contains only their certname and the necessary cryptographic information. Agents can also embed additional data in their CSR, useful for policy-based autosigning and for adding new trusted facts.

  • Regenerating certificates in a Puppet deployment

    In some cases, you might need to regenerate the certificates and security credentials (private and public keys) that are generated by Puppet’s built-in PKI systems.

  • External CA

    This information describes the supported and tested configurations for external CAs in this version of Puppet. If you have an external CA use case that isn’t listed here, contact Puppet so we can learn more about it.

  • External SSL termination