Chapter 14. Enabling SSL/TLS on overcloud public endpoints

By default, the overcloud uses unencrypted endpoints for the overcloud services. To enable SSL/TLS in your overcloud, you must configure the SSL/TLS certificate and include it in the overcloud deployment command.

Note

This process enables SSL/TLS only for Public API endpoints. The Internal and Admin APIs remain unencrypted.

Prerequisites

  • Network isolation to define the endpoints for the Public API.
  • The openssl-perl package is installed.

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.

Procedure

  1. The /etc/pki/CA/index.txt file contains records of all signed certificates. Check if this file exists. If the file does not exist, create the directory path if needed, then create an empty file, index.txt:

    $ 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, serial, with a starting value of 1000:

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

Procedure

  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.

14.3. Adding the Certificate Authority to clients

For any external clients that need to communicate using SSL/TLS, you can add the certificate authority to the client.

Procedure

  1. 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/
  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

For example, the undercloud requires a copy of the certificate authority file so that it can communicate with the overcloud endpoints during creation.

14.4. Creating an SSL/TLS key

Run the following command 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

14.5. Creating an SSL/TLS Certificate Signing Request

Create a certificate signing request for the overcloud.

Procedure

  1. Copy the default OpenSSL configuration file so that you can complete your customization:

    $ cp /etc/pki/tls/openssl.cnf .
  2. Edit the custom openssl.cnf file and set the SSL parameters that you want to use for the overcloud. For example, modify the following parameters:

    [req]
    distinguished_name = req_distinguished_name
    req_extensions = v3_req
    
    [req_distinguished_name]
    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 = 10.0.0.1
    commonName_max = 64
    
    [ v3_req ]
    # Extensions to add to a certificate request
    basicConstraints = CA:FALSE
    keyUsage = nonRepudiation, digitalSignature, keyEncipherment
    subjectAltName = @alt_names
    
    [alt_names]
    IP.1 = 10.0.0.1
    DNS.1 = 10.0.0.1
    DNS.2 = myovercloud.example.com

    Set the commonName_default to one of the following:

    • If you use an IP to access over SSL/TLS, use the Virtual IP for the Public API. Set this VIP by using the PublicVirtualFixedIPs parameter in an environment file. For more information, see Section 13.4, “Assigning predictable Virtual IPs”. If you are not using predictable VIPs, director assigns the first IP address from the range that you define in the ExternalAllocationPools parameter.
    • If you use a fully qualified domain name to access over SSL/TLS, use the domain name instead.

      Include the same Public API IP address as an IP entry and a DNS entry in the alt_names section. If you also use DNS, include the host name for the server as DNS entries in the same section. For more information about openssl.cnf, run man openssl.cnf.

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

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

14.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
Note

If the openssl-perl package is not installed, this command fails with the following error: /etc/pki/CA/newcerts: No such file or directory.

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 14.4, “Creating an SSL/TLS key” to enable SSL/TLS.

14.7. Enabling SSL/TLS

Procedure

  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:

    SSLCertificate

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

    parameter_defaults:
      SSLCertificate: |
        -----BEGIN CERTIFICATE-----
        MIIDgzCCAmugAwIBAgIJAKk46qw6ncJaMA0GCSqGS
        ...
        sFW3S2roS4X0Af/kSSD8mlBBTFTCMBAj6rtLBKLaQ
        -----END CERTIFICATE-----
    Important

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

    SSLIntermediateCertificate

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

    parameter_defaults:
      SSLIntermediateCertificate: |
        -----BEGIN CERTIFICATE-----
        sFW3S2roS4X0Af/kSSD8mlBBTFTCMBAj6rtLBKLaQbIxEpIzrgvpBCwUAMFgxCzAJB
        ...
        MIIDgzCCAmugAwIBAgIJAKk46qw6ncJaMA0GCSqGSIb3DQE
        -----END CERTIFICATE-----
    Important

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

    SSLKey

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

    parameter_defaults:
      ...
      SSLKey: |
        -----BEGIN RSA PRIVATE KEY-----
        MIIEowIBAAKCAQEAqVw8lnQ9RbeI1EdLN5PJP0lVO
        ...
        ctlKn3rAAdyumi4JDjESAXHIKFjJNOLrBmpQyES4X
        -----END RSA PRIVATE KEY-----
    Important

    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.

Procedure

  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:

CAMap

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:

parameter_defaults:
  CAMap:
    ...
    undercloud-ca:
      content: |
        -----BEGIN CERTIFICATE-----
        MIIDlTCCAn2gAwIBAgIJAOnPtx2hHEhrMA0GCS
        BAYTAlVTMQswCQYDVQQIDAJOQzEQMA4GA1UEBw
        UmVkIEhhdDELMAkGA1UECwwCUUUxFDASBgNVBA
        -----END CERTIFICATE-----
    overcloud-ca:
      content: |
        -----BEGIN CERTIFICATE-----
        MIIDBzCCAe+gAwIBAgIJAIc75A7FD++DMA0GCS
        BAMMD3d3dy5leGFtcGxlLmNvbTAeFw0xOTAxMz
        Um54yGCARyp3LpkxvyfMXX1DokpS1uKi7s6CkF
        -----END CERTIFICATE-----
Important

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.

Note

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:

CloudDomain
the DNS domain for hosts.
CloudName
The DNS hostname of the overcloud endpoints.
CloudNameCtlplane
The DNS name of the provisioning network endpoint.
CloudNameInternal
The DNS name of the Internal API endpoint.
CloudNameStorage
The DNS name of the storage endpoint.
DnsServers
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.
CloudNameStorageManagement

The DNS name of the storage management endpoint.

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

    parameter_defaults:
      DnsServers: ["10.0.0.254"]
      ....

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 (cloudname.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

Example deployment command:

$ openstack overcloud deploy --templates \
[...]
-e /home/stack/templates/enable-tls.yaml \
-e ~/templates/cloudname.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/cloudname.yaml \
    -e ~/templates/inject-trust-anchor-hiera.yaml \
    -e /usr/share/openstack-tripleo-heat-templates/environments/ssl/tls-endpoints-public-dns.yaml
  3. Run /usr/bin/certmonger-haproxy-refresh.sh on each controller to notify haproxy of the change.