From 7cfbbbc2a4d899e006e9a104d584e61e29edf351 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Sch=C3=B6chlin?= Date: Wed, 18 Sep 2024 13:19:34 +0200 Subject: [PATCH 1/5] Improve TLS configuration documenation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Marc Schöchlin --- .../configuration-guide/loadbalancer.md | 123 ++++++++++++++---- 1 file changed, 95 insertions(+), 28 deletions(-) diff --git a/docs/guides/configuration-guide/loadbalancer.md b/docs/guides/configuration-guide/loadbalancer.md index 3aabb8a64e..51c1fc43f4 100644 --- a/docs/guides/configuration-guide/loadbalancer.md +++ b/docs/guides/configuration-guide/loadbalancer.md @@ -5,6 +5,10 @@ sidebar_position: 20 # Loadbalancer +The settings of the following section rely on the mechanisms of Kolla-Ansible, +therefore it's a good idea to use the [upstream documenation](https://docs.openstack.org/kolla-ansible/latest/admin/tls.html) +for finding out details which are not covered by this documentation. + ## IP addresses & FQDNs ```yaml title="environments/kolla/configuration.yml" @@ -25,42 +29,76 @@ hosts_additional_entries: ## TLS certificates -To enable external TLS encryption: +:::warning +To avoid unnecessary additional work and problems, it is recommended that you configure TLS with the intended target +configuration of the specific environment during the initial rollout process. +::: -```yaml title="environments/kolla/configuration.yml" -kolla_enable_tls_external: "yes" -``` +For example: Changes to the configuration of TLS or the fully qualified domain names (FQDNs) will result in new URLs (with and without the https prefix) +stored in the Openstack databases, and in the case of self-signed certificates, the CA certificate must be distributed to all participating clients. -To enable internal TLS encryption: +As a result, the involved Ansible Plays must at least be executed in the correct order, and not all Ansible Plays can handle all possible configuration transitions on their own. +Therefore, in some cases, manual adjustments must be made to the systems. -```yaml title="environments/kolla/configuration.yml" -kolla_enable_tls_internal: "yes" -``` +For this reason, we recommend that you define domains, obtain certificates, and perform configurations in advance. -Two certificate files are required to use TLS securely with authentication, -which will be provided by your Certificate Authority: +## General procedure -* the server certificate with private key -* the CA certificate with any intermediate certificates +To enable TLS encryption the following steps are needed. + +1. Acticate tls encryption for both endpoints + + * To enable external TLS encryption: + + ```yaml title="environments/kolla/configuration.yml" + kolla_enable_tls_external: "yes" + ``` + * To enable internal TLS encryption: + + ```yaml title="environments/kolla/configuration.yml" + kolla_enable_tls_internal: "yes" + ``` + +2. Add the combined server certificate and private key to the following locations in the configuration repository: + * private key & certificates for `kolla_external_fqdn`: `environments/kolla/certificates/haproxy.pem` + * private key & certificates for `kolla_internal_fqdn`: `environments/kolla/certificates/haproxy-internal.pem` +3. Encrypt the certificates using ansible vault: + ``` + make ansible_vault_edit FILE=environments/kolla/certificates/haproxy.pem + make ansible_vault_edit FILE=environments/kolla/certificates/haproxy-internal.pem + ``` +4. Add the changesto the Git repository + ``` + git add environments/kolla/certificates/haproxy.pem \ + environments/kolla/certificates/haproxy-internal.pem \ + environments/kolla/configuration.yml -The combined server certificate and private key needs to be provided at -the following locations in the configuration repository: + git commit -m "Add new certificates" environments/kolla/certificates/haproxy.pem \ + environments/kolla/certificates/haproxy-internal.pem \ + environments/kolla/configuration.yml + ``` +5. Rollout changes + ``` + osism apply loadbalancer + ``` -* private key & certificates for `kolla_external_fqdn`: `environments/kolla/certificates/haproxy.pem` -* private key & certificates for `kolla_internal_fqdn`: `environments/kolla/certificates/haproxy-internal.pem` +### Self-signed certificates -## Generating TLS certificates with Let’s Encrypt +OSISM supports the usage of self-signed certificates with a custom CA i.e if you +are running a test installation or for interim purposes. -## Self-signed certificates +Two certificate files are required to use TLS securely with authentication, +which will be provided by your custom Certificate Authority: -The use of self-signed certificates with a custom CA is possible. However, a few -additional parameters are then required in the configuration so that the custom CA -is known everywhere and the self-signed certificates are accepted as valid. +* the server certificate with private key +* the CA certificate with any intermediate certificates + +The following procedure describes the prepration procedure for the CA, which is later followed +by the general steps described above. 1. Import custom CA Any custom CA can be added via the `certificates_ca` parameter. - The import on the nodes is done via `osism apply certificates`. This is already done in the bootstrap of the nodes. ```yaml title="environments/configuration.yml" @@ -72,6 +110,7 @@ is known everywhere and the self-signed certificates are accepted as valid. -----END CERTIFICATE----- ``` + 2. Manager service The local environment variable `REQUESTS_CA_BUNDLE` must be set explicitly so that @@ -83,16 +122,44 @@ is known everywhere and the self-signed certificates are accepted as valid. ``` 3. Use in OpenStack + * Add the custom CA to the configuration repository in the directory `environments/kolla/certificates/ca` with the same + name like in step 1 + * Configure the custom CA to be copied to the OpenStack containers + ```yaml title="environments/manager/configuration.yml" + kolla_copy_ca_into_containers: "yes" + openstack_cacert: /etc/ssl/certs/ca-certificates.crt + ``` + +4. Import the ca certificate to all nodes so that the custom CA is known everywhere and the self-signed certificates are accepted as valid. + ``` + osism apply certificates + ``` + +5. Execute all steps in the general documentation above + +### Generating TLS certificates with Let’s Encrypt - The custom CA must also be copied into the OpenStack containers. To do this, the custom - CA is first added in a file in the `environments/kolla/certificates/ca` of the configuration - repository. It makes sense to use the same filename like in step 1. +Using Let's encrypt certificates is a good alternative to traditional certificate authorities and +greatly simplifies the administration of TLS certificates. - The import of the custom CA must then be explicitly enabled. +For a working Let's Encrypt configuration, the API endpoints (configured by `kolla_internal_fqdn` and `kolla_external_fqdn`) +must be accessible from the internet. + +1. Acticate Let's Encrypt tls encryption for both endpoints ```yaml title="environments/kolla/configuration.yml" - kolla_copy_ca_into_containers: "yes" - openstack_cacert: /etc/ssl/certs/ca-certificates.crt + enable_letsencrypt: "yes" + letsencrypt_email: "" + kolla_enable_tls_external: "yes" + kolla_enable_tls_internal: "yes" + ``` + +2. Rollout changes + ``` + osism apply loadbalancer + ``` + +For more details about this topic, we recommend the [offical kolla-ansible documentation](https://docs.openstack.org/kolla-ansible/latest/admin/tls.html#generating-tls-certificates-with-let-s-encrypt). ## Second Loadbalancer From c34301159cfcfd2bdc5cc9231a6072cb667d9aef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Sch=C3=B6chlin?= Date: Fri, 11 Oct 2024 09:41:43 +0200 Subject: [PATCH 2/5] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sven Signed-off-by: Marc Schöchlin --- docs/guides/configuration-guide/loadbalancer.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/guides/configuration-guide/loadbalancer.md b/docs/guides/configuration-guide/loadbalancer.md index 51c1fc43f4..bedae3683e 100644 --- a/docs/guides/configuration-guide/loadbalancer.md +++ b/docs/guides/configuration-guide/loadbalancer.md @@ -6,7 +6,7 @@ sidebar_position: 20 # Loadbalancer The settings of the following section rely on the mechanisms of Kolla-Ansible, -therefore it's a good idea to use the [upstream documenation](https://docs.openstack.org/kolla-ansible/latest/admin/tls.html) +therefore it's a good idea to use the [upstream documentation](https://docs.openstack.org/kolla-ansible/latest/admin/tls.html) for finding out details which are not covered by this documentation. ## IP addresses & FQDNs @@ -46,7 +46,7 @@ For this reason, we recommend that you define domains, obtain certificates, and To enable TLS encryption the following steps are needed. -1. Acticate tls encryption for both endpoints +1. Activate tls encryption for both endpoints * To enable external TLS encryption: @@ -67,7 +67,7 @@ To enable TLS encryption the following steps are needed. make ansible_vault_edit FILE=environments/kolla/certificates/haproxy.pem make ansible_vault_edit FILE=environments/kolla/certificates/haproxy-internal.pem ``` -4. Add the changesto the Git repository +4. Add the changes to the Git repository ``` git add environments/kolla/certificates/haproxy.pem \ environments/kolla/certificates/haproxy-internal.pem \ @@ -93,7 +93,7 @@ which will be provided by your custom Certificate Authority: * the server certificate with private key * the CA certificate with any intermediate certificates -The following procedure describes the prepration procedure for the CA, which is later followed +The following procedure describes the preparation tasks for the CA, which is later followed by the general steps described above. 1. Import custom CA @@ -145,7 +145,7 @@ greatly simplifies the administration of TLS certificates. For a working Let's Encrypt configuration, the API endpoints (configured by `kolla_internal_fqdn` and `kolla_external_fqdn`) must be accessible from the internet. -1. Acticate Let's Encrypt tls encryption for both endpoints +1. Activate Let's Encrypt tls encryption for both endpoints ```yaml title="environments/kolla/configuration.yml" enable_letsencrypt: "yes" From 4abb4e4fdf100e267fdb9165f485d7a2795f2538 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Sch=C3=B6chlin?= Date: Fri, 11 Oct 2024 09:45:55 +0200 Subject: [PATCH 3/5] add reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Marc Schöchlin --- docs/guides/configuration-guide/loadbalancer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/configuration-guide/loadbalancer.md b/docs/guides/configuration-guide/loadbalancer.md index bedae3683e..0d188295c4 100644 --- a/docs/guides/configuration-guide/loadbalancer.md +++ b/docs/guides/configuration-guide/loadbalancer.md @@ -94,7 +94,7 @@ which will be provided by your custom Certificate Authority: * the CA certificate with any intermediate certificates The following procedure describes the preparation tasks for the CA, which is later followed -by the general steps described above. +by the [general procedure](#general-procedure) described above. 1. Import custom CA @@ -135,7 +135,7 @@ by the general steps described above. osism apply certificates ``` -5. Execute all steps in the general documentation above +5. Execute all steps in the [general procedure](#general-procedure) above ### Generating TLS certificates with Let’s Encrypt From e5e559d25934f01b02cfad980baaa10d5d2e846c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Sch=C3=B6chlin?= Date: Fri, 11 Oct 2024 10:29:40 +0200 Subject: [PATCH 4/5] tried to make the description better understandable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Marc Schöchlin --- docs/guides/configuration-guide/loadbalancer.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/guides/configuration-guide/loadbalancer.md b/docs/guides/configuration-guide/loadbalancer.md index 0d188295c4..c83f66ddce 100644 --- a/docs/guides/configuration-guide/loadbalancer.md +++ b/docs/guides/configuration-guide/loadbalancer.md @@ -40,7 +40,8 @@ stored in the Openstack databases, and in the case of self-signed certificates, As a result, the involved Ansible Plays must at least be executed in the correct order, and not all Ansible Plays can handle all possible configuration transitions on their own. Therefore, in some cases, manual adjustments must be made to the systems. -For this reason, we recommend that you define domains, obtain certificates, and perform configurations in advance. +For this reason, we recommend that you define and configure the specific details of domains/hostnames and tls-certificates +before running the first rollout procedures of your installation. ## General procedure From af1139f4a1ca3f7dfc96de3edf635ccf14cce348 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Sch=C3=B6chlin?= Date: Mon, 14 Oct 2024 16:06:16 +0200 Subject: [PATCH 5/5] explanation revised MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Marc Schöchlin --- .../configuration-guide/loadbalancer.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/guides/configuration-guide/loadbalancer.md b/docs/guides/configuration-guide/loadbalancer.md index c83f66ddce..e0e0e72ca2 100644 --- a/docs/guides/configuration-guide/loadbalancer.md +++ b/docs/guides/configuration-guide/loadbalancer.md @@ -5,8 +5,8 @@ sidebar_position: 20 # Loadbalancer -The settings of the following section rely on the mechanisms of Kolla-Ansible, -therefore it's a good idea to use the [upstream documentation](https://docs.openstack.org/kolla-ansible/latest/admin/tls.html) +The settings of the following section rely on the mechanisms of Kolla-Ansible, +therefore it's a good idea to consult the [upstream documentation](https://docs.openstack.org/kolla-ansible/latest/admin/tls.html) for finding out details which are not covered by this documentation. ## IP addresses & FQDNs @@ -30,18 +30,20 @@ hosts_additional_entries: ## TLS certificates :::warning -To avoid unnecessary additional work and problems, it is recommended that you configure TLS with the intended target -configuration of the specific environment during the initial rollout process. +To avoid unnecessary additional work and debugging, it is recommended that you configure TLS with the intended target +configuration of the specific environment before executing the initial rollout procedures. ::: -For example: Changes to the configuration of TLS or the fully qualified domain names (FQDNs) will result in new URLs (with and without the https prefix) -stored in the Openstack databases, and in the case of self-signed certificates, the CA certificate must be distributed to all participating clients. +Changes to the configuration of TLS (i.e. enable or disable) or fully qualified domain names (FQDNs) will +result in new URLs (with and without the https prefix). +These addresses are often stored in the Openstack database on initial deployment and cannot +be updated by simply modifying the configuration repository and performing an additional rollout. -As a result, the involved Ansible Plays must at least be executed in the correct order, and not all Ansible Plays can handle all possible configuration transitions on their own. -Therefore, in some cases, manual adjustments must be made to the systems. +In the case of self-signed certificates, the CA certificate must be distributed to all participating +https clients in the correct dependency order and in a manner appropriate to the associated Openstack service. -For this reason, we recommend that you define and configure the specific details of domains/hostnames and tls-certificates -before running the first rollout procedures of your installation. +As a result, at a minimum, the involved Ansible Plays must be run in the appropriate order, and not all Ansible Plays +are designed to to handle all possible configuration transitions on their own. ## General procedure