+++ 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 DESCRIPTION: <empty> FIELDS: KIND: KubeControllerManager VERSION: operator.openshift.io/v1 DESCRIPTION: <empty> FIELDS: KIND: OpenShiftAPIServer VERSION: operator.openshift.io/v1 DESCRIPTION: <empty> FIELDS: $ 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 DESCRIPTION: <empty> FIELDS: KIND: APIServer VERSION: config.openshift.io/v1 DESCRIPTION: <empty> FIELDS:
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