docs(controller): add unit hostname documentation

The documentation explains how to configure the new unitHostname etcd
option for controlling what hostname is exposed to the Docker containers

Author: Arne-Christian Blystad

docs/customizing_deis/controller_settings.rst

@@ -19,17 +19,18 @@ Settings set by controller
 --------------------------
 The following etcd keys are set by the controller component, typically in its /bin/boot script.
 
-===========================              =================================================================================
+=============================            =================================================================================
 setting                                  description
-===========================              =================================================================================
+=============================            =================================================================================
 /deis/controller/host                    IP address of the host running controller
 /deis/controller/port                    port used by the controller service (default: 8000)
 /deis/controller/protocol                protocol for controller (default: http)
 /deis/controller/secretKey               used for secrets (default: randomly generated)
 /deis/controller/builderKey              used by builder to authenticate with the controller (default: randomly generated)
+/deis/controller/unitHostname            See `Unit hostname`_. (default: "default")
 /deis/builder/users/*                    stores user SSH keys (used by builder)
 /deis/domains/*                          domain configuration for applications (used by router)
-===========================              =================================================================================
+=============================            =================================================================================
 
 Settings used by controller
 ---------------------------
@@ -73,3 +74,35 @@ Be sure that your custom image functions in the same way as the `stock controlle
 Deis. Specifically, ensure that it sets and reads appropriate etcd keys.
 
 .. _`stock controller image`: https://github.com/deis/deis/tree/master/controller
+
+Unit hostname
+-------------
+Per default, Docker automatically generates a hostname for your application unit, such as: 
+``5c149b397cd6``. Auto generated hostnames is not always preferred. For instance, 
+New Relic would classify each Docker container as an unique server since they use hostname 
+for grouping applications running on the same server together.
+
+Deis supports configuring hostname assignment through the ``unitHostname`` setting.
+You can change the assignment solution using the following command:
+
+.. code-block:: console
+
+    $ deisctl config controller set unitHostname=application
+
+The valid ``unitHostname`` values are:
+
+default
+    Docker will generate the hostname. Example: ``5c149b397cd6``
+
+application
+    The hostname is assigned based on the unit name. Example: ``dancing-cat.v2.web.1``
+
+server
+    The hostname is assigned based on the CoreOS hostname. Example: 
+    ``ip-10-21-2-168.eu-west-1.compute.internal``
+
+.. note::
+
+    Changes to ``/deis/controller/unitHostname`` requires either pushing a new build to 
+    every application or scaling them down and up.
+    The change is only detected when a container unit is deployed.