W3cubDocs

/Ansible

letsencrypt - Create SSL certificates with Let’s Encrypt

New in version 2.2.

Synopsis

  • Create and renew SSL certificates with Let’s Encrypt. Let’s Encrypt is a free, automated, and open certificate authority (CA), run for the public’s benefit. For details see https://letsencrypt.org. The current implementation supports the http-01, tls-sni-02 and dns-01 challenges.
  • To use this module, it has to be executed at least twice. Either as two different tasks in the same run or during multiple runs.
  • Between these two tasks you have to fulfill the required steps for the chosen challenge by whatever means necessary. For http-01 that means creating the necessary challenge file on the destination webserver. For dns-01 the necessary dns record has to be created. tls-sni-02 requires you to create a SSL certificate with the appropriate subjectAlternativeNames. It is not the responsibility of this module to perform these steps.
  • For details on how to fulfill these challenges, you might have to read through https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-7
  • Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can be used with any service using the ACME protocol.

Requirements (on host that executes module)

  • python >= 2.6
  • openssl

Options

parameter required default choices comments
account_email
 no
The email address associated with this account.
It will be used for certificate expiration warnings.
account_key
 yes
File containing the Let's Encrypt account RSA key.
Can be created with openssl rsa ....
acme_directory
 no https://acme-staging.api.letsencrypt.org/directory
The ACME directory to use. This is the entry point URL to access CA server API.
For safety reasons the default is set to the Let's Encrypt staging server. This will create technically correct, but untrusted certificates.
agreement
 no https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
URI to a terms of service document you agree to when using the ACME service at acme_directory.
challenge
 no http-01
  • http-01
  • dns-01
  • tls-sni-02
The challenge to be performed.
csr
 yes
File containing the CSR for the new certificate.
Can be created with openssl csr ....
The CSR may contain multiple Subject Alternate Names, but each one will lead to an individual challenge that must be fulfilled for the CSR to be signed.
aliases: src
data
 no
The data to validate ongoing challenges.
The value that must be used here will be provided by a previous use of this module.
dest
 yes
The destination file for the certificate.
aliases: cert
remaining_days
 no 10
The number of days the certificate must have left being valid. If cert_days < remaining_days, then it will be renewed. If the certificate is not renewed, module return values will not include challenge_data.

Examples

- letsencrypt:
    account_key: /etc/pki/cert/private/account.key
    csr: /etc/pki/cert/csr/sample.com.csr
    dest: /etc/httpd/ssl/sample.com.crt
  register: sample_com_challenge

# perform the necessary steps to fulfill the challenge
# for example:
#
# - copy:
#     dest: /var/www/html/{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource'] }}
#     content: "{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource_value'] }}"
#     when: sample_com_challenge|changed

- letsencrypt:
    account_key: /etc/pki/cert/private/account.key
    csr: /etc/pki/cert/csr/sample.com.csr
    dest: /etc/httpd/ssl/sample.com.crt
    data: "{{ sample_com_challenge }}"

Return Values

Common return values are documented here Return Values, the following are the fields unique to this module:

name description returned type sample
challenge_data
per domain / challenge type challenge data
 changed complex
contains:
name description returned type sample
resource
the challenge resource that must be created for validation
 changed string .well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA
resource_value
the value the resource has to produce for the validation
 changed string IlirfxKKXA...17Dt3juxGJ-PCt92wr-oA
cert_days
the number of days the certificate remains valid.
 success int
authorizations
ACME authorization data.
 changed complex
contains:
name description returned type sample
authorization
ACME authorization object. See https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.1.2
 success dict

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2017 Michael DeHaan
© 2017 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/letsencrypt_module.html