ansible.builtin.letsencrypt (v2.4.6.0-1) — module

Install Ansible via pip

Install with pip install ansible==2.4.6.0.post1

Description

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 U(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 I(not) the responsibility of this module to perform these steps.

For details on how to fulfill these challenges, you might have to read through U(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

• python >= 2.6
• openssl

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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 }}"

Inputs

    
csr:
    aliases:
    - src
    description:
    - File containing the CSR for the new certificate.
    - Can be created with C(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.
    required: true

data:
    default: null
    description:
    - The data to validate ongoing challenges.
    - The value that must be used here will be provided by a previous use of this module.
    required: false

dest:
    aliases:
    - cert
    description: The destination file for the certificate.
    required: true

agreement:
    default: https://letsencrypt.org/documents/LE-SA-v1.1.1-August-1-2016.pdf
    description:
    - URI to a terms of service document you agree to when using the ACME service at C(acme_directory).
    required: false

challenge:
    choices:
    - http-01
    - dns-01
    - tls-sni-02
    default: http-01
    description: The challenge to be performed.
    required: false

account_key:
    description:
    - File containing the Let's Encrypt account RSA key.
    - Can be created with C(openssl rsa ...).
    required: true

account_email:
    default: null
    description:
    - The email address associated with this account.
    - It will be used for certificate expiration warnings.
    required: false

acme_directory:
    default: https://acme-staging.api.letsencrypt.org/directory
    description:
    - 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.
    required: false

remaining_days:
    default: 10
    description:
    - The number of days the certificate must have left being valid. If C(cert_days <
      remaining_days), then it will be renewed. If the certificate is not renewed, module
      return values will not include C(challenge_data).
    required: false

Outputs

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