CCCHH/ansible-infra
CCCHH/ansible-infra
2
2
Fork 1
Code Issues 6 Pull requests 4 Wiki Activity Actions
ansible-infra/roles/certbot/README.md
June 8bf6dfbefb
All checks were successful
/ Ansible Lint (push) Successful in 3m36s
Details
certbot(role): support DNS-01 certs using acme-dns 
Introduce new configuration structure called certbot__certs, which
allows for different challenge types per cert with the first challenge
type supported being dns-01-acme-dns.
2026-03-31 16:48:00 +02:00

2.9 KiB
Raw Blame History

Role certbot

A role for deploying Certbot and setting up certificates using it.

Note: This role doesn't take care of deleting certificates.

Also see the following documentation for a full How-to on how to get certificates using this role in the context of our infra: https://wiki.ccchh.net/infrastructure:zertifikate.

Challenge Types

For the certbot__certs configuration, depending on the challenge type, different preparation needs to be done.

dns-01-acme-dns

For the dns-01-acme-dns challenge type, ensure that:

  1. An acme-dns entry got registered, so you have access to the subdomain, apiUser and apiKey for the configuration. The apiKey should be stored in some kind of secret, which then gets referenced in the relevant certbot__certs configuration.
    For our acme-dns instance, go to https://acmedns.hamburg.ccc.de/, sign-in and register a new entry.
  2. CNAME the _acme-challenge domain of the domain you want to obtain a certificate for (certbot__certs.*.commonName) to the full domain from the registration.
    It should look something like this: _acme-challenge.domainiwantcertfor.tld. CNAME 3ed25037-79f1-4a89-8934-db3e162fe2bc.auth.acmedns.hamburg.ccc.de.

For more info see:

Required Arguments

  • certbot__acme_account_email_address: The E-Mail address to use for the ACME account.

Optional Arguments

  • certbot__certificate_domains: The domains for which to obtain a certificate using the HTTP-01 challenge.
  • certbot__http_01_port: The port number the bot listens on. Should be 80 if directly exposed to the internet.
    Defaults to 31820 (for the public-reverse-proxy setup).
  • certbot__certs: Certificates to create.
    Defaults to the empty list ([ ]).
  • certbot__certs.*.commonName: The common name to issue the certificate for.
  • certbot__certs.*.challengeType: The challenge type to use for getting the certificate. Challenge type-specific configuration must be provided as well. Should be one of:
    • dns-01-acme-dns
  • certbot__certs.*.dns_01_acme_dns: Configuration for the dns-01-acme-dns challenge type.
  • certbot__certs.*.dns_01_acme_dns.serverUrl: The acme-dns server API URL.
    Defaults to https://acmedns.hamburg.ccc.de.
  • certbot__certs.*.dns_01_acme_dns.subdomain: The acme-dns subdomain to use.
  • certbot__certs.*.dns_01_acme_dns.apiUser: The acme-dns API user to use.
  • certbot__certs.*.dns_01_acme_dns.apiKey: The acme-dns API key to use.
  • certbot__new_cert_commands: A list of commands to execute after getting a new certificate. Will be added into a bash script.
    Defaults to the empty list ([ ]).

hosts

The hosts for this role need to be the machines on which you want to make sure Certbot is deployed and given certificates are set up.