Appendix A. SSL/TLS Certificate Configuration

As an optional part of the processes outlined in Section 4.6, “Configuring the Director” or Section 6.10, “Enabling SSL/TLS on the Overcloud”, you can set the use SSL/TLS for communication on either the Undercloud or Overcloud. However, if using a SSL certificate with your own certificate authority, the certificate requires the configuration steps in the following section.

A.1. Initializing the Signing Host

The signing host is the host that generates new certificates and signs them 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.

The /etc/pki/CA/index.txt file stores records of all signed certificates. Check if this file exists. If it does not exist, create an empty file:

$ sudo touch /etc/pki/CA/index.txt

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 it does not exist, create a new file with a new starting value:

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

A.2. Creating a Certificate Authority

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

For example, 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

The openssl req command asks for certain details about your authority. Enter these details.

This creates a certificate authority file called ca.crt.pem.

A.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 your Red Hat OpenStack Platform environment. Once copied to the client, run the following command on the client to add it to the certificate authority trust bundle:

$ sudo cp ca.crt.pem /etc/pki/ca-trust/source/anchors/
$ sudo update-ca-trust extract

A.4. Creating an SSL/TLS Key

Run the following commands to generate the SSL/TLS key (server.key.pem), which we use at different points to generate our undercloud or overcloud certificates:

$ openssl genrsa -out server.key.pem 2048

A.5. Creating an SSL/TLS Certificate Signing Request

This next procedure creates a certificate signing request for either the Undercloud or Overcloud.

Copy the default OpenSSL configuration file for customization.

$ cp /etc/pki/tls/openssl.cnf .

Edit the custom openssl.cnf file and set SSL parameters to use for the 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 the IP address, or fully qualified domain name if using one, of the Public API:

  • For the Undercloud, use the undercloud_public_vip parameter in undercloud.conf. If using a fully qualified domain name for this IP address, use the domain name instead.
  • For the Overcloud, use the IP address for the Public API, which is the first address for the ExternalAllocationPools parameter in your network isolation environment file. If using a fully qualified domain name for this IP address, use the domain name instead.

Edit the alt_names section to include the following entries:

  • IP - A list of IP addresses for clients to access the director over SSL.
  • DNS - A list of domain names for clients to access the 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 man openssl.cnf.

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

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

Make sure to include the SSL/TLS key you created in Section A.4, “Creating an SSL/TLS Key” for the -key option.


The openssl req command asks for several details for the certificate, including the Common Name. Make sure the Common Name is set to the IP address of the Public API for the Undercloud or Overcloud (depending on which certificate set you are creating). The openssl.cnf file should use this IP address as a default value.

Use the server.csr.pem file to create the SSL/TLS certificate in the next section.

A.6. Creating the SSL/TLS Certificate

The following command creates 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:

This results in a certificate named server.crt.pem. Use this certificate in conjunction with the SSL/TLS key from Section A.4, “Creating an SSL/TLS Key” to enable SSL/TLS.

A.7. Using the Certificate with the Undercloud

Run the following command to combine the certificate and key together:

$ cat server.crt.pem server.key.pem > undercloud.pem

This creates a undercloud.pem file. You specify the location of this file for the undercloud_service_certificate option in your undercloud.conf file. This file also requires a special SELinux context so that the HAProxy tool can read it. Use the following example as a guide:

$ sudo mkdir /etc/pki/instack-certs
$ sudo cp ~/undercloud.pem /etc/pki/instack-certs/.
$ sudo semanage fcontext -a -t etc_t "/etc/pki/instack-certs(/.*)?"
$ sudo restorecon -R /etc/pki/instack-certs

Add the undercloud.pem file location to the undercloud_service_certificate option in the undercloud.conf file. For example:

undercloud_service_certificate = /etc/pki/instack-certs/undercloud.pem

In addition, make sure to add your certificate authority from Section A.2, “Creating a Certificate Authority” to the Undercloud’s list of trusted Certificate Authorities so that different services within the Undercloud have access to the certificate authority:

$ sudo cp ca.crt.pem /etc/pki/ca-trust/source/anchors/
$ sudo update-ca-trust extract

Continue installing the Undercloud as per the instructions in Section 4.6, “Configuring the Director”.

A.8. Using the Certificate with the Overcloud

Include the contents of your certificate files in the enable-tls.yaml environment file from Section 6.10, “Enabling SSL/TLS on the Overcloud”. The Overcloud deployment process takes the parameters from enable-tls.yaml and automatically integrates them on each node in the Overcloud.