hack,install: Enable CRD description generation #10750
Conversation
Signed-off-by: timflannagan <[email protected]>
|
Can we disable description for gwparams? |
| @@ -38,7 +38,7 @@ API_INPUT_DIRS_SPACE="${API_INPUT_DIRS_SPACE%,}" # drop trailing space | |||
| API_INPUT_DIRS_COMMA="${API_INPUT_DIRS_COMMA%,}" # drop trailing comma | |||
|
|
|||
| go run k8s.io/code-generator/cmd/register-gen --output-file zz_generated.register.go ${API_INPUT_DIRS_SPACE} | |||
| go run sigs.k8s.io/controller-tools/cmd/controller-gen crd:maxDescLen=0 object rbac:roleName=kgateway paths="${APIS_PKG}/api/${VERSION}" \ | |||
| go run sigs.k8s.io/controller-tools/cmd/controller-gen crd:maxDescLen=1000 object rbac:roleName=kgateway paths="${APIS_PKG}/api/${VERSION}" \ | |||
There was a problem hiding this comment.
historically we've excluded descriptions from the crds because customers have run into size limits applying the crds. if we are using a max length, can we make it smaller? (1000 characters per description still seems pretty long)
(but thinking out loud, if we are truncating some descriptions, then maybe the descriptions won't be that useful after all? users will still need to consult the docs)
do you know if kubectl explain is widely relied upon?
There was a problem hiding this comment.
We can reduce the max length to something more reasonable. re:truncating the description: even if the description is truncated and there's some missing information, it's still a better UX imo being able to surface this information via kubectl explain than forcing users to context switch and always go to the docs to fix API documentation.
This isn't possible with kubebuilder/controller-gen today. There's no per-file, per-field, etc. knob those tools expose that allow us to selectively trim descriptions from certain APIs. If we don't want to enable descriptions, then we have a couple of options:
|
Description
Enable the kubebuilder CRD field description functionality. Previously, this was set to
zero, which disabled description field documentation for the rendered CRD manifests.
Without this, users that rely on
kubectl explain ...have a degraded UX as they cannoteasily determine the API surface behavior.
Note, I kept a maximum for the CRD description length. This was primarily to prevent
any scenario where the embedded fields within the GWParams API would exceed the
etcd size limit.
Checklist: