4346570a0b
We set the letsencrypt_self_generate_tokens value to True in testing which means the variable is valid and exists in testing. However, in production this variable isn't set and doesn't ahve a default so we get: The task includes an option with an undefined variable. The error was: 'letsencrypt_self_generate_tokens' is undefined Fix this by setting the default value for this var to False. Also, add it to the README of letsencrypt-request-certs as this is where it is primarily used. Change-Id: I862df6ea3ff7f3a1df2a088b04d230bb618aaa85
85 lines
3.6 KiB
ReStructuredText
85 lines
3.6 KiB
ReStructuredText
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**
|
|
|
|
.. zuul:rolevar:: letsencrypt_self_generate_tokens
|
|
:default: False
|
|
|
|
When set to ``True``, self-generate fake DNS-01 TXT tokens rather
|
|
than acquiring them through the ACME process with letsencrypt.
|
|
This avoids leaving "half-open" challenges during gate testing,
|
|
where we have no way to publish the DNS TXT records letsencrypt
|
|
gives us to complete the certificate issue. This should be
|
|
``True`` if ``letsencrypt_self_sign_only`` is ``True`` (unless you
|
|
wish to specifically test the ``acme.sh`` operation).
|
|
|
|
.. zuul:rolevar:: letsencrypt_use_staging
|
|
|
|
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.
|
|
|
|
.. zuul:rolevar:: letsencrypt_certs
|
|
|
|
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:
|
|
|
|
.. code-block:: yaml
|
|
|
|
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.
|
|
|
|
The hostname in the first entry for each certificate will be
|
|
registered with the ``letsencrypt-config-certcheck`` for periodic
|
|
freshness tests; from the example above, ``hostname01.opendev.org``
|
|
and ``foo.opendev.org`` would be checked. By default this will
|
|
check on port 443; if the certificate is actually active on another
|
|
port you can specify it after a colon;
|
|
e.g. ``foo.opendev.org:5000`` would indicate this host listens with
|
|
this certificate on port 5000.
|