Bug 2031875
| Summary: | [RFE]: Provide online documentation for the SRO CRD (via oc explain) | ||
|---|---|---|---|
| Product: | OpenShift Container Platform | Reporter: | Udi Kalifon <ukalifon> |
| Component: | Special Resource Operator | Assignee: | Quentin Barrand <quba> |
| Status: | CLOSED ERRATA | QA Contact: | liqcui |
| Severity: | medium | Docs Contact: | |
| Priority: | medium | ||
| Version: | 4.9 | CC: | aos-bugs, quba |
| Target Milestone: | --- | ||
| Target Release: | 4.10.0 | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | Enhancement | |
| Doc Text: |
Feature:
Include description of SRO CRD fields in product docs
Reason:
Better explain how SRO works
Result:
Provide better user experience
|
Story Points: | --- |
| Clone Of: | Environment: | ||
| Last Closed: | 2022-03-12 04:39:26 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: | |||
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 |
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.