[enterprise-3.9] managing_networking: Document routes/custom-host

Change the heading "Disabling Host Name Collision Prevention For Ingress
Objects" read "Routes and Ingress Objects" because the section discusses
both routes and ingresses.

Reorder the text to first state what host name collision prevention is,
then its purpose, and then how to disable it.

Explicitly state that the cluster administrator can edit the host name on
an existing route.

Document how to disable host name collision prevention for routes.

Add a "WARNING" marker to the text that explains about host name hijacking.

This commit fixes bug 1536340.

https://bugzilla.redhat.com/show_bug.cgi?id=1536340
(cherry picked from commit 4e7bc64) xref:openshift#7398

Author: Miciah

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:
 +