diff --git a/source/operations_and_monitoring.rst b/source/operations_and_monitoring.rst index 596d8c3..f265d36 100644 --- a/source/operations_and_monitoring.rst +++ b/source/operations_and_monitoring.rst @@ -113,13 +113,14 @@ On each controller: Some services may store data in a dedicated Docker volume, which can be removed with ``docker volume rm``. -Installing and Updating TLS Certificates ----------------------------------------- +Installing TLS Certificates +--------------------------- |tls_setup| -To configure TLS for the first time, we write a PEM file to the ``secrets.yml`` -file as ``secrets_kolla_external_tls_cert``. Use a command of this form: +To configure TLS for the first time, we write the contents of a PEM +file to the ``secrets.yml`` file as ``secrets_kolla_external_tls_cert``. +Use a command of this form: .. code-block:: console :substitutions: @@ -127,7 +128,12 @@ file as ``secrets_kolla_external_tls_cert``. Use a command of this form: kayobe# ansible-vault edit ${KAYOBE_CONFIG_PATH}/secrets.yml --vault-password-file=|vault_password_file_path| Concatenate the contents of the certificate and key files to create -``secrets_kolla_external_tls_cert``. +``secrets_kolla_external_tls_cert``. The certificates should be installed in +this order: + +* TLS certificate for the |project_name| OpenStack endpoint |public_endpoint_fqdn| +* Any intermediate certificates +* The TLS certificate private key In ``${KAYOBE_CONFIG_PATH}/kolla.yml``, set the following: @@ -136,16 +142,43 @@ In ``${KAYOBE_CONFIG_PATH}/kolla.yml``, set the following: kolla_enable_tls_external: True kolla_external_tls_cert: "{{ secrets_kolla_external_tls_cert }}" -To configure TLS, we need to reconfigure all services, as endpoint URLs need to +To apply TLS configuration, we need to reconfigure all services, as endpoint URLs need to be updated in Keystone: .. code-block:: console kayobe# kayobe overcloud service reconfigure +Alternative Configuration ++++++++++++++++++++++++++ + +As an alternative to writing the certificates as a variable to +``secrets.yml``, it is also possible to write the same data to a file, +``etc/kayobe/kolla/certificates/haproxy.pem``. The file should be +vault-encrypted in the same manner as secrets.yml. In this instance, +variable ``kolla_external_tls_cert`` does not need to be defined. + +See `Kolla-Ansible TLS guide +`__ for +further details. + +Updating TLS Certificates +------------------------- + +Check the expiry date on an installed TLS certificate from a host that can +reach the |project_name| OpenStack APIs: + +.. code-block:: console + :substitutions: + + openstack# openssl s_client -connect |public_endpoint_fqdn|:443 2> /dev/null | openssl x509 -noout -dates + +*NOTE*: Prometheus Blackbox monitoring can check certificates automatically +and alert when expiry is approaching. + To update an existing certificate, for example when it has reached expiration, -change the value of ``secrets_kolla_external_tls_cert`` and run the following -command: +change the value of ``secrets_kolla_external_tls_cert``, in the same order as +above. Run the following command: .. code-block:: console diff --git a/source/vars.rst b/source/vars.rst index b95f4ce..cb5aa96 100644 --- a/source/vars.rst +++ b/source/vars.rst @@ -35,6 +35,7 @@ .. |project_name| replace:: Acme .. |provisioning_net_cidr| replace:: 192.168.0.0/24 .. |public_api_access_host| replace:: |control_host| +.. |public_endpoint_fqdn| replace:: openstack.acme.example .. |public_network| replace:: public .. |public_subnet| replace:: 10.0.0.0/8 .. |public_vip| replace:: 10.0.0.1