Bug 1712317

Summary: Make oc explain for Master CRDs show brief introduction under DESCRIPTION instead of <empty>
Product: OpenShift Container Platform Reporter: Xingxing Xia <xxia>
Component: kube-apiserverAssignee: Mike Dame <mdame>
Status: CLOSED ERRATA QA Contact: Xingxing Xia <xxia>
Severity: medium Docs Contact:
Priority: medium    
Version: 4.1.0CC: amobrem, aos-bugs, eminguez, gmontero, jokerman, maszulik, mfojtik, mmccomas, rhamilto, spadgett, sttts, yinzhou
Target Milestone: ---   
Target Release: 4.2.0   
Hardware: Unspecified   
OS: Unspecified   
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: 1708503 Environment:
Last Closed: 2019-10-16 06:29:13 UTC Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Bug Depends On:    
Bug Blocks: 1705752    

Description Xingxing Xia 2019-05-21 10:32:57 UTC
+++ This bug was initially created as a clone of Bug #1705746 +++

Same for below CRDs, can show FIELDS contents, but no DESCRIPTION contents. DESCRIPTION is shown only <empty>:
$ for i in kubeapiservers kubecontrollermanagers openshiftapiservers; do oc explain $i --api-version=operator.openshift.io/v1 | grep -A 3 -B 3 DESCRIPTION; done
KIND:     KubeAPIServer
VERSION:  operator.openshift.io/v1


KIND:     KubeControllerManager
VERSION:  operator.openshift.io/v1


KIND:     OpenShiftAPIServer
VERSION:  operator.openshift.io/v1



$ for i in project apiserver; do oc explain $i --api-version=config.openshift.io/v1 | grep -A 3 -B 3 DESCRIPTION; done 
KIND:     Project
VERSION:  config.openshift.io/v1


KIND:     APIServer
VERSION:  config.openshift.io/v1



Comment 1 Samuel Padgett 2019-05-23 12:42:10 UTC
The UI team would really like to use these values in console, but the descriptions for all config.openshift.io resources seem to be missing from the OpenAPI definitions.

Comment 3 Maciej Szulik 2019-06-03 09:40:41 UTC
Moving to Mike, since according to Stefan this is a problem with the generator.

