- Overview
- Module Description - What the module does and why it is useful
- Setup - The basics of getting started with acme_certificates
- Usage - Configuration options and additional functionality
- Reference - An under-the-hood peek at what the module is doing and how
- Limitations - OS compatibility, etc.
- Development - Guide for contributing to the module
Manages certificates on disk using an ACME Certificate Authority such as Let's Encrypt
Requests certificates to be signed by an ACME Certificate Authority such as Let's Encrypt, and automatically handles domain authorization.
Currently supports DNS domain authorization by creating DNS records in AWS Route 53.
- (Optionally) Installs the required
acme-client
andaws-sdk
gems - Registers an account with an ACME CA using the puppet agent's private key as the registration key
- Creates temporary records in AWS Route 53 to handle ACME domain authorization
- Generates CSRs based on new or existing private keys, and gets them signed by the ACME CA
- Writes the certificates and private keys to disk at a user-specified location
- To use the builtin DNS domain authorization with Route 53:
- You must have a Route 53 hosted zone for the domain (or subdomain) you wish to generate certificates for. The domain must be set up to
delegate DNS requests to your Route 53 hosted zone (i.e.
nslookup <record>.<your domain or subdomain>
must resolve from Route 53) - You must have AWS credentials with permissions to call
route53:ChangeResourceRecordSets
androute53:GetChange
for your hosted zone
- You must have a Route 53 hosted zone for the domain (or subdomain) you wish to generate certificates for. The domain must be set up to
delegate DNS requests to your Route 53 hosted zone (i.e.
- The
acme-client
andaws-sdk
gems must be installed on your puppet agents, either manually or by specifying theacme_certificates::manage_gems
parameter
# Set the defaults for all certificates
class { 'acme_certificates':
# Automatically install the required ruby gems
manage_gems => true,
# Let's Encrypt account contact details
contact => 'mailto:[email protected]',
# Uncomment this to use the real Let's Encrypt server - this module defaults to the staging server
# directory => 'https://acme-v02.api.letsencrypt.org/directory',
# Agree to the terms of service for Let's Encrypt -- read the terms before setting this parameter
agree_to_terms_url => 'https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf',
# The ID of an existing Route 53 zone to create DNS records under
route53_zone_id => 'ABC123',
# If AWS credentials are not available via the standard environment variables, credentials files, or
# EC2 instance profiles, they may be manually specified here or on acme_certificates::cert
# aws_access_key_id => 'MYACCESSKEYID',
# aws_secret_access_key => 'SUPERSECRETVALUE',
}
# Get a signed certificate from the ACME CA
acme_certificates::cert { '/etc/ssl/certs/www.example.com.pem':
private_key_path => '/etc/ssl/private/www.example.com.key',
common_name => 'example.com',
alternate_names => ['www.example.com', 'web.example.com'],
generate_private_key => true,
owner => nginx,
group => adm,
}
Setup default values with the main acme_certificates
class, then request certificates with the acme_certificates::cert
type.
acme_certificates
: Configures the default settings for certificates managed by this puppet module.acme_certificates::gems
: Installs required gems for this module.
acme_certificates::cert
: Manage a certificate on disk signed by an ACME server.
Configures the default settings for certificates managed by this puppet module and optionally installs required gems.
Whether to install the required ruby gems to make the custom providers of this puppet module work. Defaults to false
.
If this is specified, the acme_certificates::gems
class is automatically included.
The contact information used to register with the ACME server.
e.g. 'mailto:[email protected]' or 'tel:+12025551212'
The ACME server's directory URL. Defaults to the Let's Encrypt staging environment.
The URL of the terms of service of the ACME server to agree to. By setting this, you agree to the terms of service of the ACME server.
This must be set if the ACME server requires ACME clients to agree to terms of service.
The time, in seconds, to wait for the ACME server to process pending domain authorizations before timing out. Defaults to 5 minutes.
If an existing certificate would expire within this many days, it will be renewed. Defaults to 30 days.
The path to the private key file to use for ACME registration (not the certificate private key). If specified, this file must already exist.
Defaults to registering with the ACME server using the puppet agent's private key.
The AWS Access Key ID to use to modify Route 53 records to authorize domains.
Defaults to no credentials (e.g. will use the AWS SDK default methods for finding credentials, or fail trying to look them up)
The AWS Secret Access Key to use to modify Route 53 records to authorize domains.
Defaults to no credentials (e.g. will use the AWS SDK default methods for finding credentials, or fail trying to look them up)
The Route 53 zone ID to create DNS records in to authorize domains.
Installs required gems for this module. This is automatically included by the acme_certificates class if manage_gems
is true.
The package provider for intalling gems. Defaults to 'gem'
, the system gem provider.
Manage a certificate on disk signed by an ACME server.
Automatically includes the acme_certificates
class if it has not already been declared. Many parameters in this type can have their
default value specified in the acme_certificates
class.
The common name of the certificate.
The path to the private key file. If generate_private_key
is not true, this file must already exist.
The file to place the signed certificate in. Defaults to the title
The file to place the certificate chain in. Defaults to not writing the certificate chain to disk
Whether to write out the certificate and chain to the single file identified by certificate_path. Defaults to not combining certificate and chain
Subject alternate names of the certificate. Defaults to no alternate names
Whether to automatically generate a private key for this certificate. Defaults to not generating the private key
The file owner for the generated certificate, certificate chain, and private key files. Defaults to root
The file group for the generated certificate, certificate chain, and private key files. Defaults to root
The file mode for the generated certificate file. Defaults to '0444'
The file mode for the generated certificate chain file, if $certificate_chain_path
is specified. Defaults to '0444'
The file mode for the generated private key file, if $generate_private_key
is true
. Defaults to '0400'
The contact information used to register with the ACME server.
e.g. 'mailto:[email protected]' or 'tel:+12025551212'
Defaults to the value from the acme_certificates
class
The ACME server's directory URL.
Defaults to the value from the acme_certificates
class
The URL of the terms of service of the ACME server to agree to. By setting this, you agree to the terms of service of the ACME server.
This must be set (in the certificate resource or in the acme_certificates
class) if the ACME server requires ACME clients to agree to
terms of service.
Defaults to the value from the acme_certificates
class
The time, in seconds, to wait for the ACME server to process pending domain authorizations before timing out.
Defaults to the value from the acme_certificates
class
If an existing certificate would expire within this many days, it will be renewed.
Defaults to the value from the acme_certificates
class
The path to the private key file to use for ACME registration (not the certificate private key). If specified, this file must already exist.
Defaults to the value from the acme_certificates
class
The AWS Access Key ID to use to modify Route 53 records to authorize the domain for this certificate.
Defaults to the value from the acme_certificates
class
The AWS Secret Access Key to use to modify Route 53 records to authorize the domain for this certificate.
Defaults to the value from the acme_certificates
class
The Route 53 zone ID to create DNS records in to authorize the domain for this certificate.
Defaults to the value from the acme_certificates
class
Currently only supports handling the DNS-01 challenge by creating records in Route 53.
Tested on Ubuntu.
Fork and PR, but please provide tests and update the relevant documentation.