Tools for ACME

This collection provides some useful roles for retrieving ACME certificates.

Tested with Ansible

Tested with the current ansible-core 2.11, ansible-core 2.12, ansible-core 2.13, ansible-core 2.14, ansible-core 2.15, ansible-core 2.16 releases and the current development version of ansible-core. Ansible-core versions before 2.11.0 are not supported.

External requirements

Requires the Python cryptography library installed on the controller, available to the Python version used to execute the playbook. If cryptography is not installed, a recent enough version of PyOpenSSL is currently supported as a fallback by the community.crypto.openssl_privatekey and community.crypto.openssl_csr modules.

The openssl binary must also be available in the executable path on the controller. It is needed by the acme_certificate module in case cryptography is not installed, and it is used for certificate chain validation by the felixfontein.acme.acme_certificate role.

If DNS challenges are used, there can be other requirements depending on the DNS provider. For example, for Amazon's Route 53, the Ansible amazon.aws.route53 module requires the Python boto3 package. If DNS challenges with NS1 are used, the NS1 modules must be installed. See below for more information.

Included content

• Role felixfontein.acme.acme_certificate.
• Role felixfontein.acme.revoke_old_certificates.
• Role felixfontein.acme.account_key_rollover.

(You can see the documentation corresponding to the latest commits on GitHub Pages.)

Using this collection

Before using the felixfontein.acme collection, you need to install the collection with the ansible-galaxy CLI:

ansible-galaxy collection install felixfontein.acme

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:

collections:
- name: felixfontein.acme

See Ansible Using collections for more details.

For using this collection, you always also need an ACME account. See the documentation on ACME accounts on how to create one.

Release notes

See the changelog.

Releasing, Deprecation and Versioning

We release new versions once there are new features or bugfixes. Deprecations can happen, and we try to announce them a long time in advance. We currently do not plan breaking changes, so there will be no new major release anytime soon.

Contributing

Please create issues to report problems or request new features, and create PRs to fix bugs or add new features. If you want to do a refactoring PR, please create an issue first to discuss the refactoring.

Please follow the general Ansible contributor guidelines; see the Ansible Community Guide.

More information

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community code of conduct

Licensing

GNU General Public License v3.0 or later.

See COPYING to see the full text.