Generated CRDs do not populate top-level OpenAPI schema descriptions
- Dominant language
- Go
- Stars
- 519
- Forks
- 612
- Avg merge
- 18h 35m
- Merged PRs (30d)
- 23
Description
**Describe the feature request**
While investigating `kubectl explain`, I noticed that all generated Istio CRDs have an empty top-level description.
For example:
````
kubectl explain virtualservice
GROUP: networking.istio.io
KIND: VirtualService
VERSION: v1
DESCRIPTION:
.
.
````
even though `explain virtualservice.spec` , correctly shows the generated description:
````
kubectl explain virtualservice.spec
GROUP: networking.istio.io
KIND: VirtualService
VERSION: v1
FIELD: spec
DESCRIPTION:
Configuration affecting label/content routing, sni routing, etc. See more
details at:
https://istio.io/docs/reference/config/networking/virtual-service.html
````
Looking at the generated OpenAPI:
`kubectl get --raw /openapi/v3/apis/networking.istio.io/v1 \
| jq '.components.schemas["io.istio.networking.v1.VirtualService"].description'`
returns `null`.
I traced this to the CRD generator https://github.com/istio/tools/blob/master/cmd/protoc-gen-crd/openapiGenerator.go#L340-L341 . A straightforward implementation is to propagate `spec.Description` to the root schema, which makes `kubectl explain` display a description. However, this results in the same description appearing for both the resource and its spec.
Before preparing a PR, I'd like to understand the intended design:
- **Should the root CRD schema reuse the protobuf message description?**
- **Or should the generator support a separate resource-level description (for example via a new +cue-gen annotation)?**
**Affected product area (please put an X in all that apply)**
[ ] Configuration Infrastructure
[X] Docs
[ ] Installation
[ ] Networking
[ ] Performance and Scalability
[ ] Policies and Telemetry
[ ] Security
[ ] Test and Release
[X] User Experience
**Additional context:**
This enhancement would improve the usability of generated Istio CRDs by populating top-level OpenAPI schema descriptions. Currently, `kubectl explain ` shows an empty `DESCRIPTION` for generated CRDs, even though `field` and `spec` descriptions are available. **Adding meaningful root descriptions would make Istio APIs easier to discover and understand directly from the CLI, without changing runtime behavior.**
Contributor guide
Research direction
Start in cmd/protoc-gen-crd/openapiGenerator.go around lines 340-341 and compare the generated root schema with the spec description shown by kubectl explain. Check the OpenAPI v3 schema for VirtualService and verify the intended resource-level description design. Done means generated CRDs expose a meaningful top-level description without obscuring the existing spec description.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, openapi
- Domain
- api, developer-experience, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 40/100