Chapter 14. Enabling SSL/TLS on overcloud public endpoints

download PDF

By default, the overcloud uses unencrypted endpoints for the overcloud services. To enable SSL/TLS in your overcloud, Red Hat recommends that you use a certificate authority (CA) solution.

When you use a certificate authority (CA) solution, you have production ready solutions such as a certificate renewals, certificate revocation lists (CRLs), and industry accepted cryptography. For information on using Red Hat Identity Manager (IdM) as a CA, see Implementing TLS-e with Ansible.

You can use the following manual process to enable SSL/TLS for Public API endpoints only, the Internal and Admin APIs remain unencrypted. You must also manually update SSL/TLS certificates if you do not use a CA. For more information, see Manually updating SSL/TLS certificates.


  • Network isolation to define the endpoints for the Public API.
  • The openssl-perl package is installed.
  • You have an SSL/TLS certificate. For more information see Configuring custom SSL/TLS certificates.

14.1. Initializing the signing host

The signing host is the host that generates and signs new certificates with a certificate authority. If you have never created SSL certificates on the chosen signing host, you might need to initialize the host so that it can sign new certificates.


  1. The /etc/pki/CA/index.txt file contains records of all signed certificates. Ensure that the filesystem path and index.txt file are present:

    $ sudo mkdir -p /etc/pki/CA
    $ sudo touch /etc/pki/CA/index.txt
  2. The /etc/pki/CA/serial file identifies the next serial number to use for the next certificate to sign. Check if this file exists. If the file does not exist, create a new file with a new starting value:

    $ echo '1000' | sudo tee /etc/pki/CA/serial

14.2. Creating a certificate authority

Normally you sign your SSL/TLS certificates with an external certificate authority. In some situations, you might want to use your own certificate authority. For example, you might want to have an internal-only certificate authority.


  1. Generate a key and certificate pair to act as the certificate authority:

    $ openssl genrsa -out ca.key.pem 4096
    $ openssl req  -key ca.key.pem -new -x509 -days 7300 -extensions v3_ca -out ca.crt.pem
  2. The openssl req command requests certain details about your authority. Enter these details at the prompt. These commands create a certificate authority file called ca.crt.pem.
  3. Set the certificate location as the value for the PublicTLSCAFile parameter in the enable-tls.yaml file. When you set the certificate location as the value for the PublicTLSCAFile parameter, you ensure that the CA certificate path is added to the clouds.yaml authentication file.

        PublicTLSCAFile: /etc/pki/ca-trust/source/anchors/cacert.pem

14.3. Adding the certificate authority to clients

For any external clients aiming to communicate using SSL/TLS, copy the certificate authority file to each client that requires access to your Red Hat OpenStack Platform environment.


  1. Copy the certificate authority to the client system:

    $ sudo cp ca.crt.pem /etc/pki/ca-trust/source/anchors/
  2. After you copy the certificate authority file to each client, run the following command on each client to add the certificate to the certificate authority trust bundle:

    $ sudo update-ca-trust extract

14.4. Creating an SSL/TLS key

Enabling SSL/TLS on an OpenStack environment requires an SSL/TLS key to generate your certificates.


  1. Run the following command to generate the SSL/TLS key (server.key.pem):

    $ openssl genrsa -out server.key.pem 2048

14.5. Creating an SSL/TLS certificate signing request

