Merge pull request #7398 from Miciah/managing_networking-document-routes-slash-custom-host

managing_networking: Document routes/custom-host

Author: Brice Fallon-Freeman

Diff for: admin_guide/managing_networking.adoc

@@ -86,19 +86,41 @@ Alternatively, instead of specifying specific project names, you can use the
 `--selector=<project_selector>` option.
 
 [[admin-guide-disabling-hostname-collision]]
-== Disabling Host Name Collision Prevention For Ingress Objects
+== Disabling Host Name Collision Prevention For Routes and Ingress Objects
 
 In {product-title}, host name collision prevention for routes and ingress
-objects is enabled by default. This means that the host name in a route or
-ingress object can only be set on creation and not edited afterwards. Disabling
-host name collision prevention lets you edit a host name for ingress objects after creation.
-However, because {product-title} uses the object creation timestamp to determine
-the oldest route or ingress object for a given host name, the route or ingress
-object can hijack a host name with a newer route. This can happen if an older
-route changes its host name, or if an ingress object is introduced.
-
-This is relevant to {product-title} installations that depend upon Kubernetes
-behavior, including allowing the host names in ingress objects be edited.
+objects is enabled by default. This means that users without the *cluster-admin*
+role can set the host name in a route or ingress object only on creation and
+cannot change it afterwards.  However, you can relax this restriction on routes
+and ingress objects for some or all users.
+
+[WARNING]
+====
+Because {product-title} uses the object creation timestamp to determine the
+oldest route or ingress object for a given host name, a route or ingress object
+can hijack a host name of a newer route if the older route changes its host
+name, or if an ingress object is introduced.
+====
+
+As an {product-title} cluster administrator, you can edit the host name in a
+route even after creation.  You can also create a role to allow specific users
+to do so:
+
+----
+$ oc create clusterrole route-editor --verb=update --resource=routes.route.openshift.io/custom-host
+----
+
+You can then bind the new role to a user:
+
+----
+$ oc adm policy add-cluster-role-to-user route-editor user
+----
+
+You can also disable host name collision prevention for ingress objects.  Doing
+so lets users without the *cluster-admin* role edit a host name for ingress
+objects after creation.  This is useful to {product-title} installations that
+depend upon Kubernetes behavior, including allowing the host names in ingress
+objects be edited.
 
 . Add the following to the `master.yaml` file:
 +