system-config

History

Ian Wienand 733122f0df Use handlers for letsencrypt cert updates This change proposes calling a handler each time a certificate is created/updated. The handler name is based on the name of the certificate given in the letsencrypt_certs variable, as described in the role documentation. Because Ansible considers calling a handler with no listeners an error this means each letsencrypt user will need to provide a handler. One simple option illustrated here is just to produce a stamp file. This can facilitate cross-playbook and even cross-orchestration-tool communication. For example, puppet or other ansible playbooks can detect this stamp file and schedule their reloads, etc. then remove the stamp file. It is conceivable more complex listeners could be setup via other roles, etc. should the need arise. A test is added to make sure the stamp file is created for the letsencrypt test hosts, which are always generating a new certificate in the gate test. Change-Id: I4e0609c4751643d6e0c8d9eaa38f184e0ce5452e		2019-05-14 08:14:51 +10:00
..
defaults	letsencrypt: split staging and self-signed generation	2019-04-10 08:47:32 +10:00
tasks	letsencrypt: split staging and self-signed generation	2019-04-10 08:47:32 +10:00
README.rst	Use handlers for letsencrypt cert updates	2019-05-14 08:14:51 +10:00

README.rst

Request certificates from letsencrypt

The role requests certificates (or renews expiring certificates, which is fundamentally the same thing) from letsencrypt for a host. This requires the acme.sh tool and driver which should have been installed by the letsencrypt-acme-sh-install role.

This role does not create the certificates. It will request the certificates from letsencrypt and populate the authentication data into the acme_txt_required variable. These values need to be installed and activated on the DNS server by the letsencrypt-install-txt-record role; the letsencrypt-create-certs will then finish the certificate provision process.

Role Variables

If set to True will use the letsencrypt staging environment, rather than make production requests. Useful during initial provisioning of hosts to avoid affecting production quotas.

A host wanting a certificate should define a dictionary variable letsencyrpt_certs. Each key in this dictionary is a separate certificate to create (i.e. a host can create multiple separate certificates). Each key should have a list of hostnames valid for that certificate. The certificate will be named for the first entry.

For example:
letsencrypt_certs:
  hostname-main-cert:
    - hostname01.opendev.org
    - hostname.opendev.org
  hostname-secondary-cert:
    - foo.opendev.org
will ultimately result in two certificates being provisioned on the host in /etc/letsencrypt-certs/hostname01.opendev.org and /etc/letsencrypt-certs/foo.opendev.org.

Note the creation role letsencrypt-create-certs will call a handler letsencrypt updated {{ key }} (for example, letsencrypt updated hostname-main-cert) when that certificate is created or updated. Because Ansible errors if a handler is called with no listeners, you must define a listener for event. letsencrypt-create-certs has handlers/main.yaml where handlers can be defined. Since handlers reside in a global namespace, you should choose an appropriately unique name.

Note that each entry will require a CNAME pointing the ACME challenge domain to the TXT record that will be created in the signing domain. For example above, the following records would need to be pre-created:
_acme-challenge.hostname01.opendev.org.  IN   CNAME  acme.opendev.org.
_acme-challenge.hostname.opendev.org.    IN   CNAME  acme.opendev.org.
_acme-challenge.foo.opendev.org.         IN   CNAME  acme.opendev.org.