From 6d9cf739caaf2e5fbd1d8126fec654263e8339b0 Mon Sep 17 00:00:00 2001
From: Dave McCowan <dmccowan@cisco.com>
Date: Mon, 7 Mar 2016 21:27:35 -0500
Subject: [PATCH] Add documentation for two-VIP and TLS blueprints
Relates-to: blueprint kolla-ssl
Change-Id: Id82d22c2195be5d897c781f28087a1ea422b8bea
---
doc/advanced-configuration.rst | 125 +++++++++++++++++++++++++++++++++
tools/openrc-example | 2 +-
2 files changed, 126 insertions(+), 1 deletion(-)
diff --git a/doc/advanced-configuration.rst b/doc/advanced-configuration.rst
index fda524ce85..12465f1f23 100644
--- a/doc/advanced-configuration.rst
+++ b/doc/advanced-configuration.rst
@@ -1,6 +1,131 @@
Advanced Configuration
======================
+Endpoint Network Configuration
+------------------------------
+When an OpenStack cloud is deployed, each services' REST API is presented
+as a series of endpoints. These endpoints are the admin URL, the internal
+URL, and the external URL.
+
+Kolla offers two options for assigning these endpoints to network addresses.
+These are combined and separate. For the combined option, all three
+endpoints share the same IP address. For the separate option, the external
+URL is assigned to an IP address that is different that the IP address
+shared by the internal and admin URLs.
+
+The configuration parameters related to these options are:
+- kolla_internal_vip_address
+- network_interface
+- kolla_external_vip_address
+- kolla_external_vip_interface
+
+For the combined option, set the two variables below, while allowing the
+other two to accept their default values. In this configuration all REST
+API requests, internal and external, will flow over the same network.
+::
+
+ kolla_internal_vip_address: "10.10.10.254"
+ network_interface: "eth0"
+
+For the separate option, set these four variables. In this configuration
+the internal and external REST API requests can flow over separate
+networks.
+::
+
+ kolla_internal_vip_address: "10.10.10.254"
+ network_interface: "eth0"
+ kolla_external_vip_address: "10.10.20.254"
+ kolla_external_vip_interface: "eth1"
+
+
+Fully Qualified Domain Name Configuration
+-----------------------------------------
+When addressing a server on the internet, it is more common to use
+a name, like www.example.net, instead of an address like 10.10.10.254.
+If you prefer to use names to address the endpoints in your kolla
+deployment use the variables:
+- kolla_internal_fqdn
+- kolla_external_fqdn
+::
+ kolla_internal_fqdn: inside.mykolla.example.net
+ kolla_external_fqdn: mykolla.example.net
+
+Provisions must be taken outside of kolla for these names to map to the
+configured IP addresses. Using a DNS server or the /etc/hosts file are
+two ways to create this mapping.
+
+TLS Configuration
+-----------------
+An additional endpoint configuration option is to enable or disable
+TLS protection for the external VIP. TLS allows a client to authenticate
+the OpenStack service endpoint and allows for encryption of the requests
+and responses.
+
+.. NOTE:: The kolla_internal_vip_address and kolla_external_vip_address must
+ be different to enable TLS on the external network.
+
+The configuration variables that control TLS networking are:
+- kolla_enable_tls_external
+- kolla_external_fqdn_cert
+
+The default for TLS is disabled; to enable TLS networking:
+::
+
+ kolla_enable_tls_external: "yes"
+ kolla_external_fqdn_cert: "{{ node_config_directory }}/certificates/mycert.pem"
+
+
+.. NOTE:: TLS authentication is based on certificates that have been
+ signed by trusted Certificate Authorities. Examples of commercial
+ CAs are Comodo, Symantec, GoDaddy, and GlobalSign. Letsencrypt.org
+ is a CA that will provided trusted certificates at no charge. Many
+ company's IT departments will provide certificates within that
+ company's domain. If using a trusted CA is not possible for your
+ situation, you can use OpenSSL to create your own or see the section
+ below about kolla generated self-signed certificates.
+
+Two certificate files are required to use TLS securely with authentication.
+These two files will be provided by your Certificate Authority. These
+two files are the server certificate with private key and the CA certificate
+with any intermediate certificates. The server certificate needs to be
+installed with the kolla deployment and is configured with the
+kolla_external_fqdn_cert parameter. If the server certificate provided
+is not already trusted by the client, then the CA certificate file will
+need to be distributed to the client.
+
+When using TLS to connect to a public endpoint, an OpenStack client will
+have settings similar to this:
+::
+
+ export OS_PROJECT_DOMAIN_ID=default
+ export OS_USER_DOMAIN_ID=default
+ export OS_PROJECT_NAME=demo
+ export OS_USERNAME=demo
+ export OS_PASSWORD=demo-password
+ export OS_AUTH_URL=https://mykolla.example.net:5000
+ # os_cacert is optional for trusted certificates
+ export OS_CACERT=/etc/pki/mykolla-cacert.crt
+ export OS_IDENTITY_API_VERSION=3
+
+Self-Signed Certificates
+------------------------
+.. NOTE:: Self-signed certificates should never be used in production.
+
+It is not always practical to get a certificate signed by a well-known
+trust CA, for example a development or internal test kolla deployment. In
+these cases it can be useful to have a self-signed certificate to use.
+
+For convenience, the kolla-ansible command will generate the necessary
+certificate files based on the information in the globals.yml configuration
+file.
+::
+
+ kolla-ansible certificates
+
+The files haproxy.pem and haproxy-ca.pem will be generated and stored
+in the /etc/kolla/certificates/ directory.
+
+
Deployment Configuration
------------------------
TODO(all) fill this section out
diff --git a/tools/openrc-example b/tools/openrc-example
index fec34259a9..72e87fdf4a 100644
--- a/tools/openrc-example
+++ b/tools/openrc-example
@@ -44,6 +44,6 @@ export OS_USER_DOMAIN_ID=default
export OS_PROJECT_NAME=admin
export OS_USERNAME=admin
export OS_PASSWORD=<keystone_admin_password>
-export OS_AUTH_URL=http://<kolla_external_fqdn>:<keystone_public_port>
+export OS_AUTH_URL=https://<kolla_external_fqdn>:<keystone_public_port>
export OS_CACERT=<path_to_kolla_external_cacert>
export OS_IDENTITY_API_VERSION=3