From 4e7bc64dc24e481e94109819305b06421d0dc898 Mon Sep 17 00:00:00 2001 From: Miciah Masters Date: Mon, 29 Jan 2018 16:41:45 -0500 Subject: [PATCH] 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 --- admin_guide/managing_networking.adoc | 44 +++++++++++++++++++++------- 1 file changed, 33 insertions(+), 11 deletions(-) diff --git a/admin_guide/managing_networking.adoc b/admin_guide/managing_networking.adoc index b9b2f322499d..78d31440cc1e 100644 --- a/admin_guide/managing_networking.adoc +++ b/admin_guide/managing_networking.adoc @@ -86,19 +86,41 @@ Alternatively, instead of specifying specific project names, you can use the `--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: +