ca_extend
Version information
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:
- check_agent_expiry
- check_ca_expiry
- configure_master
- extend_ca_cert
Plans:
- extend_ca_cert
- get_agent_facts
- upload_ca_cert
Start using this module
Add this module to your Puppetfile:
mod 'puppetlabs-ca_extend', '1.1.1'
Learn more about managing modules with a PuppetfileDocumentation
ca_extend
Table of Contents
- Description
- Setup - The basics of getting started with ca_extend
- Usage - Configuration options and additional functionality
Description
A set of Plans and Tasks to extend the expiration date of the certificate for the certificate authority in Puppet Enterprise and open source Puppet and distribute the certificate to agent nodes.
Note that in open source Puppet, if the CA cert is only used by the Puppet CA and no other integrations, there is no further action to take after using the two main plans. However, if it is used for other purposes such as SSL encrypted PuppetDB traffic, then these integrations will need to have their copy of the cert updated. If it is stored in any keystores, these will also need to be updated.
The functionality of this module is divided into two main plans:
ca_extend::extend_ca_cert
- Extends the CA certificate and configures the master and any compile masters to use the new certificate
ca_extend::upload_ca_cert
- Distributes the certificate to any number of agents. Any protocol supported by Bolt can be used, such as
ssh
,winrm
, orPCP
.
- Distributes the certificate to any number of agents. Any protocol supported by Bolt can be used, such as
Regardless of whether the CA cert has passed expiration or not, the extend_ca_cert
plan may be used to extend its expiration date in-place and configure the master and compilers to use it.
After the CA is functional again (or if it had yet to expire), there are two options for distributing the new cert to agents.
- Using the
ca_extend::upload_ca_cert
plan or another method to copy the newca.pem
into place on agents. - Deleting
ca.pem
from agents and letting them download the file as part of the next Puppet agent run. The agent will re-download this file only if it is absent, so it must be deleted to get a new copy using this method.
There are also two complementary tasks to check the expiry of the CA cert and any agent certificates.
ca_extend::check_agent_expiry
- Checks if any agent certificates expire by a certain date. Defaults to 3 months from today
ca_extend::check_ca_expiry
- Checks if the CA certificate expires by a certain date. Defaults to 3 months from today
Setup
This module requires a Bolt installation >= 1.21.0 on either a client machine or the Puppet master
The recommended installation procedure for 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 an EL 7 master:
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
Dependencies
- A Bolt installation >= 1.21.0
- puppetlabs-stdlib >= 3.2.0 < 6.0.0
- A
base64
binary on the master which supports the-w
flag bash
>= 4.0 on the master
Configuration
Inventory
This module works best with a Bolt inventory file to support simultaneous uploads to *nix and Windows agents. See the Bolt documentation for how to configure the inventory. See the REFERENCE.md
for a sample inventory file.
Alternatively, one can use an ssh
config file if only using this protocol to connect to agents. Bolt defaults to using ssh
, which in turn will use ~/.ssh/config
for options such as the username and identity file.
Connecting to PuppetDB
Another convenient way to specify targets for the ca_extend::upload_ca_cert
plan is by connecting Bolt to PuppetDB, after which the --query can be used to specify a node list. See REFERENCE.md
for an example.
Examples
bolt plan run ca_extend::extend_ca_cert master=<master_fqdn> compile_masters=<comma_separated_compile_master_fqdns>
bolt plan run ca_extend::upload_ca_cert cert=<path_to_cert> --nodes <TargetSpec>
bolt task run ca_extend::check_ca_expiry --nodes <TargetSpec>
bolt task run ca_extend::check_agent_expiry --nodes <TargetSpec>
See REFERENCE.md
for more detailed example commands
Reference
Configuration
ssh
By default, Bolt will assume the ssh
transport and use ~/.ssh.config
for configuration options. Below is a sample config
file and command.
Host pe-*
User centos
Port 22
PasswordAuthentication no
IdentityFile /home/adrian/.ssh/id_rsa-acceptance
IdentitiesOnly yes
LogLevel ERROR
$ bolt plan run ca_extend::upload_ca_cert cert=/tmp/tmp.CuWtz3dmfx --run-as root --nodes pe-201815-agent
{
"success": {
"pe-201815-agent": {
"_output": "Uploaded '/tmp/tmp.CuWtz3dmfx' to 'pe-201815-agent:/etc/puppetlabs/puppet/ssl/certs/ca.pem'"
}
}
}
Inventory
See the Bolt inventory documentation for a full reference on how to use the inventory. Below is a sample inventory created using bolt-inventory-pdb and example commands.
$ cat pdb.yaml
---
query: "inventory[certname] {}"
groups:
- name: windows
query: "inventory[certname] { facts.osfamily = 'windows' }"
config:
transport: winrm
winrm:
user: Administrator
password: foo
ssl: false
- name: linux
query: "inventory[certname] { facts.kernel = 'Linux' }"
config:
transport: ssh
ssh:
user: centos
private-key: ~/.ssh/id_rsa-acceptance
host-key-check: false
$ /opt/puppetlabs/bolt/bin/bolt-inventory-pdb pdb.yaml -o ~/.puppetlabs/bolt/inventory.yaml
$ cat ~/.puppetlabs/bolt/inventory.yaml
---
query: inventory[certname] {}
groups:
- name: windows
query: inventory[certname] { facts.osfamily = 'windows' }
config:
transport: winrm
winrm:
user: Administrator
password: foo
ssl: false
nodes:
- ljbkgu9t2x3ohqd.delivery.puppetlabs.net
- name: linux
query: inventory[certname] { facts.kernel = 'Linux' }
config:
transport: ssh
ssh:
user: centos
private-key: "~/.ssh/id_rsa-acceptance"
host-key-check: false
nodes:
- pe-201815-master.puppetdebug.vlan
- pe-201815-agent.platform9.puppet.net
- pe-201815-compile.platform9.puppet.net
nodes:
- ljbkgu9t2x3ohqd.delivery.puppetlabs.net
- pe-201815-master.puppetdebug.vlan
- pe-201815-agent.platform9.puppet.net
- pe-201815-compile.platform9.puppet.net
$ bolt command run hostname --nodes linux
Started on pe-201815-compile.platform9.puppet.net...
Started on pe-201815-master.puppetdebug.vlan...
Started on pe-201815-agent.platform9.puppet.net...
Finished on pe-201815-master.puppetdebug.vlan:
STDOUT:
pe-201815-master.puppetdebug.vlan
Finished on pe-201815-compile.platform9.puppet.net:
STDOUT:
pe-201815-compile
Finished on pe-201815-agent.platform9.puppet.net:
STDOUT:
pe-201815-agent
Successful on 3 nodes: pe-201815-master.puppetdebug.vlan,pe-201815-agent.platform9.puppet.net,pe-201815-compile.platform9.puppet.net
Ran on 3 nodes in 0.62 seconds
$ bolt command run hostname --nodes windows
Started on ljbkgu9t2x3ohqd.delivery.puppetlabs.net...
Finished on ljbkgu9t2x3ohqd.delivery.puppetlabs.net:
STDOUT:
ljbkgu9t2x3ohqd
Successful on 1 node: ljbkgu9t2x3ohqd.delivery.puppetlabs.net
Ran on 1 node in 0.70 seconds
Plans
ca_extend::extend_ca_cert
Arguments
- master - Fully qualified domain name of the master containing the certificate authority
- compile_masters - Comma separated list of fully qualified domain names of compile masters
Steps
- Runs the
service
task to stop thepuppet
andpe-puppetserver
services on the master - Runs the
ca_extend::extend_ca_cert
task to dump the new cert to a file and return the path to the file and a base64 encoded string of its contents - Runs the
ca_extend::configure_master
task to backup thessl
directory to/var/puppetlabs/backups
, copy the new cert into place, and configure the master to use the new cert - Decodes the cert's contents and dump it to a temp file
- Uploads the new cert to any compile masters and configures them to use the new cert
Output
All steps in this plan are critical to extending the certificate, so the plan will fail if any step fails. The output consists of Bolt logging messages and any failures of the steps involved.
Example
$ bolt plan run ca_extend::extend_ca_cert master=pe-201815-master compile_masters=pe-201815-compile --run-as root
Starting: plan ca_extend::extend_ca_cert
Starting: command 'echo "test" | base64 -w 0 - &>/dev/null' on localhost
Finished: command 'echo "test" | base64 -w 0 - &>/dev/null' with 0 failures in 0.0 sec
INFO: Stopping puppet and pe-puppetserver services on pe-201815-master
Starting: task service on pe-201815-master
Finished: task service with 0 failures in 0.85 sec
Starting: task service on pe-201815-master
Finished: task service with 0 failures in 1.95 sec
INFO: Extending certificate on master pe-201815-master
Starting: task ca_extend::extend_ca_cert on pe-201815-master
Finished: task ca_extend::extend_ca_cert with 0 failures in 2.92 sec
INFO: Configuring master pe-201815-master to use new certificate
Starting: task ca_extend::configure_master on pe-201815-master
Finished: task ca_extend::configure_master with 0 failures in 95.72 sec
Starting: task service on pe-201815-master
Finished: task service with 0 failures in 1.64 sec
INFO: Configuring compile master(s) pe-201815-compile to use new certificate
Starting: file upload from /tmp/tmp.CuWtz3dmfx to /etc/puppetlabs/puppet/ssl/certs/ca.pem on pe-201815-compile
Finished: file upload from /tmp/tmp.CuWtz3dmfx to /etc/puppetlabs/puppet/ssl/certs/ca.pem with 0 failures in 0.59 sec
Starting: task run_agent on pe-201815-compile
Finished: task run_agent with 0 failures in 44.34 sec
INFO: CA cert decoded and stored at /tmp/tmp.CuWtz3dmfx
INFO: Run plan 'ca_extend::upload_ca_cert' to distribute to agents
Finished: plan ca_extend::extend_ca_cert in 148.06 sec
ca_extend::upload_ca_cert
Arguments
- cert - Location of the new certificate on disk.
This plan accepts any valid TargetSpec(s) specified by the --nodes
option.
Steps
- Collects facts from agents and separates them into groups of *nix and Windows
- Runs
upload_file
on each list of agents to distribute the cert - Constructs a JSON formatted object of the results of the uploads and returns it
Output
The output of this plan is a JSON object with two keys: success
and failure
. Each key contains any number of objects consisting of the agent certname and the output of the upload_file
command.
$ bolt plan run ca_extend::upload_ca_cert cert=/tmp/tmp.CuWtz3dmfx --run-as root --query 'inventory { }'
Starting: plan ca_extend::upload_ca_cert
Starting: plan ca_extend::get_agent_facts
Starting: install puppet and gather facts on pe-201815-agent.platform9.puppet.net, ljbkgu9t2x3ohqd.delivery.puppetlabs.net, pe-201815-master.puppetdebug.vlan, pe-201815-compile.platform9.puppet.net
Finished: install puppet and gather facts with 0 failures in 9.33 sec
Finished: plan ca_extend::get_agent_facts in 9.33 sec
Starting: plan facts
Starting: task facts on pe-201815-agent.platform9.puppet.net, ljbkgu9t2x3ohqd.delivery.puppetlabs.net, pe-201815-master.puppetdebug.vlan, pe-201815-compile.platform9.puppet.net
Finished: task facts with 0 failures in 6.27 sec
Finished: plan facts in 6.31 sec
Starting: file upload from /tmp/tmp.CuWtz3dmfx to C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\ca.pem on ljbkgu9t2x3ohqd.delivery.puppetlabs.net
Finished: file upload from /tmp/tmp.CuWtz3dmfx to C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\ca.pem with 0 failures in 1.07 sec
Starting: file upload from /tmp/tmp.CuWtz3dmfx to /etc/puppetlabs/puppet/ssl/certs/ca.pem on pe-201815-agent.platform9.puppet.net, pe-201815-master.puppetdebug.vlan, pe-201815-compile.platform9.puppet.net
Finished: file upload from /tmp/tmp.CuWtz3dmfx to /etc/puppetlabs/puppet/ssl/certs/ca.pem with 0 failures in 0.66 sec
Finished: plan ca_extend::upload_ca_cert in 17.41 sec
{
"success": {
"pe-201815-agent.platform9.puppet.net": {
"_output": "Uploaded '/tmp/tmp.CuWtz3dmfx' to 'pe-201815-agent.platform9.puppet.net:/etc/puppetlabs/puppet/ssl/certs/ca.pem'"
},
"pe-201815-master.puppetdebug.vlan": {
"_output": "Uploaded '/tmp/tmp.CuWtz3dmfx' to 'pe-201815-master.puppetdebug.vlan:/etc/puppetlabs/puppet/ssl/certs/ca.pem'"
},
"pe-201815-compile.platform9.puppet.net": {
"_output": "Uploaded '/tmp/tmp.CuWtz3dmfx' to 'pe-201815-compile.platform9.puppet.net:/etc/puppetlabs/puppet/ssl/certs/ca.pem'"
},
"ljbkgu9t2x3ohqd.delivery.puppetlabs.net": {
"_output": "Uploaded '/tmp/tmp.CuWtz3dmfx' to 'ljbkgu9t2x3ohqd.delivery.puppetlabs.net:C:\\ProgramData\\PuppetLabs\\puppet\\etc\\ssl\\certs\\ca.pem'"
}
}
}
Tasks
ca_extend::check_ca_expiry
Arguments
- cert - Optional location of certificate on disk to check. Defaults to /etc/puppetlabs/puppet/ssl/certs/ca.pem.
- date - Optional YYYY-MM-DD format date against which to check for expiration. Defaults to 3 months in the future.
This task accepts any valid TargetSpec(s) specified by the --nodes
option. Can be run on any *nix agent node or the master.
Steps
- Uses
openssl
and Unixdate
to determine if the certificate will expire.
Output
A JSON object with the status and expiration date, e.g.
{
"status": "valid",
"expiry date": "Feb 16 01:00:09 2034 GMT"
}
ca_extend::check_agent_expiry
Arguments
- date - Optional YYYY-MM-DD format date against which to check for expiration
This task accepts any valid TargetSpec(s) specified by the --nodes
option. Should be run on the master.
Steps
- Uses
openssl
and Unixdate
to determine if the signed agent certificates under/etc/puppetlabs/puppet/ssl/ca/signed/
will expire.
Output
A JSON object with keys for valid and expiring certificates, e.g.
{
"valid": [
"/etc/puppetlabs/puppet/ssl/ca/signed/c4lscpmafhaxjr8.delivery.puppetlabs.net.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/cd4pe-containers.platform9.puppet.net.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/iwj6668y4s3vq40.delivery.puppetlabs.net.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/koo1nzsozj2xeqh.delivery.puppetlabs.net.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/mafy3pgo98v2vne.delivery.puppetlabs.net.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/pe-201901-agent.platform9.puppet.net.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/pe-201901-compile.puppetdebug.vlan.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/pe-201901-master.puppetdebug.vlan.pem",
"/etc/puppetlabs/puppet/ssl/ca/signed/qgocotu07r3rdpa.delivery.puppetlabs.net.pem"
],
"expiring": [
]
}
What are tasks?
Modules can contain tasks that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Tasks in this module release
extend_ca_cert
Get the platform release of a node
What are plans?
Modules can contain plans that take action outside of a desired state managed by Puppet. It’s perfect for troubleshooting or deploying one-off changes, distributing scripts to run across your infrastructure, or automating changes that need to happen in a particular order as part of an application deployment.
Dependencies
- puppetlabs/stdlib (>= 3.2.0 < 6.0.0)