Add support for ACME http-01 challenge

All docs are included.

Change-Id: Ie29ff7ca340812c8dc0dac493518c87cf7bf137b
Partially-Implements: blueprint letsencrypt-https

3 files changed, 45 insertions, 0 deletions

diff --git a/doc/source/admin/acme.rst b/doc/source/admin/acme.rst
new file mode 100644
index 000000000..6a12efe11
--- /dev/null
+++ b/doc/source/admin/acme.rst
@@ -0,0 +1,41 @@
+.. acme:
+
+==============================
+ACME http-01 challenge support
+==============================
+
+This guide describes how to configure Kolla Ansible to enable ACME http-01
+challenge support.
+As of Victoria, Kolla Ansible supports configuring HAProxy Horizon frontend
+to proxy ACME http-01 challenge requests to selected external (not deployed
+by Kolla Ansible) ACME client servers. These can be ad-hoc or regular servers.
+This guide assumes general knowledge of ACME.
+
+Do note ACME supports http-01 challenge only over official HTTP(S) ports, that
+is 80 (for HTTP) and 443 (for HTTPS). Only Horizon is normally deployed on such
+port with Kolla Ansible (other services use custom ports). This means that,
+as of now, running Horizon is mandatory to support ACME http-01 challenge.
+
+How To (External ACME client)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You need to determine the IP address (and port) of the ACME client server
+used for http-01 challenge (e.g. the host you use to run certbot).
+The default port is usually ``80`` (HTTP). Assuming the IP address of that host
+is ``192.168.1.1``, the config would look like the following:
+
+.. code-block:: yaml
+
+  enable_horizon: "yes"
+  acme_client_servers:
+    - server certbot 192.168.1.1:80
+
+``acme_client_servers`` is a list of HAProxy backend server directives. The
+first parameter is the name of the backend server - it can be arbitrary and
+is used for logging purposes.
+
+After (re)deploying, you can proceed with running the client to host the
+http-01 challenge files. Please ensure Horizon frontend responds on the domain
+you request the certificate for.
+
+To use the newly-generated key-cert pair, follow the :doc:`tls` guide.
diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst
index eb7e906f8..720b663c3 100644
--- a/doc/source/admin/index.rst
+++ b/doc/source/admin/index.rst
@@ -7,6 +7,7 @@ Admin Guides
 
    advanced-configuration
    tls
+   acme
    mariadb-backup-and-restore
    production-architecture-guide
    deployment-philosophy
diff --git a/doc/source/admin/tls.rst b/doc/source/admin/tls.rst
index eefca8247..2e619b512 100644
--- a/doc/source/admin/tls.rst
+++ b/doc/source/admin/tls.rst
@@ -30,6 +30,9 @@ There are two different layers of TLS configuration for OpenStack APIs:
   :ref:`admin-tls-generating-a-private-ca` to use a Kolla Ansible generated
   private CA.
 
+  For details on ACME-enabled CAs, such as letsencrypt.org, please see
+  :doc:`acme`.
+
 Quick Start
 ~~~~~~~~~~~