tls-certificates

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, basename, common_name and subject_alt_names)

Certificates are placed in the base_directory, by default /etc/ssl/ansible. Private keys are placed in the private/ subdirectory, and signed certificates in the certs/ subdirectory. All paths can be overridden with the *_path variables.

Tasks

Orchestration happens in the tasks/main.yml file.

  • base_directory creation is handled by tasks/create_directories.yml.
  • Generation of the private key and signing request is done in tasks/create_keypair.yml.

According to the self_sign variable, one of two processes can happen:

  • When self_sign is true, a self-signed certificate is generated by tasks/self_sign.yml.
  • When self_sign is false, tasks/letsencrypt.yml takes care of sending the CSR to Let’s Encrypt for signature.

Let’s Encrypt

The tasks/letsencrypt.yml tasks handle certificate signatures by Let’s Encrypt. Responding to the ACME challenge is done through the tasks/letsencrypt_challenge.yml tasks.

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).

Available variables

Certificate settings

  • 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 /etc/ssl/ansible.
  • 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 base_directory.

  • csr_path: Path to the certificate request file. Defaults to certs/basename.csr.
  • certificate_path: Path to the signed certificate. Defaults to certs/basename.pem.
  • fullchain_path: Path to the signed certificate with full certificate chain. Defaults to certs/basename.fullchain.pem.
  • privatekey_path: Path to the private key. Defaults to private/basename.key.
  • nginx_snippet_path: Path to the nginx configuration snippet for well known directory. Defaults to /etc/nginx/snippets/letsencrypt-{{ basename }}.conf.

Let’s Encrypt settings

Account 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_agreement: URL to a terms of service document you agree to when using the ACME service. Default value is current as of November 23 2017.
  • letsencrypt_acme_directory: URL to the ACME directory used for requests. Test value: https://staging.api.letsencrypt.org/directory, production value: https://acme-v01.api.letsencrypt.org/directory.
  • letsencrypt_chain_path: Path to the chain of intermediate certificates for Let’s Encrypt validation.

Challenge settings

  • letsencrypt_challenge_mode: Challenge mode for Let’s Encrypt. Supported values: http-01.
  • letsencrypt_well_known_dir: Directory where to store the /.well-known/ data for the http-01 challenge.
  • letsencrypt_do_nginx_vhost: Whether to provide a default nginx virtual host for the http-01 challenge. Defaults to false: web-server configuration must make the .well-known directory available.

Internal settings:

  • skip_unit_test: Used internally by the test suite to disable actions that can’t be performed in the gitlab-ci test runner.