Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve tls certificate documentation #644

Merged
merged 5 commits into from
Nov 29, 2024
Merged

Improve tls certificate documentation #644

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7cfbbbc
Improve TLS configuration documenation
scoopex Sep 18, 2024
c343011
Apply suggestions from code review
scoopex Oct 11, 2024
4abb4e4
add reference
scoopex Oct 11, 2024
e5e559d
tried to make the description better understandable
scoopex Oct 11, 2024
af1139f
explanation revised
scoopex Oct 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 98 additions & 28 deletions docs/guides/configuration-guide/loadbalancer.md
View file
Open in desktop
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 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

```yaml title="environments/kolla/configuration.yml"
Expand All @@ -25,42 +29,79 @@ hosts_additional_entries:

## TLS certificates

To enable external TLS encryption:
:::warning
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.
:::

```yaml title="environments/kolla/configuration.yml"
kolla_enable_tls_external: "yes"
```
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.

To enable internal TLS encryption:
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.

```yaml title="environments/kolla/configuration.yml"
kolla_enable_tls_internal: "yes"
```
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

Suggested change
are designed to to handle all possible configuration transitions on their own.
are designed to handle all possible configuration transitions on their own.


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. Activate 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 changes to 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 preparation tasks for the CA, which is later followed
by the [general procedure](#general-procedure) 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 +113,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 +125,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 procedure](#general-procedure) 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.
Comment on lines +148 to +149
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not necessarily true anymore since you can configure distinct ACME servers for internal or external usage, they only need to be reachable from the control nodes, see:

https://docs.openstack.org/kolla-ansible/latest/admin/tls.html#generating-tls-certificates-with-let-s-encrypt

so you can now use a private ACME-CA-Server in an air gapped environment.


1. Activate 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
Loading