TLS everywhere for the overcloud

TLS everywhere for the overcloud

It is possible to deploy most of the services to use TLS for communications in the internal network as well. This, however, needs several more certificates than the public approach, with the number being dependant on the number of nodes in your deployment. This complicates certificate and key management to the extent where it’s not sustainable to have the deployer inject all the certificates and keys needed and then have to handle all their lifecycles. Then, we have to take into account that a certificate revocation might be needed at some point. So, from both the maintenance and security standpoints this is not sustainable.

For the aforementioned reasons, we decided to rely on certmonger to get the certificates from an actual CA. Certmonger will do the certificate requests and do the certificate renewals when it’s needed, thus reducing the maintenance burden.

FreeIPA has been chosen as the default CA. Certmonger already has a plugin for it, and it has the added value that, besides being able to automatically provide the certificates we need, we can also keep track of the nodes and have an identity for them.


The default CA can be overridden via the CertmongerCA parameter. However, the CA has to be something that certmonger understands, so there are adjustments to be done. For more information on how to change it you can consult the certmonger documentation

Communicating with the CA (FreeIPA) requires the nodes to have proper credentials, and these credentials also need to be transported into the overcloud nodes in a secure manner. To address this, we use a Nova vendordata plugin called novajoin whose purpose is to detect the nodes that are created by nova, register or join them in FreeIPA and provide an OTP that the node can subsequently use to enroll to FreeIPA. The node subsequently enrolls by loading the vendordata-provided JSON via the config-drive, which ends up executing a cloud-init script to do this. With the node enrolled, certificates can be requested securely. Novajoin can also receive extra entries from nova metadata to create extra principals that the services will need. These create service principals for services such as httpd, mysql and haproxy, and are used to requests the certificates for the specific service users with the correct SubjectAltNames.

The following are instructions assuming the default CA, which is FreeIPA.

CA installation

As mentioned before, the default CA is FreeIPA. Due to port conflicts between FreeIPA and some OpenStack services, it’s not trivial to install it in the undercloud. On the other hand, often folks already have a FreeIPA server installed on-premise.

To have a minimal FreeIPA installation with the required functionalities for TLS everywhere in TripleO, you can run the following command:

ipa-server-install -U -r `hostname -d|tr "[a-z]" "[A-Z]"` \
               -p $DirectoryManagerPassword -a $AdminPassword \
               --hostname `hostname -f` \
               --ip-address=$FreeIPAIP \
               --setup-dns --auto-forwarders --auto-reverse

There are several things to note from the aforementioned command:

  • This command assumes that your kerberos realm is the same as your host’s domain name. This is a fairly normal setup, but note that it’s possible to use different values.

  • The $DirectoryManagerPassword and $AdminPassword don’t need to be the same. However, please remember $AdminPassword since it’s what you will use in a subsequent command to set up the undercloud.

  • $FreeIPAIP needs to be an IP address that’s accessible from both the undercloud and the overcloud nodes.

  • We enable DNS because FreeIPA will serve as the nameserver for both the undercloud and overcloud nodes. This simplifies the installation as the nodes can autodiscover FreeIPA’s capabilities (for enrollment and for the CA) through DNS.

  • Assuming the FreeIPA node has working DNS, setting the --auto-forwarders flag adds the node’s configured nameservers and forwards DNS queries to them if needed. Note that you can also specify manually the forwarders for the DNS setup through the --forwarder option.


Take special care to ensure that the $FreeIPAIP is reachable by the undercloud and overcloud nodes. This requirement is commonly overlooked or misunderstood.

For more information on FreeIPA and its capabilities, please consult the FreeIPA documentation


You could also try out the IdM container as an alternative to the FreeIPA installation. Just make sure to enable DNS and follow the considerations listed above.

CA setup

The undercloud needs to be enrolled to FreeIPA, and we need to create some extra privileges/permissions to be used by the novajoin services. Assuming there’s an already existing FreeIPA installation, we can use a script that comes with the python-novajoin package:

sudo novajoin-ipa-setup \
    --principal admin \
    --password < freeipa admin password > \
    --server < freeipa server hostname > \
    --realm < overcloud cloud domain in upper case > \
    --domain < overcloud cloud domain > \
    --hostname < undercloud hostname > \

This command will give us a One-Time Password (OTP) that we can then use for the undercloud enrollment. We can also specify the command to output the OTP into a file by using the --otp-file option.


