Create and manage TLS certificates, either with Let’s Encrypt or using self-signed ones.
This role is expected to be called using the
include_role module, setting
variables specific to the certificate instance wanted (notably,
Certificates are placed in the
base_directory, by default
Private keys are placed in the
private/ subdirectory, and signed certificates
certs/ subdirectory. All paths can be overridden with the
Orchestration happens in the
base_directorycreation is handled by
- Generation of the private key and signing request is done in
According to the
self_sign variable, one of two processes can happen:
self_signis true, a self-signed certificate is generated by
tasks/letsencrypt.ymltakes care of sending the CSR to Let’s Encrypt for signature.
tasks/letsencrypt.yml tasks handle certificate signatures by Let’s
Encrypt. Responding to the ACME challenge is done through the
We only support the
http-01 challenge, and only through nginx.
tasks/letsencrypt_nginx_pre.yml sets up a configuration snippet to publish the
/.well-known directory, as well as a temporary virtual host if
letsencrypt_do_nginx_vhost is true (helpful for bootstraping the
configuration on a clean machine).
basename: Base name for the TLS certs installation path.
common_name: Main domain name the certificate will be valid for.
subject_alt_names: Alternative names the certificate will be valid for. The common name is automatically added to the list of SANs.
base_directory: Base installation directory for the TLS certificates. Defaults to
self_sign: If true, self-sign the certificate; if false, request signature from Let’s Encrypt.
Path setting overrides¶
All default paths are relative to
csr_path: Path to the certificate request file. Defaults to
certificate_path: Path to the signed certificate. Defaults to
fullchain_path: Path to the signed certificate with full certificate chain. Defaults to
privatekey_path: Path to the private key. Defaults to
Let’s Encrypt settings¶
letsencrypt_account_key: Path to the Let’s Encrypt account private key.
letsencrypt_account_email: Email used for the Let’s Encrypt account.
letsencrypt_acme_directory: URL to the ACME directory used for requests. Test value:
https://acme-staging-v02.api.letsencrypt.org/directory, production value:
letsencrypt_chain_path: Path to the chain of intermediate certificates for Let’s Encrypt validation.
letsencrypt_challenge_mode: Challenge mode for Let’s Encrypt. Supported values:
letsencrypt_well_known_dir: Directory where to store the
/.well-known/data for the
skip_unit_test: Used internally by the test suite to disable actions that can’t be performed in the gitlab-ci test runner.