Complete the following steps to create a certificate signing request.


  1. Copy the default OpenSSL configuration file:

    $ cp /etc/pki/tls/openssl.cnf .
  2. Edit the new openssl.cnf file and configure the SSL parameters that you want to use for director. An example of the types of parameters to modify include:

    distinguished_name = req_distinguished_name
    req_extensions = v3_req
    countryName = Country Name (2 letter code)
    countryName_default = AU
    stateOrProvinceName = State or Province Name (full name)
    stateOrProvinceName_default = Queensland
    localityName = Locality Name (eg, city)
    localityName_default = Brisbane
    organizationalUnitName = Organizational Unit Name (eg, section)
    organizationalUnitName_default = Red Hat
    commonName = Common Name
    commonName_default =
    commonName_max = 64
    [ v3_req ]
    # Extensions to add to a certificate request
    basicConstraints = CA:FALSE
    keyUsage = nonRepudiation, digitalSignature, keyEncipherment
    subjectAltName = @alt_names
    IP.1 =
    DNS.1 = instack.localdomain
    DNS.2 = vip.localdomain
    DNS.3 =

    Set the commonName_default to one of the following entries:

    • If you are using an IP address to access director over SSL/TLS, use the undercloud_public_host parameter in the undercloud.conf file.
    • If you are using a fully qualified domain name to access director over SSL/TLS, use the domain name.

    Edit the alt_names section to include the following entries:

    • IP - A list of IP addresses that clients use to access director over SSL.
    • DNS - A list of domain names that clients use to access director over SSL. Also include the Public API IP address as a DNS entry at the end of the alt_names section.

    For more information about openssl.cnf, run the man openssl.cnf command.

  3. Run the following command to generate a certificate signing request (server.csr.pem):

    $ openssl req -config openssl.cnf -key server.key.pem -new -out server.csr.pem

    Ensure that you include your OpenStack SSL/TLS key with the -key option.

This command generates a server.csr.pem file, which is the certificate signing request. Use this file to create your OpenStack SSL/TLS certificate.

14.6. Creating the SSL/TLS certificate

To generate the SSL/TLS certificate for your OpenStack environment, the following files must be present:

The customized configuration file that specifies the v3 extensions.
The certificate signing request to generate and sign the certificate with a certificate authority.
The certificate authority, which signs the certificate.
The certificate authority private key.


  1. Run the following command to create a certificate for your undercloud or overcloud:

    $ sudo openssl ca -config openssl.cnf -extensions v3_req -days 3650 -in server.csr.pem -out server.crt.pem -cert ca.crt.pem -keyfile ca.key.pem

    This command uses the following options:

    Use a custom configuration file, which is the openssl.cnf file with v3 extensions.
    -extensions v3_req
    Enabled v3 extensions.
    Defines how long in days until the certificate expires.
    The certificate signing request.
    The resulting signed certificate.
    The certificate authority file.
    The certificate authority private key.

This command creates a new certificate named server.crt.pem. Use this certificate in conjunction with your OpenStack SSL/TLS key

14.7. Enabling SSL/TLS

To enable SSL/TLS in your overcloud, you must create an environment file that contains parameters for your SSL/TLS certiciates and private key.


  1. Copy the enable-tls.yaml environment file from the heat template collection:

    $ cp -r /usr/share/openstack-tripleo-heat-templates/environments/ssl/enable-tls.yaml ~/templates/.
  2. Edit this file and make the following changes for these parameters:


    Copy the contents of the certificate file (server.crt.pem) into the SSLCertificate parameter:

      SSLCertificate: |
        -----BEGIN CERTIFICATE-----
        -----END CERTIFICATE-----

    The certificate contents require the same indentation level for all new lines.


    If you have an intermediate certificate, copy the contents of the intermediate certificate into the SSLIntermediateCertificate parameter:

      SSLIntermediateCertificate: |
        -----BEGIN CERTIFICATE-----
        -----END CERTIFICATE-----

    The certificate contents require the same indentation level for all new lines.


    Copy the contents of the private key (server.key.pem) into the SSLKey parameter:

      SSLKey: |
        -----BEGIN RSA PRIVATE KEY-----
        -----END RSA PRIVATE KEY-----

    The private key contents require the same indentation level for all new lines.

14.8. Injecting a root certificate

If the certificate signer is not in the default trust store on the overcloud image, you must inject the certificate authority into the overcloud image.


  1. Copy the inject-trust-anchor-hiera.yaml environment file from the heat template collection:

    $ cp -r /usr/share/openstack-tripleo-heat-templates/environments/ssl/inject-trust-anchor-hiera.yaml ~/templates/.

