nickjj.acme_sh

What is ansible-acme-sh?

It is an Ansible role that helps you:

• Install acme.sh to create, renew, or delete SSL certificates from Let's Encrypt.
• Get certificates for single, multiple, or wildcard domains.
• Configure either multiple domains with one certificate or use separate certificates for each domain.
• Use DNS challenges automatically through acme.sh's DNS API feature.
• Run custom commands with acme.sh if the default settings don’t meet your needs.

Why use this role?

This role utilizes acme.sh, a standalone Bash script that simplifies the process of issuing and automatically renewing SSL certificates.

The aim of this role is to be very customizable while also providing sensible defaults, so you can start quickly by just listing your domain names, setting your DNS provider, and supplying your API key.

It is designed to be repeatable for every task!

Why use DNS challenges?

Using DNS challenges allows you to set up your certificates before your web server or proxy is ready. It also means your web server doesn’t have to understand how the ACME challenge works. You just need to point to the final certificates this role generates.

If your web server runs in Docker, it might not be available until after Ansible sets up your server. For instance, commonly, apps are deployed using git, which happens after the server is provisioned.

Also, DNS challenges are necessary for issuing wildcard certificates with Let's Encrypt. Focusing on a single solution that works for all certificate types is beneficial.

I may not support other methods like standalone, webroot, nginx, or Apache, but nothing’s final yet.

Supported platforms

• Ubuntu 16.04 LTS (Xenial)
• Ubuntu 18.04 LTS (Bionic)
• Debian 8 (Jessie)
• Debian 9 (Stretch)

Role variables

Here are some key variables you can configure:

# User that acme.sh will run as (must exist already).
acme_sh_become_user: "root"

# Package dependencies (for Debian/Ubuntu).
acme_sh_dependencies: ["cron", "git", "wget"]

# The source repo for acme.sh.
acme_sh_git_url: "https://github.com/acmesh-official/acme.sh"

# Version to clone (can be branch, tag, or commit).
acme_sh_git_version: "master"

# Update the repo on every run (False means stick with the old version).
acme_sh_git_update: False 

# Location where the repo will be cloned.
acme_sh_git_clone_dest: "/usr/local/src/acme.sh"

# Enable automatic updates for acme.sh.
acme_sh_upgrade: False 

# Enable this to uninstall acme.sh.
acme_sh_uninstall: False 

# Optional email for Let's Encrypt account notifications.
acme_sh_account_email: ""

# Renewal attempt interval (default is 30 days).
acme_sh_renew_time_in_days: 30 

# Where to copy the certificates.
acme_sh_copy_certs_to_path: "/etc/ssl/ansible"

# Show valid SSL certificates and expiration dates at the end.
acme_sh_list_domains: True 

# Use Let's Encrypt staging servers for testing.
acme_sh_default_staging: True 

# Force a new certificate issue even if domain list hasn't changed.
acme_sh_default_force_issue: False 

# Force renewal of a certificate, regardless of changes.
acme_sh_default_force_renew: False 

# Enable more detailed logging for testing.
acme_sh_default_debug: False 

# Default DNS provider to use (include 'dns_' prefix).
acme_sh_default_dns_provider: "dns_dgon" 

# API keys for your DNS provider (add as key/value pairs).
acme_sh_default_dns_provider_api_keys: {}

# Delay in seconds after setting the DNS TXT record.
acme_sh_default_dns_sleep: 120 

# Option to add extra command-line flags when issuing, renewing, or installing certificates.
acme_sh_default_extra_flags_issue: ""
acme_sh_default_extra_flags_renew: ""
acme_sh_default_extra_flags_install_cert: ""

# Command to run after installing certificates (like reloading nginx).
acme_sh_default_install_cert_reloadcmd: "sudo systemctl reload nginx"

# Hooks to run commands at different points during certificate issuance/renewal.
acme_sh_default_issue_pre_hook: ""
acme_sh_default_issue_post_hook: ""
acme_sh_default_issue_renew_hook: ""

# Remove certificates instead of renewing them.
acme_sh_default_remove: False 

# List of domains and configuration options for each domain.
acme_sh_domains:
  # Example domains and settings can go here.

Example usage

Suppose you have a group called app and a site.yml file. Edit it like this:

---

- name: Configure app server(s)
  hosts: "app"
  become: True

  roles:
    - { role: "nickjj.acme_sh", tags: ["acme_sh"] }

Here are a few examples you can use by editing group_vars/app.yml:

---

acme_sh_account_email: "[email protected]"

acme_sh_default_dns_provider: "dns_cf"
acme_sh_default_dns_provider_api_keys:
  "CF_Key": "THE_API_SECRET_TOKEN_FROM_THE_CLOUDFLARE_DASHBOARD"
  "CF_Email": "[email protected]"

acme_sh_default_install_cert_reloadcmd: "docker exec nginx nginx -s reload"

acme_sh_domains:
  - domains: ["example.com", "www.example.com", "admin.example.com"]

If you need an Ansible role for user creation, check out my user role.

To run it, execute: ansible-playbook -i inventory/hosts site.yml -t acme_sh.

Installation

To install, use:

$ ansible-galaxy install nickjj.acme_sh

Ansible Galaxy

Find it on the official Ansible Galaxy to rate it.

License

MIT