Add descriptions to kubectl explain

[kevin-hanselman]

Summary

kubectl explain is an invaluable tool for quickly exploring Kubernetes resources. CRDs can provide descriptions that kubectl explain can pick up. For example, see Knative.

Use Cases

Instead of going to the Argo Workflows webpage, I'd like to run, for example, kubectl explain workflow for guidance on building a Workflow resource.

---

Message from the maintainers:

Love this enhancement proposal? Give it a 👍. We prioritise the proposals with the most 👍.

[alexec]

This is like man for CRDs?

[kevin-hanselman]

This is like man for CRDs?

@alexec it's like man for all Kubernetes resources -- built-ins and CRDs alike.

[danielhelfand]

This may be a bit challenging for resources like Workflows, which will require a schema for this feature to work. Due to the size of the CRDs with the schema, this will cause errors like below when deploying the CRD with descriptions:

for: "manifests/base/crds/full/argoproj.io_workflows.yaml": Request entity too large: limit is 3145728

It seems schemas were intentionally left out due to this issue.

However, it still may be possible for smaller CRDs to support kubectl explain.

[drew-viles]

Even if a description can't be put in, it would be nice to know what lies under spec.

For example, if something is a map[string]string or a bool etc. Having nothing isn't really useful for development as it means people need to know the fields they want already before they go to the docs for an example of it rather than being able to deduce how to lay something out from the explain command

An example of this would be when I was creating a CronWorkflow. I presumed base on the example here that the .spec.workflowSpec.templates.dag.tasks.template.name would be the name of a WorkflowTemplate, however this isn't really clear. I only know by hunting through examples in the GitHub repo that you would have to use spec.workflowSpec.workflowTemplateName.name to reference a workflow template.

I feel there is room for improvement here and if I can find the time to help with this I will. Either getting the explain command to work on a more descriptive level or improving any docs where possible.

[drew-viles]

I've located this - it's something for now I guess.
https://argoproj.github.io/argo-workflows/fields/#workflow

Just not ideal when working on a cli 😉