Forge Home

ca_extend

A set of Bolt Plans and Tasks to extend the CA cert in Puppet Enterprise

17,652 downloads

761 latest version

4.9 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 3.5.0 (latest)
  • 3.4.0
  • 3.3.1
  • 3.3.0
  • 3.2.0
  • 3.1.0
  • 3.0.0
  • 2.1.0
  • 2.0.0
  • 1.2.1
  • 1.2.0
  • 1.1.1
  • 1.1.0
  • 1.0.1
released Nov 24th 2020
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.0 < 7.0.0
  • , , , , ,
Tasks:
  • extend_ca_cert
  • configure_master
  • check_agent_expiry
  • check_ca_expiry
Plans:
  • extend_ca_cert
  • get_agent_facts
  • upload_ca_cert

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-ca_extend', '1.2.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-ca_extend
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-ca_extend --version 1.2.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

puppetlabs/ca_extend — version 1.2.0 Nov 24th 2020

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 Master 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 Master 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.21.0 on either on the Master or an agent.

The recommended procedure for installation this module 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, to install Bolt and the required modules on a Master running EL 7:

sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-7.noarch.rpm
sudo yum install puppet-bolt
mkdir -p ~/Boltdir
cd !$

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

mod 'puppetlabs-ca_extend'
EOF

bolt puppetfile install

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

Dependencies

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

bolt plan run ca_extend::extend_ca_cert --targets <master_fqdn> compile_masters=<comma_separated_compile_master_fqdns> --run-as root

Note that if you are running extend_ca_cert locally on the Master, 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

(The master and (optional) compile_masters parameters are Bolt targets, not certificate data.)

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.

Development

Puppet Labs modules on the Puppet Forge are open source projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve. We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.

For more information, see our module contribution guide.