Edit this file and make the following changes for these parameters:


Lists each certificate authority content (CA) to inject into the overcloud. The overcloud requires the CA files used to sign the certificates for both the undercloud and the overcloud. Copy the contents of the root certificate authority file (ca.crt.pem) into an entry. For example, your CAMap parameter might look like the following:

      content: |
        -----BEGIN CERTIFICATE-----
        -----END CERTIFICATE-----
      content: |
        -----BEGIN CERTIFICATE-----
        -----END CERTIFICATE-----

The certificate authority contents require the same indentation level for all new lines.

You can also inject additional CAs with the CAMap parameter.

14.9. Configuring DNS endpoints

If you use a DNS hostname to access the overcloud through SSL/TLS, copy the /usr/share/openstack-tripleo-heat-templates/environments/predictable-placement/custom-domain.yaml file into the /home/stack/templates directory.


It is not possible to redeploy with a TLS-everywhere architecture if this environment file is not included in the initial deployment.

Configure the host and domain names for all fields, adding parameters for custom networks if needed:

the DNS domain for hosts.
The DNS hostname of the overcloud endpoints.
The DNS name of the provisioning network endpoint.
The DNS name of the Internal API endpoint.
The DNS name of the storage endpoint.
The DNS name of the storage management endpoint.
A list of DNS servers that you want to use. The configured DNS servers must contain an entry for the configured CloudName that matches the IP address of the Public API.


  • Add a list of DNS servers to use under parameter defaults, in either a new or existing environment file:

      DnsServers: [""]

14.10. Adding environment files during overcloud creation

Use the -e option with the deployment command openstack overcloud deploy to include environment files in the deployment process. Add the environment files from this section in the following order:

  • The environment file to enable SSL/TLS (enable-tls.yaml)
  • The environment file to set the DNS hostname (custom-domain.yaml)
  • The environment file to inject the root certificate authority (inject-trust-anchor-hiera.yaml)
  • The environment file to set the public endpoint mapping:

    • If you use a DNS name for accessing the public endpoints, use /usr/share/openstack-tripleo-heat-templates/environments/ssl/tls-endpoints-public-dns.yaml
    • If you use a IP address for accessing the public endpoints, use /usr/share/openstack-tripleo-heat-templates/environments/ssl/tls-endpoints-public-ip.yaml


  • Use the following deployment command snippet as an example of how to include your SSL/TLS environment files:
$ openstack overcloud deploy --templates \
-e /home/stack/templates/enable-tls.yaml \
-e ~/templates/custom-domain.yaml \
-e ~/templates/inject-trust-anchor-hiera.yaml \
-e /usr/share/openstack-tripleo-heat-templates/environments/ssl/tls-endpoints-public-dns.yaml

14.11. Manually Updating SSL/TLS Certificates

Complete the following steps if you are using your own SSL/TLS certificates that are not auto-generated from the TLS everywhere (TLS-e) process.


  1. Edit your heat templates with the following content:

    • Edit the enable-tls.yaml file and update the SSLCertificate, SSLKey, and SSLIntermediateCertificate parameters.
    • If your certificate authority has changed, edit the inject-trust-anchor-hiera.yaml file and update the CAMap parameter.
  2. Rerun the deployment command:

    $ openstack overcloud deploy --templates \
    -e /home/stack/templates/enable-tls.yaml \
    -e ~/templates/custom-domain.yaml \
    -e ~/templates/inject-trust-anchor-hiera.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/ssl/tls-endpoints-public-dns.yaml
  3. On the director, run the following command for each Controller:

    ssh heat-admin@<controller> sudo podman \
    restart $(podman ps --format="{{.Names}}" | grep -w -E 'haproxy(-bundle-.*-[0-9]+)?')
Red Hat logoGithubRedditYoutubeTwitter


Try, buy, & sell


About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.