Ansible Role: Certbot (for Let's Encrypt)

This role installs and sets up Certbot, which is used for obtaining Let's Encrypt SSL certificates.

Requirements

To install Certbot from the source, you need Git. You can install Git using the geerlingguy.git role.

Usually, installing from the source (see Source Installation from Git) offers a better experience, especially on older operating systems.

Role Variables

The variable certbot_install_from_source decides if Certbot will be installed from Git or through a package manager. By default, it installs via a package manager, so this variable is set to no.

certbot_auto_renew: true
certbot_auto_renew_user: root
certbot_auto_renew_hour: "3"
certbot_auto_renew_minute: "30"
certbot_auto_renew_options: "--quiet --no-self-upgrade"

By default, this role sets up a cron job to run as the specified user at the given time every day. It runs the command certbot renew daily at 03:30. It's best to set a custom user and time to renew during off-peak hours, using a non-root account.

Automatic Certificate Generation

Currently, the role supports one method for generating new certificates: standalone. More methods (like using nginx or apache) may be added later.

For an example: Check the test playbook in molecule/default/playbook-standalone-nginx-aws.yml.

certbot_create_if_missing: false
certbot_create_method: certonly

To allow this role to generate certificates, set certbot_create_if_missing to yes or True. Choose the certificate generation method with the certbot_create_method variable, currently allowing certonly.

certbot_admin_email: email@example.com

This is the email address to agree to Let's Encrypt's terms and receive notifications about your certificates. Make this your or your organization's regularly monitored email.

certbot_certs: []
  # - email: [email protected]
  #   domains:
  #     - example1.com
  #     - example2.com
  # - domains:
  #     - example3.com

This is a list of domains (and other data) for which certificates will be created. You can add an email key to override the certbot_admin_email.

certbot_create_command: "{{ certbot_script }} certonly --standalone --noninteractive --agree-tos --email {{ cert_item.email | default(certbot_admin_email) }} -d {{ cert_item.domains | join(',') }}"

The certbot_create_command defines how to generate the certificate.

Source Installation from Git

You can install Certbot from its Git repository, which can be useful if your operating system doesn't have a Certbot package (like CentOS < 7, Ubuntu < 16.10, and Debian < 8).

certbot_install_from_source: false
certbot_repo: https://github.com/certbot/certbot.git
certbot_version: master
certbot_keep_updated: true

Set certbot_install_from_source to yes if you want to install from Git. This will clone the configured certbot_repo, respecting the certbot_version. If you set certbot_keep_updated to yes, the repository will update every time this role runs.

certbot_dir: /opt/certbot

This is the directory where Certbot will be cloned.

Wildcard Certificates

Let's Encrypt supports wildcard certificates, though the process for using them is more complex. See this pull request comment for an example. You can also refer to Michael Porter's guide on Creating A Let’s Encrypt Wildcard Cert With Ansible using Cloudflare.

Dependencies

None.

Example Playbook

- hosts: servers

  vars:
    certbot_auto_renew_user: your_username_here
    certbot_auto_renew_minute: "20"
    certbot_auto_renew_hour: "5"

  roles:
    - thiagoalmeidasa.certbot_route53

More examples can be found in the tests/ directory.

Manually creating certificates with certbot

Note: This role can automatically generate certificates; see the previous section on "Automatic Certificate Generation."

You can manually create certificates using the certbot (or certbot-auto) command. Use letsencrypt on Ubuntu 16.04, or /opt/certbot/certbot-auto if installing from Git. Here are some example commands for configuring certificates with Certbot:

# Automatically add certs for all Apache virtual hosts (use with caution).
certbot --apache

# Generate certs without changing Apache configuration (safer).
certbot --apache certonly

If you want to fully automate adding a new certificate without using the role's built-in functions, you can do so with command line options:

1. Stop any services using ports 80 and 443 (like Apache, Nginx, Varnish).
2. Register: certbot register --agree-tos --email [[email protected]] - Note: You won't have to do this again for future certificates on the same server.
3. Generate a certificate for a domain that points to this server: certbot certonly --noninteractive --standalone -d example.com -d www.example.com
4. Restart any stopped services on ports 80 and 443.
5. Update your web server's configuration to use the new certificate (fullchain.pem) and private key (privkey.pem) generated by Certbot.
6. Reload or restart your web server to apply the new HTTPS configuration.

Certbot certificate auto-renewal

By default, this role sets up a cron job that renews all installed certificates once a day at your chosen time.

You can test the auto-renewal (without actually renewing the cert) with:

/opt/certbot/certbot-auto renew --dry-run

For more options, see the full documentation on the Certbot website.

License

MIT / BSD