Comment 4 Stefan Schimanski 2019-06-03 09:43:11 UTC
My comment 2 was slightly wrong (we also lack docs for spec and status, but that's not what this bz is about). Instead: we have godocs above the top-level types, e.g. https://github.com/openshift/api/blob/8f991bdc99ced4d880d2e30e52b76cf8c525bbd4/operator/v1/types_kubecontrollermanager.go#L11, but that does not end up as description of the OpenAPI spec. It's probably a bug in crd-schema-gen.

Comment 5 Xingxing Xia 2019-06-10 09:34:16 UTC
Adding clusterresourcequota too, which also explains "<empty>" DESCRIPTION.
$ oc explain clusterresourcequota
KIND:     ClusterResourceQuota
VERSION:  quota.openshift.io/v1


   apiVersion   <string>

Comment 6 Sally 2019-06-17 13:35:30 UTC
*** Bug 1683055 has been marked as a duplicate of this bug. ***

Comment 7 Mike Dame 2019-06-17 17:42:50 UTC
Update on this: Version 0.2 of k8s/controller-tools seems to generate the top-level type descriptions appropriately. Our generator[1] is currently based on v0.1.x and we are working to update it which I think may fix this problem.

[1] https://github.com/openshift/crd-schema-gen/

Comment 8 Eduardo Minguez 2019-06-18 10:17:09 UTC
This seems to affect the 'machineconfiguration.openshift.io/v1' objects as well:

$ oc api-resources --api-group machineconfiguration.openshift.io -o name

$ oc explain --api-version=machineconfiguration.openshift.io/v1 kubeletconfigs
KIND:     KubeletConfig
VERSION:  machineconfiguration.openshift.io/v1


$ oc explain --api-version=machineconfiguration.openshift.io/v1 containerruntimeconfigs
KIND:     ContainerRuntimeConfig
VERSION:  machineconfiguration.openshift.io/v1


$ oc explain --api-version=machineconfiguration.openshift.io/v1 controllerconfigs
KIND:     ControllerConfig
VERSION:  machineconfiguration.openshift.io/v1


$ oc explain --api-version=machineconfiguration.openshift.io/v1 machineconfigpools
KIND:     MachineConfigPool
VERSION:  machineconfiguration.openshift.io/v1


$ oc explain --api-version=machineconfiguration.openshift.io/v1 machineconfigs
KIND:     MachineConfig
VERSION:  machineconfiguration.openshift.io/v1


$ oc explain --api-version=machineconfiguration.openshift.io/v1 mcoconfigs
KIND:     MCOConfig
VERSION:  machineconfiguration.openshift.io/v1


Comment 9 Mike Dame 2019-06-18 17:00:07 UTC
None of the machine configuration CRDs have any validations on them. They need to be created, either manually or with a generator.

Also, this BZ can be manually fixed by adding a description field to any object's openapiv3 schema. For example in the cluster-config-operator, this section[1] would be updated to:

    description: 'This is the description I want to include in `oc explain`'

This should work around for anyone who needs it while we update the generator to do this automatically

Comment 11 Mike Dame 2019-06-18 20:18:21 UTC
PR to update generator, which will generate the missing descriptions from api: https://github.com/openshift/crd-schema-gen/pull/6

Comment 12 Maciej Szulik 2019-06-19 13:46:23 UTC
*** Bug 1712638 has been marked as a duplicate of this bug. ***

Comment 13 Mike Dame 2019-07-10 16:46:43 UTC
With the successful merge of https://github.com/openshift/cluster-kube-apiserver-operator/pull/514, DESCRIPTION should now work for Kubeapiserver:

$ oc explain kubeapiservers
KIND:     KubeAPIServer
VERSION:  operator.openshift.io/v1

     KubeAPIServer provides information to configure an operator to manage

Kubeapiserver is currently the only operator which we have provided this fix for so far, but this should show that we've fixed the root cause of this bug (descriptions not being populated in CRDs). The same changes in the KAS pull request I linked will need to be applied to every operator that is currently missing a description in oc explain. I will make an effort to update the other operators in this BZ as well

Comment 14 Mike Dame 2019-07-10 20:19:04 UTC
More PRs to add descriptions to components:

Not sure when it would be appropriate to close this bug, as the change itself should probably be triaged out to the teams that own the individual components that are still missing descriptions (ie, this is not a bug with `oc explain`). I'll keep adding it where I see it missing and put this ON_QA once these are merged

Comment 15 Mike Dame 2019-07-11 19:32:26 UTC
PR for the machineconfig CRDs as well: https://github.com/openshift/machine-config-operator/pull/955

Now that the Master CRDs mentioned in this bug should have their descriptions (kubeapiservers kubecontrollermanagers openshiftapiservers), I'm going to set ON_QA. Other components can reference this bug and those PRs for how to generate a description specifically for them

Comment 16 Xingxing Xia 2019-07-16 02:37:17 UTC
Verified in 4.2.0-0.nightly-2019-07-14-223254 for the issue of `for i in kubeapiservers kubecontrollermanagers openshiftapiservers; do oc explain $i --api-version=operator.openshift.io/v1 ...` in comment 0, this issue is fixed.

However, the issue of `for i in project apiserver; do oc explain $i --api-version=config.openshift.io/v1 ...` still exists, these resources still show <empty>, the corresponding bug 1712638 should not be closed as DUP, so I reopen.

Per comment 15, this bug won't fix other components, so the bug 1683055 should be closed as DUP, I reopen too.

clusterresourcequota in comment 5 is owned by Apiserver but is not fixed, so assign back this bug.

BTW, all fix PRs target 4.2 but this bug's Target Release is shown 4.1.z. If don't want to backport, pls update to 4.2

Comment 17 Mike Dame 2019-07-19 16:59:50 UTC
https://github.com/openshift/cluster-config-operator/pull/70 Should add the config and clusterresourcequota descriptions

Comment 18 Mike Dame 2019-07-19 18:53:02 UTC
#70 has merged, so project, apiserver, and clusterresourcequota should have descriptions now, please check again now. Thanks

Comment 19 Xingxing Xia 2019-07-22 07:36:47 UTC
Verified in 4.2.0-0.nightly-2019-07-21-222447

Comment 21 errata-xmlrpc 2019-10-16 06:29:13 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.