danvaida.letsencrypt

Ansible Let's Encrypt Role

This is a tool that helps you get TLS certificates using Let's Encrypt's ACME service. After you get the certificates, you'll need to set them up on your web server.

Requirements

openssl
Python version 2.7.9 or higher

Role Variables

letsencrypt_certs_dir: The directory where all certificate signing requests (CSRs), keys, and certificates will be stored.
letsencrypt_account_key_name: The name of the RSA key for the Let's Encrypt account.
letsencrypt_account_key_size: The size of the RSA key for the Let's Encrypt account.
letsencrypt_certs_to_generate: A list of certificates you want to create.
- account_email: Your email for notifications about certificate expiration.
- account_key: The location of the RSA key file.
- acme_directory: The ACME API endpoint (default is Let's Encrypt's Staging).
- agreement: The link to the Terms of Service you accept.
- challenge: The type of challenge you will use.
- csr: The path to the CSR file.
- dest: Where to save the resulting certificate file.
- remaining_days: The number of days the certificate will remain valid.

Dependencies

None specified.

Example Playbook

This playbook requests a certificate from Let's Encrypt, but it should work with any ACME server.

Create a CSR, key, and request the certificate.
Complete the challenge (this example uses a DNS record in Route53).
Validate the challenge and get the certificate.

- name: ACME Step 1
  hosts: localhost
  connection: local
  roles:
    - role: letsencrypt
      letsencrypt_certs_dir: './files/production/certs'
      letsencrypt_account_key_name: 'letsencrypt_account'
      letsencrypt_account_key_size: 2048
      letsencrypt_certs_to_generate:
        - domain: 'your-domain.com'
          key_size: 2048
          account_email: '[email protected]'
          account_key: "{{ letsencrypt_certs_dir }}/{{ letsencrypt_account_key_name }}.key"
          challenge: 'dns-01'
          agreement: 'https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf'
          csr: "{{ letsencrypt_certs_dir }}/your-domain.com/your.csr"
          dest: "{{ letsencrypt_certs_dir }}/your-domain.com/domain.crt"
          acme_directory: 'https://acme-v01.api.letsencrypt.org/directory'
      tags: letsencrypt

  tasks:
    - name: Prepare Route53 records
      set_fact:
        route53_records_to_add: "{{
          route53_records_to_add | default([]) +
          [{'zone': item.1.domain,
          'record': item.0.challenge_data[item.1.domain]['dns-01']['resource'] + '.' + item.1.domain + '.',
          'ttl': 300,
          'type': 'TXT',
          'value': '\"' + item.0.challenge_data[item.1.domain]['dns-01']['resource_value'] + '\"' }]
          }}"
      with_together:
        - "{{ letsencrypt_acme_step_one }}"
        - "{{ letsencrypt_certs_to_obtain | default([]) }}"
      when: item.1.domain == item.0.item.domain
      tags: route53

- name: Solve ACME challenge (DNS record in Route53)
  hosts: localhost
  connection: local
  roles:
    - role: route53
      tags: route53

- name: ACME Step 2
  hosts: localhost
  connection: local
  pre_tasks:
    - name: Wait for DNS changes
      pause: minutes=1

  roles:
    - role: letsencrypt
      letsencrypt_acme_step: two
      tags: letsencrypt

Completing other types of challenges will follow a similar process.

Testing

Tests focus on the DNS challenge using AWS Route53.

To run tests in the provided Docker environment, use these commands:

$ cd /path/to/ansible-roles/letsencrypt
$ ansible-galaxy install --force --role-file=./tests/requirements.yml --roles-path=./tests/dependencies
$ docker build --no-cache --pull --tag ansible-roles-test tests/support
$ docker run --rm --interactive --tty --volume $PWD:/etc/ansible/roles/letsencrypt --volume $PWD/tests/dependencies:/etc/ansible/roles/letsencrypt/tests/roles:ro --env AWS_ACCESS_KEY=$AWS_ACCESS_KEY --env AWS_SECRET_KEY=$AWS_SECRET_KEY --workdir /etc/ansible/roles/letsencrypt/tests ansible-roles-test

To-do

Add support for more challenge types
Support other DNS services APIs (such as Cloud DNS)
Integrate with web server roles (like NGINX, Apache)
Add support for renewal of certificates
Ensure compatibility with multiple Ansible versions and distributions
Update the Ansible version in the test Docker image to remove the need for agreement on the DNS challenge.