Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve API documentation for CSV and PackageManifest #167

Closed
TheRealJon opened this issue Nov 1, 2021 · 2 comments · Fixed by #168
Closed

Improve API documentation for CSV and PackageManifest #167

TheRealJon opened this issue Nov 1, 2021 · 2 comments · Fixed by #168

Comments

@TheRealJon
Copy link
Contributor

TheRealJon commented Nov 1, 2021

The API documentaion for ClusterServiceVerion is incomplete for the following properties:

CSV properties:

.spec.customresourcedefinitions.owned[].resources[]
.spec.customresourcedefinitions.required[].resources[]
.spec.apiservicedefinitions.owned[].resources[]
.spec.apiservicedefinitions.required[].resources[]

These all share the same description:

APIResourceReference is a Kubernetes resource type used by a custom resource

I've searched through OpenShift, Kubernetes, and Operator Framework repos and documentation and cannot find any further reference to an APIResourceReference schema. The schema consists of three string-type properties: kind, name, and version. These properties have no description defined in the schema.

The resource[] properties above are currently only consumed by the web console in order to list related resources on operand details pages, but we recently had a bug opened where this API was being misused. Adding some descriptions might be helpful in preventing future bugs or confusion.

@TheRealJon
Copy link
Contributor Author

I am working on a PR for this.

TheRealJon added a commit to TheRealJon/api that referenced this issue Nov 2, 2021
Fixes operator-framework#167
Add descriptions for kind, name, and version properties of APIResourceReference schema.
TheRealJon added a commit to TheRealJon/api that referenced this issue Nov 2, 2021
Fixes operator-framework#167
Add descriptions for kind, name, and version properties of APIResourceReference schema.
@SudoBrendan
Copy link

SudoBrendan commented Jan 14, 2022

Hey, just wanted to add some color - found myself here after running operator-sdk generate bundle, and being prompted for some of these required fields, which have no docs. It'd be awesome if they were included here!

Some are a little obvious (maintainer), others, not so much (provider? urls?) having at least some kubectl explain docs on the CSV would be helpful to know what these fields are supposed to have and where they show up.

TheRealJon added a commit to TheRealJon/api that referenced this issue Jan 28, 2022
Fixes operator-framework#167
Add descriptions for kind, name, and version properties of APIResourceReference schema.
TheRealJon added a commit to TheRealJon/api that referenced this issue May 26, 2022
Fixes operator-framework#167
Add descriptions for kind, name, and version properties of APIResourceReference schema.
TheRealJon added a commit to TheRealJon/api that referenced this issue Mar 23, 2023
Fixes operator-framework#167
Add descriptions for kind, name, and version properties of APIResourceReference schema.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants