Skip to main content

ACME-based enrollment

Follow these steps to get certificates from DigiCert​​®​​ Trust Lifecycle Manager into your Puppet environment using the ACMEv2 protocol to generate requests and download the resulting certificates.

Before you begin

In Trust Lifecycle Manager, you need a certificate profile with the 3rd-party ACME client enrollment method. The profile defines the general certificate properties and provides the required ACME URL and external account binding (EAB) credentials:

  • ACME Directory URL: The ACME server URL to request certificates from Trust Lifecycle Manager.

  • Key identifier (KID): Identifies the certificate profile in your Trust Lifecycle Manager account.

  • HMAC key: Used to encrypt and authenticate your account key during certificate requests.

Integration workflow

Step 1: Download the integration sample files

To begin the process of ACME-based certificate enrollment using Puppet, you’ll need to download and extract the provided sample files, then move them into the appropriate Puppet environment directory. This setup ensures that Puppet can properly find and use the configuration files and modules.

Important

The integration package linked below contains a site.pp file that uses a wildcard (default) node block. This means the certbot class is applied to all nodes by default. See Optional: Custom server and agent configuration to download an alternate package that has modified site.pp and init.pp files.

  1. Download the Puppet integration package to get the following environment files:

    • production/data/certbot.yaml: Contains key-value pairs for Certbot configuration, such as email, domain, and ACME server details, used by Hiera for data lookups.

    • production/environment.conf: Defines environment-specific settings, such as module paths and manifest locations, for the production environment.

    • production/hiera.yaml: Configures Hiera, Puppet’s hierarchical data lookup tool, specifying the data sources and hierarchy for resolving configuration data.

    • production/manifests/site.pp: The main manifest file for the production environment, defining node-specific configurations and including the necessary classes.

    • production/modules/certbot/manifests/init.pp: Contains the definition of the Certbot class, including resource declarations and configurations for managing Certbot installations and certificates.

  2. Copy the package contents to your Puppet environment directory.

    sudo -u puppet cp -r puppet-acme-integration/production/* /etc/puppetlabs/code/environments/production/

    Notice

    Copying the files as the puppet user ensures the files have the correct ownership and permissions.

    • If the files were not copied as the puppet user, copy as root (sudo), and then adjust the ownership to ensure proper access:

      sudo chown -R puppet:puppet /etc/puppetlabs/code/environments/production/

Step 2: Configure Puppet manifests and hiera data

In this step, you will configure the necessary Puppet manifests and hiera data to set up the environment for requesting and managing SSL/TLS certificates using Certbot.

  1. Navigate to the Puppet environment directory.

    cd /etc/puppetlabs/code/environments/production

  2. Update the hiera.yaml file to specify certbot.yaml as the data file. The modified hiera.yaml should look like this:

    version: 5
defaults:
  datadir: data
  data_hash: yaml_data

hierarchy:
  - name: "Certbot"
    path: "certbot.yaml"

  3. In the data directory, open the certbot.yaml file and update the following key/value pairs:

    • certbot::certbot_email: Your contact email for receiving certificate notifications.

    • certbot::certbot_domain: The domain name for which you want to issue the certificates.

    • certbot::certbot_http_port: The HTTP port to use for the ACME challenge (commonly port 80).

    • certbot::certbot_eab_kid: The Key ID (KID) for External Account Binding (EAB), provided by your ACME provider.

    • certbot::certbot_eab_hmac_key: The HMAC key for EAB.

    • certbot::certbot_server: The directory URL for the ACME provider (e.g., Let’s Encrypt).

    • certbot::certbot_rsa_key_size: The desired RSA key size for the certificates.

Step 3: Request a certificate

To request a certificate from Trust Lifecycle Manager on a Puppet server, run the following command:

sudo /opt/puppetlabs/bin/puppet apply /etc/puppetlabs/code/environments/production/manifests/site.pp

This command performs the following actions:

  • Reads the site.pp manifest, which includes the certbot class.

  • Applies the configurations defined in the certbot class from init.pp, including installing necessary packages, configuring Certbot, and requesting a certificate.

  • Downloads PEM-formatted certificates to /etc/letsencrypt/live/<certbot_domain>/.

Optional: Custom server and agent

In certain environments, you may need to apply different configurations for Puppet server and agent nodes, particularly if they have distinct roles or require separate handling. To specify different configurations for Puppet server and agent nodes, you can modify the site.pp file to include distinct classes or configurations for each node type.

  1. Download the alternate Puppet integration package, which contains a modified site.pp and init.pp files.

  2. Open site.pp located in the manifests directory and specify your Puppet server and agent nodes by including the appropriate classes. For example:

    node 'puppet-server.example.com' {
  include certbot::server
}

node 'puppet-agent.example.com' {
  include certbot::agent
}

    Note

    Replace puppet-server.example.com and puppet-agent.example.com with the actual hostnames of your server and agent nodes

  3. Continue with the steps above, starting from 2. Copy the package contents to your Puppet environment directory.

What's next?

Verify that the certificate files fullchain.pem and privkey.pem are located in the Certbot certificate directory.

ls /etc/letsencrypt/live/<certbot_domain>/

The certificate also appears in the Trust Lifecycle Manager Inventory view so you can monitor it and set up notifications.

Notice

Certbot automatically attempts to renew certificates before they expire. Ensure that the necessary cron jobs or systemd timers are set up to handle automatic renewals. This is typically handled by Certbot’s default installation but verify that it is configured properly.

In this section: