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-apiserver | Assignee: | Mike Dame <mdame> |
| Status: | CLOSED ERRATA | QA Contact: | Xingxing Xia <xxia> |
| Severity: | medium | Docs Contact: | |
| Priority: | medium | ||
| Version: | 4.1.0 | CC: | amobrem, aos-bugs, eminguez, gmontero, jokerman, maszulik, mfojtik, mmccomas, rhamilto, spadgett, sttts, yinzhou |
| 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: | 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: | |
| Embargoed: | |||
| Bug Depends On: | |||
| Bug Blocks: | 1705752 | ||
|
Description
Xingxing Xia
2019-05-21 10:32:57 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. The reason: https://github.com/openshift/api/blob/8f991bdc99ced4d880d2e30e52b76cf8c525bbd4/operator/v1/types_kubecontrollermanager.go has not docs. Moving to Mike, since according to Stefan this is a problem with the generator. 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. Adding clusterresourcequota too, which also explains "<empty>" DESCRIPTION.
$ oc explain clusterresourcequota
KIND: ClusterResourceQuota
VERSION: quota.openshift.io/v1
DESCRIPTION:
<empty>
FIELDS:
apiVersion <string>
...
*** Bug 1683055 has been marked as a duplicate of this bug. *** 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/ This seems to affect the 'machineconfiguration.openshift.io/v1' objects as well:
$ oc api-resources --api-group machineconfiguration.openshift.io -o name
containerruntimeconfigs.machineconfiguration.openshift.io
controllerconfigs.machineconfiguration.openshift.io
kubeletconfigs.machineconfiguration.openshift.io
machineconfigpools.machineconfiguration.openshift.io
machineconfigs.machineconfiguration.openshift.io
mcoconfigs.machineconfiguration.openshift.io
$ oc explain --api-version=machineconfiguration.openshift.io/v1 kubeletconfigs
KIND: KubeletConfig
VERSION: machineconfiguration.openshift.io/v1
DESCRIPTION:
<empty>
$ oc explain --api-version=machineconfiguration.openshift.io/v1 containerruntimeconfigs
KIND: ContainerRuntimeConfig
VERSION: machineconfiguration.openshift.io/v1
DESCRIPTION:
<empty>
$ oc explain --api-version=machineconfiguration.openshift.io/v1 controllerconfigs
KIND: ControllerConfig
VERSION: machineconfiguration.openshift.io/v1
DESCRIPTION:
<empty>
$ oc explain --api-version=machineconfiguration.openshift.io/v1 machineconfigpools
KIND: MachineConfigPool
VERSION: machineconfiguration.openshift.io/v1
DESCRIPTION:
<empty>
$ oc explain --api-version=machineconfiguration.openshift.io/v1 machineconfigs
KIND: MachineConfig
VERSION: machineconfiguration.openshift.io/v1
DESCRIPTION:
<empty>
$ oc explain --api-version=machineconfiguration.openshift.io/v1 mcoconfigs
KIND: MCOConfig
VERSION: machineconfiguration.openshift.io/v1
DESCRIPTION:
<empty>
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:
<...>
validation:
openAPIV3Schema:
description: 'This is the description I want to include in `oc explain`'
properties:
<...>
This should work around for anyone who needs it while we update the generator to do this automatically
[1](forgot link) https://github.com/openshift/cluster-config-operator/blob/master/manifests/0000_10_config-operator_01_proxy.crd.yaml#L19-L21 PR to update generator, which will generate the missing descriptions from api: https://github.com/openshift/crd-schema-gen/pull/6 *** Bug 1712638 has been marked as a duplicate of this bug. *** 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 DESCRIPTION: KubeAPIServer provides information to configure an operator to manage kube-apiserver. 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 More PRs to add descriptions to components: https://github.com/openshift/cluster-openshift-apiserver-operator/pull/210 https://github.com/openshift/cluster-kube-controller-manager-operator/pull/265 https://github.com/openshift/cluster-openshift-controller-manager-operator/pull/105 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 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 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 https://github.com/openshift/cluster-config-operator/pull/70 Should add the config and clusterresourcequota descriptions #70 has merged, so project, apiserver, and clusterresourcequota should have descriptions now, please check again now. Thanks Verified in 4.2.0-0.nightly-2019-07-21-222447 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 |