Letsencrypt
A module for configuring certificates from letsencrypt (or other ACME providers), and deploying them.
Table of Contents
Why
Why this module instead of puppet/letsencrypt? Setting up certificates on existing infrastructure with that module isn't a problem. However, bootstraping new servers is a problem, since one usually wants to write a complete server configuration (for nginx (or similar)) at the beginning, but letsencrypt requires a working webserver to authenticate. This module solves that (see [Server Integration](#Server Integration)).
This module also allows multiple domains to be added to a single certificate one by one, instead of requiring them all to be pre-determined.
Usage
Examples
For basic usage, include letsencrypt, and define letsencrypt::cert resources.
include ::letsencrypt
letsencrypt::cert { 'example.com':
include_self => true,
authenticator => 'nginx',
}
Each certificate can have its own authenticator and configuration, allowing multiple different setups to co-exist.
Server Integration
A number of functions are available for easy integration with different web servers (currently only nginx). These procedures expand to a correct ssl configuration if the wanted certificate is available, or to ssl => false (or similar) if it isn't. This allows efficient bootstrapping.
The following example would configure an ngnix server without SSL on its first run, but configure a server with ssl on future runs (since the certificate will be generated by then).
nginx::resource::server { 'example.com':
* => letsencrypt::conf::nginx('example.com'),
}
It's recommended to reload to add a post-hook to letsencrypt::cert which reloads your server configuration. This won't allow SSL to get configured on the first run, but is usually needed when a certificate gets renewed.
letsencrypt::cert { 'example.com':
# [...]
config => {
'post-hook' => 'nginx -s reload',
},
}
Extra Domains
Additional domain names can later be added to a given certificate.
letsencrypt::domain { 'subdomain.example.com':
cert_name => 'example.com',
}
This is for example useful if you have a profile which sets up a certificate with the hosts fully qualified domain name as its name, and each other profile registering domains to that certificate.
Authenticators
Each certificate needs to be authenticated, this has no relation to where the certificate is used, even though the usual configuration uses the certificates on the same web server which was used for authentication. Currently only nginx is supported.
Facter Facts
letsencrypt_bycertname
A hash from each certificates locally chosen name, to its directory in the letsencrypt live directory. The actual directory name [may have extra numbers on its end]. This fact strips them to allow one to check if a given certificate is loaded.
letsencrypt_directory
A hash from each domain name which has a certificate, to its directory in letsencrypts live directory. "${letsencrypt_directory['example.com']}/fullchain.pem" or similar is probably what you want.
Restrictions
Currently only nginx is supported. In the future, at least the following should be supported:
- Apache2 authenticator
- Apache2 configuration function
- Route53 authenticator
The letsencrypt directories aren't cleaned up if certificates is no longer managed.
The module doesn't notice if the authenticator service changes, meaning that old certificates will need to be removed by hand.
Other Stuff
When debugging locally, configuration files will be placed in /etc/letsencrypt. Letsencrypt stores its debug logs to /var/log/letsencrypt/letsencrypt.log.