From 32e700f0767f8893fe2a0f5fd0b65fdd4b96a7b6 Mon Sep 17 00:00:00 2001 From: plui29989 Date: Tue, 28 Feb 2023 21:07:16 +0100 Subject: [PATCH 1/3] Add doc for self-signed certificates --- docs/configuring-playbook-ssl-certificates.md | 43 ++++++++++++++++++- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 60d5b135..a2fab7c3 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -29,6 +29,45 @@ devture_traefik_config_entrypoint_web_secure_enabled: false ## Using self-signed SSL certificates -Using self-signed certificates with Traefik is a somewhat involved processes, where you need to manually mount the files into the container and adjust the "static" configuration to refer to them. +To use self-signed SSL certificates, you need to disable the certResolvers and the traefik-certs-dumper tool. +You also need to override the providers.file setting in the Traefik configs. +Create a file 'certificates.yml' in /devture-traefik/config/ with the following content: -Feel free to research this approach on your own and improve this guide! +```yaml +tls: + certificates: + - certFile: /ssl/cert.pem + keyFile: /ssl/privkey.pem + stores: + default: + defaultCertificate: + certFile: /ssl/cert.pem + keyFile: /ssl/privkey.pem +``` + +Place the key and your certificate in /devture-traefik/ssl/ +You can use the matrix-aux role for this: + +```yaml +matrix_aux_file_definitions: + - dest: /devture-traefik/ssl/privkey.pem + src: /path/to/privkey.pem + - dest: /devture-traefik/ssl/cert.pem + src: /path/to/cert.pem + - dest: /devture-traefik/config/certificates.yml + src: /path/to/certificates.yml +``` + +Then add the following to your vars.yml: + +```yaml +devture_traefik_config_certificatesResolvers_acme_enabled: false +devture_traefik_certResolver_primary: '' +devture_traefik_ssl_dir_enabled: true +devture_traefik_configuration_extension_yaml: | + providers: + file: + filename: /config/certificates.yml + watch: true +matrix_playbook_traefik_certs_dumper_role_enabled: false +``` From 4b17a1e73a5a3560f6b2bb25ec8ac6ac26c52924 Mon Sep 17 00:00:00 2001 From: plui29989 Date: Tue, 28 Feb 2023 21:09:37 +0100 Subject: [PATCH 2/3] formatting --- docs/configuring-playbook-ssl-certificates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index a2fab7c3..859885dd 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -31,6 +31,7 @@ devture_traefik_config_entrypoint_web_secure_enabled: false To use self-signed SSL certificates, you need to disable the certResolvers and the traefik-certs-dumper tool. You also need to override the providers.file setting in the Traefik configs. + Create a file 'certificates.yml' in /devture-traefik/config/ with the following content: ```yaml @@ -46,6 +47,7 @@ tls: ``` Place the key and your certificate in /devture-traefik/ssl/ + You can use the matrix-aux role for this: ```yaml From 7331d314c422ec9b113ea3d09135355d89610824 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Wed, 1 Mar 2023 09:45:54 +0200 Subject: [PATCH 3/3] Improve wording --- docs/configuring-playbook-ssl-certificates.md | 74 +++++++++++-------- 1 file changed, 42 insertions(+), 32 deletions(-) diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 859885dd..bde425bd 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -29,47 +29,57 @@ devture_traefik_config_entrypoint_web_secure_enabled: false ## Using self-signed SSL certificates -To use self-signed SSL certificates, you need to disable the certResolvers and the traefik-certs-dumper tool. -You also need to override the providers.file setting in the Traefik configs. +To use self-signed SSL certificates, you need to: -Create a file 'certificates.yml' in /devture-traefik/config/ with the following content: - -```yaml -tls: - certificates: - - certFile: /ssl/cert.pem - keyFile: /ssl/privkey.pem - stores: - default: - defaultCertificate: - certFile: /ssl/cert.pem - keyFile: /ssl/privkey.pem -``` - -Place the key and your certificate in /devture-traefik/ssl/ - -You can use the matrix-aux role for this: - -```yaml -matrix_aux_file_definitions: - - dest: /devture-traefik/ssl/privkey.pem - src: /path/to/privkey.pem - - dest: /devture-traefik/ssl/cert.pem - src: /path/to/cert.pem - - dest: /devture-traefik/config/certificates.yml - src: /path/to/certificates.yml -``` - -Then add the following to your vars.yml: +- disable `certResolvers` in Traefik, so it won't attempt to retrieve SSL certificates using the default certificate resolver (using [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/)) +- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the `matrix-aux` role) or manually +- register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/) +- put the SSL files on the server, with the help of this Ansible playbook (via the `matrix-aux` role) or manually ```yaml +# Disable ACME / Let's Encrypt support devture_traefik_config_certificatesResolvers_acme_enabled: false + +# Unset the default certificate resolver devture_traefik_certResolver_primary: '' + +# Keep the SSL directory normally used for ACME / Let's Encrypt certificates. +# We need to explicitly enable this, because disabling ACME support (above) automatically disables it otherwise. devture_traefik_ssl_dir_enabled: true + +# Tell Traefik to load our custom configuration file (certificates.yml). +# The file is created below. See `matrix_aux_file_definitions`. +# The `/config/..` path is an in-container path, not a path on the host. Do not change it! devture_traefik_configuration_extension_yaml: | providers: file: filename: /config/certificates.yml watch: true -matrix_playbook_traefik_certs_dumper_role_enabled: false + +# Use the matrix-aux role to create our custom files on the server. +# If you'd like to do this manually, you remove this `matrix_aux_file_definitions` variable. +matrix_aux_file_definitions: + # Create the privkey.pem file on the server by + # uploading a file from the computer where Ansible is running. + - dest: "{{ devture_traefik_ssl_dir_path }}/privkey.pem" + src: /path/on/your/Ansible/computer/to/privkey.pem + + # Create the cert.pem file on the server + # uploading a file from the computer where Ansible is running. + - dest: "{{ devture_traefik_ssl_dir_path }}/cert.pem" + src: /path/on/your/Ansible/computer/to/cert.pem + + # Create the custom Traefik configuration. + # The `/ssl/..` paths below are in-container paths, not paths on the host. Do not change them! + - dest: "{{ devture_traefik_config_dir_path }}/certificates.yml" + content: | + tls: + certificates: + - certFile: /ssl/cert.pem + keyFile: /ssl/privkey.pem + stores: + default: + defaultCertificate: + certFile: /ssl/cert.pem + keyFile: /ssl/privkey.pem ```