ca_extend

Table of Contents

1. Overview
2. Description - What the module does and why it is useful
3. Setup - The basics of getting started with this module
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing
6. Development - Guide for contributing to the module

Overview

This module can extend a certificate authority (CA) that's about to expire or has already expired.

A Puppet CA certificate is only valid for a finite time (a new installation of PE 2019.x / Puppet 6.x will create a 15 year CA, while earlier versions will create a 5 year CA; and upgrading does not extend the CA.), after which it expires. When a CA certificate expires, Puppet services will no longer accept any certificates signed by that CA, and your Puppet infrastructure will immediately stop working.

If your CA certificate is expiring soon (or it's already expired), you need to:

• Generate a new CA certificate using the existing CA keypair.
• Distribute the new CA certificate to agents.

This module can automate those tasks.

Description

This module is composed of Plans and Tasks to extend the expiration date of the CA certificate in Puppet Enterprise (and Puppet Open Source) and distribute that CA certificate to agents.

Note that, with Puppet Open Source, if the CA certificate is only used by the Puppet CA and no other integrations, there is no further action to take after using the two Plans. However, if it is used for other integrations (such as SSL encrypted PuppetDB traffic) then those integrations will need to have their copy of the CA certificate updated. If the CA certificate is stored in any keystores, those will also need to be updated.

The functionality of this module is composed into two Plans:

• ca_extend::extend_ca_cert
  • Extend the CA certificate and configure the primary Puppet server and any Compilers to use that extended certificate.
• ca_extend::upload_ca_cert
  • Distribute the CA certificate to agents using any transport supported by Puppet Bolt, such as ssh, winrm, or pcp.

Regardless of whether the CA certificate is expired, the extend_ca_cert plan may be used to extend its expiration date in-place and configure the primary Puppet server and any Compilers to use it.

After the CA certificate has been extended, there are two methods for distributing it to agents.

• Using the ca_extend::upload_ca_cert plan or another method to copy the CA certificate to agents.
• Manually deleting ca.pem on agents and letting them download that file as part of the next Puppet agent run. The agent will download that file only if it is absent, so it must be deleted to use this method.

There are also two complementary tasks to check the expiration date of the CA certificate or any agent certificates.

• ca_extend::check_ca_expiry
  • Checks if the CA certificate expires by a certain date. Defaults to three months from today.
• ca_extend::check_agent_expiry
  • Checks if any agent certificate expires by a certain date. Defaults to three months from today.

If the CA certificate is expiring or expired, you must extend it as soon as possible.

Setup

This module requires Puppet Bolt >= 1.2.0 on either on the primary Puppet server or a workstation with connectivity to the primary.

The installation procedure will differ depending on the version of Bolt. If possible, using Bolt >= 3.0.0 is recommended. For example, this will install the latest Bolt version on EL 7.

sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-7.noarch.rpm
sudo yum install puppet-bolt

The following two sections show how to install the module dependencies depending on the installed version of Bolt.

Bolt >= 1.2.0 < 3.0.0

The recommended procedure for these versions is to use a Bolt Puppetfile. From within a Boltdir, specify this module and puppetlabs-stdlib as dependencies and run bolt puppetfile install. For example:

mkdir -p ~/Boltdir
cd !$

cat >>Puppetfile <<EOF
mod 'puppetlabs-stdlib'

mod 'puppetlabs-ca_extend'
EOF

bolt puppetfile install

Bolt >= 3.0.0

The recommended procedure for these versions is to use a Bolt Project. When creating a Bolt project, specify this module and puppetlabs-stdlib as dependencies and initialize the project. For example:

sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-7.noarch.rpm
sudo yum install puppet-bolt

If your primary Puppet server or workstation has internet access, the project can be initialized with the needed dependencies with the following:

mkdir ca_extend
cd !$

bolt project init expiry --modules puppetlabs-stdlib,puppetlabs-ca_extend

Otherwise, if your primary Puppet server or workstation operates behind a proxy, initialize the project without the --modules option

mkdir ca_extend
cd !$

bolt project init expiry

Then edit your bolt-project.yaml to use the proxy according to the documentation. Next, add the module dependencies to bolt-project.yaml:

---
name: expiry
modules:
  - name: puppetlabs-stdlib
  - name: puppetlabs-ca_extend

Finally, install the modules.

bolt module install

See the "Usage" section for how to run the tasks and plans remotely or locally on the primary Puppet server.

Dependencies

• A Puppet Bolt >= 1.21.0
• puppetlabs-stdlib
• A base64 binary on the primary Puppet server which supports the -w flag
• bash >= 4.0 on the primary Puppet server

Configuration

Inventory

This module works best with a Bolt inventory file to allow for simultaneous uploads to *nix and Windows agents. See the Bolt documentation for how to configure an inventory file. See the REFERENCE.md for a sample inventory file.

Alternatively, you can use an ssh config file if you will only use that transport to upload the CA certificate to agents. Bolt defaults to using the ssh transport, which in turn will use ~/.ssh/config for options such as username and private-key.

PuppetDB

A convenient way to specify targets for the ca_extend::upload_ca_cert plan is by connecting Bolt to PuppetDB, after which --query can be used to specify targets. See REFERENCE.md for an example.

PCP

Note that you cannot use the Bolt pcp transport if your CA certificate has already expired, as the PXP-Agent service itself depends upon a valid CA certificate.

Usage

First, check the expiration of the Puppet agent certificate by running the following command as root on the primary Puppet server:

/opt/puppetlabs/puppet/bin/openssl x509 -in "$(/opt/puppetlabs/bin/puppet config print hostcert)" -enddate -noout

If, and only if, the notAfter date printed has already passed, then the primary Puppet server certificate has expired and must be cleaned up before the CA can be regenerated. This can be accomplished by passing regen_primary_cert=true to the ca_extend::extend_ca_cert plan.

bolt plan run ca_extend::extend_ca_cert regen_primary_cert=true --targets <primary_fqdn> compilers=<comma_separated_compiler_fqdns> --run-as root

Note that if you are running extend_ca_cert locally on the primary Puppet server, you can avoid potential Bolt transport issues by specifying --targets local://$(hostname -f), e.g.

bolt plan run ca_extend::extend_ca_cert --targets local://$(hostname -f) --run-as root

bolt plan run ca_extend::upload_ca_cert cert=<path_to_cert> --targets <TargetSpec>

bolt task run ca_extend::check_ca_expiry --targets <TargetSpec>

bolt task run ca_extend::check_agent_expiry --targets <TargetSpec>

See REFERENCE.md for more detailed examples.

Reference

Puppet's security is based on a PKI using X.509 certificates.

This module's ca_extend::extend_ca_cert plan creates a new self-signed CA certificate using the same keypair as the prior self-signed CA. The new CA has the same:

• Keypair.
• Subject.
• Issuer.
• X509v3 Subject Key Identifier (the fingerprint of the public key).

The new CA has a different:

• Authority Key Identifier (just the serial number, since it's self-signed).
• Validity period (the point of the whole exercise).
• Signature (since we changed the serial number and validity period).

Since Puppet's services (and other services that use Puppet's PKI) validate certificates by trusting a self-signed CA and comparing its public key to the Signatures and Authority Key Identifiers of the certificates it has issued, it's possible to issue a new self-signed CA certificate based on a prior keypair without invalidating any certificates issued by the old CA. Once you've done that, it's just a matter of delivering the new CA certificate to every participant in the PKI.

How to Report an issue or contribute to the module

If you are a PE user and need support using this module or are encountering issues, our Support team would be happy to help you resolve your issue and help reproduce any bugs. Just raise a ticket on the support portal.

If you have a reproducible bug or are a community user you can raise it directly on the Github issues page of the module here. We also welcome PR contributions to improve the module. Please see further details about contributing here

Reference

Table of Contents

Tasks

• check_agent_expiry: Check the expiration date of all agent certificates
• check_ca_expiry: Check the expiration date of a CA certificate
• check_primary_cert: Check the expiration date of the primary server cert
• configure_primary: Backup ssldir and copy newly generated CA certificate
• extend_ca_cert: Extend CA certificate expiry date

Plans

• ca_extend::extend_ca_cert: Plan that extends the Puppet CA certificate and configures the primary Puppet server and Compilers to use the extended certificate.
• ca_extend::get_agent_facts: A plan to work around BOLT-1168 so that one agent failing in apply_prep won't cause the whole plan to fail.
• ca_extend::upload_ca_cert: A plan to upload a given CA certificate to a number of Puppet agent nodes

Tasks

check_agent_expiry

Check the expiration date of all agent certificates

Supports noop? false

Parameters

date

Data type: Optional[String[1]]

YYYY-MM-DD date to test whether the certificates will expire by. Defaults to three months from today

check_ca_expiry

Check the expiration date of a CA certificate

Supports noop? false

Parameters

cert

Data type: Optional[String[1]]

Location of the CA certificate to check. Defaults to Puppet's default location

date

Data type: Optional[String[1]]

YYYY-MM-DD date to test whether the certificate will expire by. Defaults to three months from today

check_primary_cert

Check the expiration date of the primary server cert

Supports noop? false

configure_primary

Backup ssldir and copy newly generated CA certificate

Supports noop? false

Parameters

new_cert

Data type: String

Location of the newly generated CA certificate

regen_primary_cert

Data type: Boolean

Flag to regerate the primary server's certificate. Set to true to perform the regeneration

extend_ca_cert

Extend CA certificate expiry date

Supports noop? false

Plans

ca_extend::extend_ca_cert

Plan that extends the Puppet CA certificate and configures the primary Puppet server and Compilers to use the extended certificate.

Examples

Extend the CA cert and regenerate the primary agent cert locally on the primary Puppet server

bolt plan run ca_extend::extend_ca_cert regen_primary_cert=true --targets local://$(hostname -f) --run-as root

Extend the CA cert by running the plan remotely

bolt plan run ca_extend::extend_ca_cert --targets <primary_fqdn> --run-as root

Parameters

The following parameters are available in the ca_extend::extend_ca_cert plan:

• targets
• compilers
• ssldir
• regen_primary_cert

targets

Data type: TargetSpec

The target node on which to run the plan. Should be the primary Puppet server

compilers

Data type: Optional[TargetSpec]

Optional comma separated list of compilers to upload the certificate to

Default value: undef

ssldir

Data type: Any

Location of the ssldir on disk

Default value: '/etc/puppetlabs/puppet/ssl'

regen_primary_cert

Data type: Any

Whether to also regenerate the agent certificate of the primary Puppet server

Default value: false

ca_extend::get_agent_facts

A plan to work around BOLT-1168 so that one agent failing in apply_prep won't cause the whole plan to fail.

Parameters

The following parameters are available in the ca_extend::get_agent_facts plan:

• nodes

nodes

Data type: TargetSpec

The targets to run apply_prep on

ca_extend::upload_ca_cert

A plan to upload a given CA certificate to a number of Puppet agent nodes

Parameters

The following parameters are available in the ca_extend::upload_ca_cert plan:

• nodes
• cert

nodes

Data type: TargetSpec

The targets to upload the certificate to

cert

Data type: String

The location of the CA certificate on disk of the local machine

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

v3.0.0 (2021-08-18)

Full Changelog

Changed

• Remove harmful terms from ca_extend #40 (gavindidrichsen)
• (SUP-2497) Remove EOL platforms and versions #39 (m0dular)

Added

• Updated the readme file to include "How to Report an issue or contribute to the module" section (SUP-2376) #16 (asselvakumar)
• Add option to regenerate the primary agent cert. #10 (m0dular)

Fixed

• Remove hard-coded paths from scripts #30 (m0dular)
• Check for cadir during primary cert regen #28 (m0dular)

* This Changelog was automatically generated by github_changelog_generator