Description of problem: When trying to learn the SRO CRD, I make use of "oc explain" - but most of the fields in the CRD are either vaguely described or actually have an empty description. For example: -------------- # oc explain specialresources.spec KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 RESOURCE: spec <Object> DESCRIPTION: SpecialResourceSpec defines the desired state of SpecialResource FIELDS: chart <Object> -required- debug <boolean> dependencies <[]Object> driverContainer <Object> SpecialResourceDriverContainer defines the desired state of SpecialResource forceUpgrade <boolean> namespace <string> -required- nodeSelector <map[string]string> set <> -------------- * I'd expect the chart description to not be empty. Please explain what the chart is needed for and what it should contain. * It's not clear what debug changes, and where to see the additional debug info. Please add a description. * Please give a description for dependencies and provide examples of use cases that need it. * Explain what forceUpdate is. * What is set? What is its type and schema? ... there are many more examples of empty descriptions. If you try to figure out the stuff that's not described, by looking into the description of the nested objects - you also find lots of empty descriptions. Examples: * oc explain specialresources.spec.chart.repository.url (the description here should mention that url can also be a local files path) * oc explain specialresources.spec.chart.tags The rest of the fields are mostly a copy-paste of each other and are vague and general and not helpful. Examples: * oc explain specialresources.spec.driverContainer: "SpecialResourceDriverContainer defines the desired state of SpecialResource" * oc explain specialresources.spec.driverContainer.artifacts: "SpecialResourceArtifacts defines the observed state of SpecialResource" * oc explain specialresources.spec.driverContainer.source: "SpecialResourceSource defines the observed state of SpecialResource" ... and so on. Please explain each field and not just say "defines the observed state of SpecialResource", which doesn't really contribute anything to the understanding.
oc explain specialresources.spec KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 RESOURCE: spec <Object> DESCRIPTION: SpecialResourceSpec describes the desired state of the resource, such as the chart to be used and a selector on which nodes it should be installed. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status FIELDS: chart <Object> -required- Chart describes the Helm chart that needs to be installed. debug <boolean> Debug enables additional logging. dependencies <[]Object> Dependencies is a list of dependencies required by this SpecialReosurce. driverContainer <Object> DriverContainer is not used. forceUpgrade <boolean> ForceUpgrade is not used. namespace <string> -required- Namespace describes in which namespace the chart will be installed. nodeSelector <map[string]string> NodeSelector is used to determine on which nodes the software stack should be installed. set <> Set is a user-defined hierarchical value tree from where the chart takes its parameters. $ oc explain specialresources.spec.chart.tags KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 FIELD: tags <[]string> DESCRIPTION: Tags is a list of tags for this chart. oc explain specialresources.spec.driverContainer KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 RESOURCE: driverContainer <Object> DESCRIPTION: DriverContainer is not used. FIELDS: artifacts <Object> SpecialResourceArtifacts is not used. source <Object> SpecialResourceSource is not used. oc explain specialresources.spec.driverContainer.artifacts KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 RESOURCE: artifacts <Object> DESCRIPTION: SpecialResourceArtifacts is not used. FIELDS: claims <[]Object> hostPaths <[]Object> images <[]Object> oc explain specialresources.spec.driverContainer.source KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 RESOURCE: source <Object> DESCRIPTION: SpecialResourceSource is not used. FIELDS: git <Object> SpecialResourceGit is not used. ############################################ Above looks like ok, but this one, the BZ highlight [the description here should mention that url can also be a local files path], no such description in latest code. oc explain specialresources.spec.chart.repository.url KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 FIELD: url <string> DESCRIPTION: URL is the canonical URL of the Helm repository.
As discussed with Dev team, the following description is as expected. oc explain specialresources.spec.chart.repository.url KIND: SpecialResource VERSION: sro.openshift.io/v1beta1 FIELD: url <string> DESCRIPTION: URL is the canonical URL of the Helm repository.
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 (Moderate: OpenShift Container Platform 4.10.3 security update), 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/RHSA-2022:0056