istio / istio/api

Generated CRDs do not populate top-level OpenAPI schema descriptions

Open
#3,742 0 comments 0 reactions 0 assignees View on GitHub
area/user experience kind/docs kind/enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.