managing_networking: Document routes/custom-host

[Miciah]

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

[vikram-redhat]

@bfallonf - PTAL.

[bfallonf]

s/regular users/application developers?

Is that what you mean by users?

[Miciah]

I struggled a bit with the terminology. I mean OpenShift users who do not have the cluster-admin role, for which "regular users" seems like a reasonable term. In contrast, the term "application developers" is less obviously a counterpart to "cluster administrator" and is not evocative of authorization and security roles. However, I would like to use the preferred term, whatever it may be.

For what it's worth, git grep on the master branch finds 9 occurrences of "regular users" and 7 occurrences of "application developers". It also found 5 occurrences of "non-administrator users", but that's ambiguous (non-cluster administrator, non-project administrator, or other?).

So, "regular users", "application developers", or is there another, more suitable term?

[bfallonf]

@Miciah Hmm I see. Would it be better to just say "users without the admin role"? "Regular users" does sound a little vague. Not sure if there's the perfect title for the role you're describing. Let me know what you think.

There's another instance on line 120 as well.

[Miciah]

I changed both occurrences of "regular users" to "users without the cluster-admin role". Does it read all right?

Would it be worthwhile to establish conventions for how to refer to users with or without a particular role, and document said conventions in contributing_to_docs/doc_guidelines.adoc?

[bfallonf]

@Miciah LGTM. As for the guidlines, I'll send an email out. It may be that there's an edge case here where you're wanting to refer to users that aren't admins (because otherwise they'd have the admin role), but who also aren't developers, so I'll see what the other writers think.

[Miciah]

Well, they may or may not be developers. RBAC and configurable security policies make devising clear and concise terminology a little tricky. An organization may choose to allow all application developers to edit route hosts, or allow project administrators to do so, or define some new kind of users that have fewer (or different) privileges than the cluster administrator has but more (or different) privileges than application developers have.

[bfallonf]

s/CAUTION/WARNING

I don't think we use caution anywhere.

[Miciah]

Thanks! I used "CAUTION" because I saw it further down in managing_networking.adoc, but "WARNING" does seem to be much more common in other files. Fixed.

[bfallonf]

@Miciah Thanks for this. I think it sums up the process better. If you don't mind, there's a couple docs things to clear up, then I'll merge. Thanks!

[knobunc]

LGTM. Thanks Miciah

[bfallonf]

Thanks @Miciah @knobunc . I'll merge.

[bfallonf]

[rev_history]
|xref:../admin_guide/managing_networking.adoc#admin-guide-manage-networking[Managing Networking]
|Changed the xref:../admin_guide/managing_networking.adoc#admin-guide-disabling-hostname-collision[Disabling Host Name Collision Prevention For Routes and Ingress Objects] section to mention the ability to give users the rights to edits host names on routes and ingress objects.
%

[Miciah]

@bfallonf, sorry to have to bring up another issue, but while testing on 3.6, I discovered that oc create clusterrole does not exist before 3.9.

For 3.6 and 3.7, we need to replace the following:

$ oc create clusterrole route-editor --verb=update --resource=routes.route.openshift.io/custom-host

with the following:

$ oc create -f - <<EOF
apiVersion: v1
kind: ClusterRole
metadata:
  name: route-editor
rules:
- apiGroups:
  - route.openshift.io
  - ""
  resources:
  - routes/custom-host
  verbs:
  - update
EOF

Shall I open a PR against one or more of the 3.6 or 3.7 branches? I'm not familiar with whatever tooling you use to propagate changes to the various branches.

[bfallonf]

Hi @Miciah . No worries. I can update the 3.6 and 3.7 branches with the above. Thanks for letting me know!