opendev/system-config
Code Issues Proposed changes
0c0b8e3087
system-config/playbooks/roles/letsencrypt-request-certs/README.rst

56 lines
2.1 KiB
ReStructuredText
Raw Normal View History

letsencrypt support This change contains the roles and testing for deploying certificates on hosts using letsencrypt with domain authentication. From a top level, the process is implemented in the roles as follows: 1) letsencrypt-acme-sh-install This role installs the acme.sh tool on hosts in the letsencrypt group, along with a small custom driver script to help parse output that is used by later roles. 2) letsencrypt-request-certs This role runs on each host, and reads a host variable describing the certificates required. It uses the acme.sh tool (via the driver) to request the certificates from letsencrypt. It populates a global Ansible variable with the authentication TXT records required. If the certificate exists on the host and is not within the renewal period, it should do nothing. 3) letsencrypt-install-txt-record This role runs on the adns server. It installs the TXT records generated in step 2 to the acme.opendev.org domain and then refreshes the server. Hosts wanting certificates will have pre-provisioned CNAME records for _acme-challenge.host.opendev.org pointing to acme.opendev.org. 4) letsencrypt-create-certs This role runs on each host, reading the same variable as in step 2. However this time the acme.sh tool is run to authenticate and create the certificates, which should now work correctly via the TXT records from step 3. After this, the host will have the full certificate material. Testing is added via testinfra. For testing purposes requests are made to the staging letsencrypt servers and a self-signed certificate is provisioned in step 4 (as the authentication is not available during CI). We test that the DNS TXT records are created locally on the CI adns server, however. Related-Spec: https://review.openstack.org/587283 Change-Id: I1f66da614751a29cc565b37cdc9ff34d70fdfd3f
2019-02-14 08:10:51 +11:00
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**
letsencrypt: split staging and self-signed generation We currently only have letsencrypt_test_only as a single flag that sets tests to use the letsencrypt staging environment and also generates a self-signed certificate. However, for initial testing we actually want to fully generate certificates on hosts, but using the staging environment (i.e. *not* generate self-signed certs). Thus we need to split this option into two, so the gate tests still use staging+self-signed, but in-progress production hosts can just using the staging flag. These variables are split, and graphite01.opendev.org is made to create staging certificates. Also remove some debugging that is no longer necessary. Change-Id: I08959ba904f821c9408d8f363542502cd76a30a4
2019-04-10 07:31:26 +10:00
.. zuul:rolevar:: letsencrypt_use_staging
letsencrypt support This change contains the roles and testing for deploying certificates on hosts using letsencrypt with domain authentication. From a top level, the process is implemented in the roles as follows: 1) letsencrypt-acme-sh-install This role installs the acme.sh tool on hosts in the letsencrypt group, along with a small custom driver script to help parse output that is used by later roles. 2) letsencrypt-request-certs This role runs on each host, and reads a host variable describing the certificates required. It uses the acme.sh tool (via the driver) to request the certificates from letsencrypt. It populates a global Ansible variable with the authentication TXT records required. If the certificate exists on the host and is not within the renewal period, it should do nothing. 3) letsencrypt-install-txt-record This role runs on the adns server. It installs the TXT records generated in step 2 to the acme.opendev.org domain and then refreshes the server. Hosts wanting certificates will have pre-provisioned CNAME records for _acme-challenge.host.opendev.org pointing to acme.opendev.org. 4) letsencrypt-create-certs This role runs on each host, reading the same variable as in step 2. However this time the acme.sh tool is run to authenticate and create the certificates, which should now work correctly via the TXT records from step 3. After this, the host will have the full certificate material. Testing is added via testinfra. For testing purposes requests are made to the staging letsencrypt servers and a self-signed certificate is provisioned in step 4 (as the authentication is not available during CI). We test that the DNS TXT records are created locally on the CI adns server, however. Related-Spec: https://review.openstack.org/587283 Change-Id: I1f66da614751a29cc565b37cdc9ff34d70fdfd3f
2019-02-14 08:10:51 +11:00
letsencrypt: split staging and self-signed generation We currently only have letsencrypt_test_only as a single flag that sets tests to use the letsencrypt staging environment and also generates a self-signed certificate. However, for initial testing we actually want to fully generate certificates on hosts, but using the staging environment (i.e. *not* generate self-signed certs). Thus we need to split this option into two, so the gate tests still use staging+self-signed, but in-progress production hosts can just using the staging flag. These variables are split, and graphite01.opendev.org is made to create staging certificates. Also remove some debugging that is no longer necessary. Change-Id: I08959ba904f821c9408d8f363542502cd76a30a4
2019-04-10 07:31:26 +10:00
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.
letsencrypt support This change contains the roles and testing for deploying certificates on hosts using letsencrypt with domain authentication. From a top level, the process is implemented in the roles as follows: 1) letsencrypt-acme-sh-install This role installs the acme.sh tool on hosts in the letsencrypt group, along with a small custom driver script to help parse output that is used by later roles. 2) letsencrypt-request-certs This role runs on each host, and reads a host variable describing the certificates required. It uses the acme.sh tool (via the driver) to request the certificates from letsencrypt. It populates a global Ansible variable with the authentication TXT records required. If the certificate exists on the host and is not within the renewal period, it should do nothing. 3) letsencrypt-install-txt-record This role runs on the adns server. It installs the TXT records generated in step 2 to the acme.opendev.org domain and then refreshes the server. Hosts wanting certificates will have pre-provisioned CNAME records for _acme-challenge.host.opendev.org pointing to acme.opendev.org. 4) letsencrypt-create-certs This role runs on each host, reading the same variable as in step 2. However this time the acme.sh tool is run to authenticate and create the certificates, which should now work correctly via the TXT records from step 3. After this, the host will have the full certificate material. Testing is added via testinfra. For testing purposes requests are made to the staging letsencrypt servers and a self-signed certificate is provisioned in step 4 (as the authentication is not available during CI). We test that the DNS TXT records are created locally on the CI adns server, however. Related-Spec: https://review.openstack.org/587283 Change-Id: I1f66da614751a29cc565b37cdc9ff34d70fdfd3f
2019-02-14 08:10:51 +11:00
.. 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:
main:
- hostname01.opendev.org
- hostname.opendev.org
secondary:
- 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 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.
Copy Permalink