Skip to content

Commit

Permalink
Improve TLS configuration documenation
Browse files Browse the repository at this point in the history 
Signed-off-by: Marc Schöchlin <[email protected]>
  • Loading branch information
@scoopex
scoopex committed Sep 18, 2024
1 parent 1126019 commit 7cfbbbc
Showing 1 changed file with 95 additions and 28 deletions.
123 changes: 95 additions & 28 deletions docs/guides/configuration-guide/loadbalancer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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"
Expand All @@ -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
Expand All @@ -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: "<The email used for registration and recovery contact>"
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

Expand Down

0 comments on commit 7cfbbbc

Please sign in to comment.