Bug 1738401

Summary:	Ingress: Improve config.openshift.io resource description
Product:	OpenShift Container Platform	Reporter:	Hongan Li <hongli>
Component:	Networking	Assignee:	Dan Mace <dmace>
Networking sub component:	router	QA Contact:	Hongan Li <hongli>
Status:	CLOSED ERRATA	Docs Contact:
Severity:	high
Priority:	high	CC:	aos-bugs, xtian
Version:	4.2.0
Target Milestone:	---
Target Release:	4.2.0
Hardware:	Unspecified
OS:	Unspecified
Whiteboard:
Fixed In Version:		Doc Type:	If docs needed, set a value
Doc Text:		Story Points:	---
Clone Of:		Environment:
Last Closed:	2019-10-16 06:35:02 UTC	Type:	Bug
Regression:	---	Mount Type:	---
Documentation:	---	CRM:
Verified Versions:		Category:	---
oVirt Team:	---	RHEL 7.3 requirements from Atomic Host:
Cloudforms Team:	---	Target Upstream Version:
Embargoed:

Description Hongan Li 2019-08-07 06:06:59 UTC

Description of problem:
same to https://bugzilla.redhat.com/show_bug.cgi?id=1732146

"The various cluster config config.openshift.io resource descriptions have been copied and pasted from each other and have no detail. Administrators don't know what these configurations are for."

Version-Release number of selected component (if applicable):
4.2.0-0.nightly-2019-08-06-195545

How reproducible:
100%

Steps to Reproduce:
1. oc explain ingress --api-version=config.openshift.io/v1
2.


Actual results:
<---snip--->
DESCRIPTION:
     Ingress holds cluster-wide information about Ingress. The canonical name is
     `cluster` TODO this object is an example of a possible grouping and is
     subject to change or removal
<---snip--->

Expected results:
the description should be improved:
1. "TODO this object is an example..." should be removed.
2. "Ingress holds cluster-wide information about Ingress" looks meaningless, better to tell that it holds cluster-wide settings like default route subdomain for Ingress.


Additional info:
please also help confirm if domain can be changed by user. if not please update description below by adding "Once set, this field cannot be changed.".

FIELDS:
   domain	<string>
     domain is used to generate a default host name for a route when the route's
     host name is empty. The generated host name will follow this pattern:
     "<route-name>.<route-namespace>.<domain>".

Comment 2 Hongan Li 2019-08-20 05:55:39 UTC

The PR has been merged some days ago, but checked with latest nightly and ci build and both descriptions are not updated, so I moving this to MODIFIED.


$ oc get clusterversion
NAME      VERSION                             AVAILABLE   PROGRESSING   SINCE   STATUS
version   4.2.0-0.nightly-2019-08-19-201622   True        False         5h56m   Cluster version is 4.2.0-0.nightly-2019-08-19-201622

$ oc get clusterversion
NAME      VERSION                        AVAILABLE   PROGRESSING   SINCE   STATUS
version   4.2.0-0.ci-2019-08-19-233324   True        False         170m    Cluster version is 4.2.0-0.ci-2019-08-19-233324


oc explain ingress --api-version=config.openshift.io/v1
KIND:     Ingress
VERSION:  config.openshift.io/v1

DESCRIPTION:
     Ingress holds cluster-wide information about Ingress. The canonical name is
     `cluster` TODO this object is an example of a possible grouping and is
     subject to change or removal

Comment 4 Dan Mace 2019-08-22 19:28:51 UTC

Looks like the fix also needs https://github.com/openshift/cluster-config-operator/pull/86.

Comment 6 Hongan Li 2019-08-23 10:00:03 UTC

verified with 4.2.0-0.nightly-2019-08-23-034826 and issue has been fixed.

$ oc explain ingress --api-version=config.openshift.io/v1
KIND:     Ingress
VERSION:  config.openshift.io/v1

DESCRIPTION:
     Ingress holds cluster-wide information about ingress, including the default
     ingress domain used for routes. The canonical name is `cluster`.
<---snip--->

$ oc explain ingress.spec --api-version=config.openshift.io/v1
KIND:     Ingress
VERSION:  config.openshift.io/v1

RESOURCE: spec <Object>

DESCRIPTION:
     spec holds user settable values for configuration

FIELDS:
   domain	<string>
     domain is used to generate a default host name for a route when the route's
     host name is empty. The generated host name will follow this pattern:
     "<route-name>.<route-namespace>.<domain>". It is also used as the default
     wildcard domain suffix for ingress. The default ingresscontroller domain
     will follow this pattern: "*.<domain>". Once set, changing domain is not
     currently supported.

Comment 7 errata-xmlrpc 2019-10-16 06:35:02 UTC

Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

https://access.redhat.com/errata/RHBA-2019:2922