Certificate management
All CHI-in-a-Box APIs and application endpoints are exposed over the public Internet via TLS-encrypted proxies served by HAProxy. A valid SSL certificate is needed for the kolla_external_fqdn
you provide. You can use either an automated LetsEncrypt workflow or provide a certificate you have obtained from another certificate authority (by default, this will be, relative to your site configuration directory, ./certificates/haproxy.pem
).
LetsEncrypt
Setup
In order to use the LetsEncrypt method, you must first enable the LetsEncrypt agents for your deployment:
Ensure the agents are deployed before proceeding:
At this point, verify that the ACME server is running by visiting: http://<kolla_external_fqdn>/.well-known/acme-challenge/
If everything has gone well, you'll get a 404 from nginx.
Initial certificate generation
Currently, the initial certificate generation is not yet automated (https://github.com/ChameleonCloud/chi-in-a-box/issues/116). You must perform the following steps:
Finally, enable external TLS in your defaults.yml
And reconfigure ./cc-ansible reconfigure --tags haproxy
Certificate renewal
Any LetsEncrypt certificates will be automatically renewed. However, HAProxy will not automatically restart when this happens, meaning it will not detect or pick up the new certificates (see https://github.com/ChameleonCloud/chi-in-a-box/issues/125). For the time being, you may wish to set up a periodic task to restart HAProxy every few weeks.
Bring your own certificate
When providing your own certificate file, care must be taken to format it for HAProxy. HAProxy requires a PEM file with the following information, concatenated in order:
Your private key
Your public certificate
(Optional) Your intermediate certificates. Place them in reverse order here, the uppermost certificate coming last.
This should end up looking something like:
Most likely you will not need to add more than one intermediate certificate.
Place your PEM file in $site_config/certificates/haproxy.pem
(or whatever the value of kolla_external_fqdn_cert
) and ensure it is not world-readable (chmod 400
). Then, run a reconfiguration of HAProxy to copy the new certificate and restart HAProxy:
Debugging certificates
If you're having trouble with your certs failing verification, What's my Chain Cert? is an excellent debugging tool and can help pinpoint issues such as an expired intermediate certificate.
Last updated