This can be run from either the undercloud node itself or the FreeIPA node. Just note that the example provided is using the FreeIPA admin credentials. This can be done using another principal if it has the approprite permissions.

Undercloud setup

Now that we have an OTP we can either deploy or update the undercloud. The following settings in undercloud.conf will get the undercloud to enroll to FreeIPA and deploy novajoin:

enable_novajoin = True
ipa_otp = < OTP provided by the novajoin-ipa-setup script >

The undercloud fully-qualified hostname should also be set in undercloud.conf, since this is the host that will be used to enroll to FreeIPA. It should match the one provided in the novajoin-ipa setup script. We can set it like this:

undercloud_hostname = < undercloud FQDN >

It is useful to have FreeIPA set as the DNS server since this will automatically: discover the FreeIPA server hostname, set up the Kerberos realm/domain automatically, and it will set the DNS entries of the overcloud nodes once they’re deployed. We can set it in undercloud.conf with the following setting:

undercloud_nameservers = < FreeIPA IP >


This takes a comma-separated list, so we can set another nameserver with this configuration option.

The undercloud’s neutron must also use the appropriate domain that it will advertise to the overcloud nodes. Assuming we’re using as the domain for the overcloud nodes. We must set the following:

overcloud_domain_name =


The value for overcloud_domain_name in undercloud.conf must match the value for CloudDomain that we’ll set for the overcloud deployment in the following section.

With these settings, do the following command to set the desired configurations and enable novajoin:

openstack undercloud install


Please make sure that the aforementioned configuration options are set in the [DEFAULT] section of undercloud.conf

Overcloud deployment

The TLS-everywhere setup only works with FQDNs so we need to set the appropriate entries for the overcloud endpoints as well as setting an appropriate domain for the nodes that matches the one we set for FreeIPA. We can do this by overriding some parameters via parameter_defaults. Assuming that the domain for our cloud is We’ll set the following in a file we’ll call cloud-names.yaml which we’ll include in our overcloud deploy command:



The value for CloudDomain must match the value for overcloud_domain_name that was configured in undercloud.conf

As with our undercloud, we also want the overcloud nodes’ name server to point to FreeIPA. We can do this by setting the DnsServers parameter via parameter_defaults. You can create an environment file for it, however, since you probably are deploying with network isolation, you can already set this parameter in the network-environment.yaml file that’s referenced in Configuring Network Isolation. So that setting would look like this:

  DnsServers: ["< FreeIPA IP >"]

Remembering that optionally we can set other nameservers with this parameter.

You’ll also need to add set the DNS server for the ctlplane network to point to FreeIPA as described in Configure a nameserver for the Overcloud.

To tell the overcloud deployment to deploy the keystone endpoints (and references) using DNS names instead of IPs, we need to add the following environment to our overcloud deployment:


Finally, to enable TLS in the internal network, we need to use the following environment:


This will set the appropriate resources that enable the certificate requests via certmonger and create the appropriate service principals for kerberos (which are used by FreeIPA).


As part of the enrollment, FreeIPA is set as a trusted CA, so we don’t need to do any extra steps for this.

Classic public TLS and certmonger-based internal TLS

enable-internal-tls.yaml will be used for the internal network endpoints. One can still use the enable-tls.yaml environment for the public endpoints if a specific certificate for the public endpoints is needed.

The arguments for a deployment using injected certificates for the public endpoints, and certmonger-provided certificates for the internal endpoints look like the following:

openstack overcloud deploy \
    -e ~/ssl-heat-templates/environments/ssl/tls-everywhere-endpoints-dns.yaml \
    -e ~/ssl-heat-templates/environments/ssl/enable-tls.yaml \
    -e ~/ssl-heat-templates/environments/ssl/enable-internal-tls.yaml \
    -e ~/cloud-names.yaml

Certmonger-based public and Internal TLS

It is also possible to get all your certificates from a CA. For this you need to include the environments/services/haproxy-public-tls-certmonger.yaml environment file.

To do a deployment with both public and internal endpoints using certificates provided by certmonger, we would need to issue a command similar to the following:

openstack overcloud deploy \
    -e ~/ssl-heat-templates/environments/ssl/tls-everywhere-endpoints-dns.yaml \
    -e ~/ssl-heat-templates/environments/services/haproxy-public-tls-certmonger.yaml \
    -e ~/ssl-heat-templates/environments/ssl/enable-internal-tls.yaml \
    -e ~/cloud-names.yaml
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.