Merge pull request stackhpc#32 from stackhpc/cert-rotation

Add useful details on ordering for cert rotation

source/operations_and_monitoring.rst

@@ -113,21 +113,27 @@ 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:
 
    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
+<https://docs.openstack.org/kolla-ansible/latest/admin/tls.html>`__ 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
 

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