Appendix A. SSL/TLS Certificate Configuration

You can configure the undercloud to use SSL/TLS for communication over public endpoints. However, if want to you use a SSL certificate with your own certificate authority, you must complete the following configuration steps.


For more information about creating overcloud SSL/TLS certificates, see "Enabling SSL/TLS on Overcloud Public Endpoints" in the Advanced Overcloud Customization guide.

A.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.

The /etc/pki/CA/index.txt file contains 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 the file does not exist, create a new file with a new starting value:

$ 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 want to use your own certificate authority. For example, you might want to have an internal-only certificate authority.

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 at the prompt.

These commands create 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 to your Red Hat OpenStack Platform environment.

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

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

A.4. Creating an SSL/TLS Key

Run the following commands to generate the SSL/TLS key (server.key.pem) that you use at different points to generate your undercloud or overcloud certificates:

$ openssl genrsa -out server.key.pem 2048

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

Complete the following steps to create a certificate signing request for either the undercloud or overcloud.

Copy the default OpenSSL configuration file:

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

Edit the new openssl.cnf file and configure the 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 one of the following entries:

  • If using an IP address to access the director over SSL/TLS, use the undercloud_public_host parameter in undercloud.conf.
  • If using a fully qualified domain name to access the 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 the director over SSL.
  • DNS - A list of domain names that clients use 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 the man openssl.cnf command.

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 the SSL/TLS key you created in Section A.4, “Creating an SSL/TLS Key” with the -key option.

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

A.6. Creating the SSL/TLS Certificate

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:

This command creates a new 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:

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

This command creates a undercloud.pem file. Specify the location of this file for the undercloud_service_certificate option in your undercloud.conf file. This .pem file also requires a special SELinux context so that the HAProxy tool can read it. To configure the SELinux context, complete the following example steps:

$ 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:

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

In addition, ensure you 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 according to the instructions in Section 4.1, “Configuring the director”.