kubernetes
kubectl CLI should more consistently and concisely convey discovery
Moved from kubernetes/kubernetes#53387
Now that discovery is complete as an API, and CRD and aggregation are in heavy use, we need to make some minor tweaks to kubectl to improve discoverability of apis from clients.
Common issues:
- I want to see all resources that I might be able to create
- I want to be able to disambiguate conflicting resources
- I want to distinguish between cluster scoped and non-cluster scoped resources
- I want an equivalent to the
allshortcut that is actually all resource types that are namespace scoped
We want to orient brand new users to kubectl from a config perspective into:
- what can i
get - if i want to create a config resource, how do i specify it (
explain, which could be better) - i want to know what a resource is for
Some thoughts:
kubectl api-versionsis too simple, and needs to be better or removed- There should be a command that makes it easy to see the list of:
- all namespace scoped resources
- all cluster scoped resources
- the shortcuts of those resources
- what the resource does (potentially as a
-voption) - a brief discussion of how to deal with version conflicting names (pod v1beta.special.bar and pod v1)
- potentially what versions exist for those resources
explainandgetshould suggest that command when you specify something it doesn't recognize- We could piggyback this into get except discovery resources aren't quite a format API, so it would be somewhat hacky. However, get and describe already work so a few special cases aren't terrible (we did reserve APIGroupList v1 and APIGroup v1)
Hypothetical
$ kubectl get apigroups
NAME VERSIONS RESOURCES
autoscaling v1 horizontalpodautoscaler
$ kubectl describe apis
API Groups
autoscaling:
v1:
Resources: horizontalpodautoscaler
v2:
...
$ kubectl get apis
NAME VERSIONS RESOURCES
autoscaling v1 horizontalpodautoscaler
$ kubectl apis
GROUP VERSIONS RESOURCES
autoscaling v1 horizontalpodautoscaler
$ kubectl apis --group=autoscaling --version=v1
GROUP VERSIONS RESOURCES
autoscaling v1 horizontalpodautoscaler
$ kubectl explain
error: You must select a resource type to explain:
Nicely formatted two column table - one for namespace scoped and one for cluster scoped
It should be easy to select all namespaced resources from a command - we should add:
$ kubectl get all-namespaced --all
$ kubectl describe all-namespaced
$ kubectl delete all-resources --all
We can't change all because of backwards compatibility (anyone with kubectl delete all --all would be broken if we change what all covers), but also because it's deliberately short to remain easy to type for end users.
This is really annoying now that I'm dealing with more and more groups.
Explain should tell me what group something is I need to be able to see info on a given resource type in the exact form that I would specify it to get (the so called "resource-arg" form resource.version.group). I.e. "I got an error that told me this resource doesn't do what I think - how do i find out more about it". Error messages need to do a better job of returning a discoverable type (for 2) - right now we're doing either the struct print for many of them or the GroupVersionResource.String() method which is not an accepted form. I think this is the #1 issue dealing with extensions - no place to go to find them, no way to know how to use them in kubectl, no way to check that the ones I care about are registered.
Use cases:
When I as a user get errors about mismatches between what I typed and what is available on the server, I need to discover what is on the server As a user, I expect to get canonical representations of resources so as to avoid having to explain how to transform the representations myself
We already have kubectl api-versions and there was a PR to add kubectl api-resources. But when I think about the operations that these commands perform, and that I may want to describe the objects they return in more detail, I think it makes more sense to expose these as resources under kubectl get and describe. That also makes it easier to suggest options:
$ kubectl get
usage: This command expects a resource type and an optional name of a resource to locate. Use `kubectl get apiresources` to see all valid resource types.
Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close.
Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale
Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close.
Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle stale
Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
If this issue is safe to close now please do so with /close.
Send feedback to sig-testing, kubernetes/test-infra and/or fejta. /lifecycle rotten /remove-lifecycle stale
