Support external/pre-provisioned authoritative cluster DNS (#690)

* Document how to use fully external DNS servers w/o provisioning
  dns servers group with Heat.

* Document how to use a mixed servers setup for dynamic records
  updates mathing public or private views.

* Allow custom nsupdate key names for OSP10 dns service compatibility.
  The osp-dns configures the named service with the fixed key_name
  'update-key'. Add optional key_name for the external_nsupdate_keys
  public section to allow custom key names.

1 files changed, 50 insertions, 6 deletions

diff --git a/playbooks/provisioning/openstack/README.md b/playbooks/provisioning/openstack/README.md
index c9f651032..2eb9aa9cd 100644
--- a/playbooks/provisioning/openstack/README.md
+++ b/playbooks/provisioning/openstack/README.md
@@ -53,8 +53,9 @@ Otherwise, even if there are differences between the two versions, installation
 * Assigns Cinder volumes to the servers
 * Set up an `openshift` user with sudo privileges
 * Optionally attach Red Hat subscriptions
-* Set up a bind-based DNS server
-* When deploying more than one master, set up a HAproxy server
+* Sets up a bind-based DNS server or configures the cluster servers to use an external DNS server.
+* Supports mixed in-stack/external DNS servers for dynamic updates.
+* When deploying more than one master, sets up a HAproxy server
 
 
 ## Set up
@@ -69,9 +70,17 @@ Otherwise, even if there are differences between the two versions, installation
 
 ### Update `inventory/group_vars/all.yml`
 
+#### DNS configuration variables
+
 Pay special attention to the values in the first paragraph -- these
 will depend on your OpenStack environment.
 
+Note that the provsisioning playbooks update the original Neutron subnet
+created with the Heat stack to point to the configured DNS servers.
+So the provisioned cluster nodes will start using those natively as
+default nameservers. Technically, this allows to deploy OpenShift clusters
+without dnsmasq proxies.
+
 The `env_id` and `public_dns_domain` will form the cluster's DNS domain all
 your servers will be under. With the default values, this will be
 `openshift.example.com`. For workloads, the default subdomain is 'apps'.
@@ -93,10 +102,45 @@ daemon that in turn proxies DNS requests to the authoritative DNS server.
 When Network Manager is enabled for provisioned cluster nodes, which is
 normally the case, you should not change the defaults and always deploy dnsmasq.
 
-Note that the authoritative DNS server is configured on post provsision
-steps, and the Neutron subnet for the Heat stack is updated to point to that
-server in the end. So the provisioned servers will start using it natively
-as a default nameserver that comes from the NetworkManager and cloud-init.
+`external_nsupdate_keys` describes an external authoritative DNS server(s)
+processing dynamic records updates in the public and private cluster views:
+
+    external_nsupdate_keys:
+      public:
+        key_secret: <some nsupdate key>
+        key_algorithm: 'hmac-md5'
+        key_name: 'update-key'
+        server: <public DNS server IP>
+      private:
+        key_secret: <some nsupdate key 2>
+        key_algorithm: 'hmac-sha256'
+        server: <public or private DNS server IP>
+
+Here, for the public view section, we specified another key algorithm and
+optional `key_name`, which normally defaults to the cluster's DNS domain.
+This just illustrates a compatibility mode with a DNS service deployed
+by OpenShift on OSP10 reference architecture, and used in a mixed mode with
+another external DNS server.
+
+Another example defines an external DNS server for the public view
+additionally to the in-stack DNS server used for the private view only:
+
+    external_nsupdate_keys:
+      public:
+        key_secret: <some nsupdate key>
+        key_algorithm: 'hmac-sha256'
+        server: <public DNS server IP>
+
+Here, updates matching the public view will be hitting the given public
+server IP. While updates matching the private view will be sent to the
+auto evaluated in-stack DNS server's **public** IP.
+
+Note, for the in-stack DNS server, private view updates may be sent only
+via the public IP of the server. You can not send updates via the private
+IP yet. This forces the in-stack private server to have a floating IP.
+See also the [security notes](#security-notes)
+
+#### Other configuration variables
 
 `openstack_ssh_key` is a Nova keypair - you can see your keypairs with
 `openstack keypair list`. This guide assumes that its corresponding private