search

argoproj / argo-workflows

Workflow Engine for Kubernetes
https://argo-workflows.readthedocs.io/
Apache License 2.0
14.96k stars 3.19k forks source link

Add descriptions to `kubectl explain` #8190

Open kevin-hanselman opened 2 years ago

kevin-hanselman commented 2 years ago

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 commented 2 years ago

This is like man for CRDs?

kevin-hanselman commented 2 years ago

This is like man for CRDs?

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

danielhelfand commented 2 years ago

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 commented 1 year ago

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 commented 1 year ago

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 😉