A new command to read types' description from Swagger - kubectl explain #12677

andronat · 2015-08-13T18:44:26Z

This is a simple kubectl tool that parses the swagger schema and returns useful information for the various resources and their fields that we have.

Here you can see an example output:

# kubectl explain pods
DESCRIPTION:
Pod is a collection of containers that can run on a host. This resource is created by clients and scheduled onto hosts.

FIELDS:
   kind <string>
     Kind is a string value representing the REST resource this object
     represents. Servers may infer this from the endpoint the client submits
     requests to. Cannot be updated. In CamelCase. More info:
     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#types-kinds

   metadata <Object>
     Standard object's metadata. More info:
     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#metadata

   spec <Object>
     Specification of the desired behavior of the pod. More info:
     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status

   status   <Object>
     Most recently observed status of the pod. This data may not be up to date.
     Populated by the system. Read-only. More info:
     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#spec-and-status

   apiVersion   <string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     http://releases.k8s.io/HEAD/docs/devel/api-conventions.md#resources

and has this interface:

# kubectl help explain
Documentation of resources.

Possible resource types include: pods (po), services (svc),
replicationcontrollers (rc), nodes (no), events (ev), componentstatuses (cs),
limitranges (limits), persistentvolumes (pv), persistentvolumeclaims (pvc),
resourcequotas (quota), namespaces (ns) or endpoints (ep).

Usage:
  kubectl explain RESOURCE [flags]

Examples:
# Get the documentation of the resource and its fields
$ kubectl explain pods

# Get the documentation of a specific field of a resource
$ kubectl explain pods.spec.containers

Flags:
      --recursive[=false]: Print the fields of fields (Currently only 1 level deep)

/cc @ghodss

k8s-bot · 2015-08-13T19:09:56Z

GCE e2e build/test passed for commit 574663305ceb07207e3583ac0e8a294b8f4223f1.

k8s-bot · 2015-08-13T19:14:39Z

GCE e2e build/test passed for commit fdef9f45ac103cd36641c3210a53e33160a008cb.

k8s-bot · 2015-08-13T19:14:44Z

GCE e2e build/test passed for commit b66283478f6d4fbc572180525c9a3cde3b53fce1.

k8s-bot · 2015-08-13T21:42:19Z

GCE e2e build/test passed for commit 2d64923001cca38089da9de40ccde5616080e593.

k8s-bot · 2015-08-15T12:31:31Z

GCE e2e build/test passed for commit 96663b6dba3b421c62f34a3947b9210c98ed85e1.

andronat · 2015-08-18T16:43:45Z

Lots of changes. Added a dot notation feature for better exploration. Thanks @ghodss for the nice ideas and suggestions :)

k8s-bot · 2015-08-18T17:02:50Z

GCE e2e build/test passed for commit a80b32db433a55fc503c38234701123f9f43c571.

k8s-bot · 2015-08-18T19:49:54Z

GCE e2e build/test failed for commit 104ddbe35f01870362ef0346df525b93d805a68e.

bgrant0607 · 2015-08-18T22:58:13Z

cc @kubernetes/kubectl

ghodss · 2015-08-18T23:00:32Z

This implements #3060.

deads2k · 2015-08-19T12:23:00Z

@pweil- This ought to help the detection issue you wrote in openshift.

k8s-bot · 2015-08-19T12:44:29Z

GCE e2e build/test passed for commit c866a9fac8993aabe906c2f5413278beabbc3f98.

jwforres · 2015-08-19T14:08:50Z

cc @fabianofranz

bgrant0607 · 2015-08-21T18:58:57Z

cc @RichieEscarez

0xmichalis · 2015-08-24T08:52:31Z

pkg/kubectl/cmd/swagger_doc.go

+	for _, model := range args {
+		if cmdutil.GetFlagBool(cmd, "search") {
+			kubectl.SearchForModel(model, apiV, out, client)
+		} else {


Make GetModelDescription and SearchForModel return errors instead of os.Exit so they can be used directly in return statements (will make this else clause redundant).

Great, thanks! I am on it.

k8s-github-robot · 2015-08-27T22:44:35Z

Labelling this PR as size/XL

nikhiljindal · 2015-08-28T22:03:25Z

Thanks a lot @andronat. This is exciting stuff!
I recommend reading https://github.com/kubernetes/kubernetes/blob/master/docs/devel/kubectl-conventions.md for our general kubectl conventions.

For ex the current proposed kubectl doc Pod doesnt follow our kubectl VERB NOUN convention.
We can instead have something like kubectl describe kind Pod for returning the model for Pod kind.
kubectl describe kind can return a list of all kinds (Pod, ReplicationController, Node, etc).
kubectl describe operation /api/v1/namespaces/x/pods GET can describe the GET operation at that path.
kubectl describe operation /api/v1/namespaces/x/pods can return a list of all valid methods for that path.
I am sure @bgrant0607 and @smarterclayton will have better suggestions.

nikhiljindal · 2015-08-28T22:15:53Z

docs/user-guide/kubectl/kubectl.md

@@ -86,6 +86,7 @@ kubectl
 * [kubectl create](kubectl_create.md)	 - Create a resource by filename or stdin
 * [kubectl delete](kubectl_delete.md)	 - Delete resources by filenames, stdin, resources and names, or by resources and label selector.
 * [kubectl describe](kubectl_describe.md)	 - Show details of a specific resource or group of resources
+* [kubectl doc](kubectl_doc.md)	 - Print model's documentation through swagger's API.


I think we can do without specifying "swagger" here. Many kubectl users might not know what swagger is and dont need to.
If we decide to change this to kubectl get kind, then we can say "Show the fields of a given kind"

k8s-bot · 2015-09-22T12:43:03Z

GCE e2e build/test passed for commit 344b2c6ea66e43ca898311a50410c04c9d98376c.

k8s-github-robot · 2015-09-22T12:57:48Z

Labelling this PR as size/XL

k8s-bot · 2015-09-23T07:07:35Z

GCE e2e build/test passed for commit 344b2c6ea66e43ca898311a50410c04c9d98376c.

janetkuo · 2015-09-24T23:48:27Z

@andronat thanks for the update. I think the map needs to be updated since operations like kubectl explain pod, kubectl explain replicationcontroller (singularized resource name) don't work. For recursive display if we decide to go one level deep we should say so in the flag description (or perhaps we can use some other flags like --level=2, --depth=3; it's up to you).

andronat · 2015-09-25T11:10:06Z

@janetkuo yea, I fixed the problems

k8s-bot · 2015-09-25T11:36:20Z

GCE e2e build/test passed for commit bff4e1046c7b29eb4d9737e816cca8821da2ca2c.

janetkuo · 2015-09-25T17:53:16Z

@andronat thanks, this LGTM now. Please update the description of this PR (the first comment) to reflect the latest change. @bgrant0607 may have more comments.

bgrant0607 · 2015-09-25T20:35:12Z

Thanks for all the work on this. We can improve it more later. Please rebase and squash.

k8s-github-robot · 2015-09-26T11:52:02Z

Labelling this PR as size/L

k8s-bot · 2015-09-26T12:00:32Z

Unit, integration and GCE e2e test build/test passed for commit e8b9dde.

andronat · 2015-09-26T12:06:51Z

I updated the description and squashed the commits.

k8s-github-robot · 2015-09-29T05:10:56Z

The author of this PR is not in the whitelist for merge, can one of the admins add the 'ok-to-merge' label?

A new command to read types' description from Swagger - kubectl explain

googlebot added the cla: yes label Aug 13, 2015

andronat changed the title ~~A new command to read types' description from Swagger~~ WIP: A new command to read types' description from Swagger Aug 13, 2015

bgrant0607 added the area/kubectl label Aug 18, 2015

ghodss mentioned this pull request Aug 18, 2015

Add support to kubectl to describe API types and operations #3060

Closed

k8s-github-robot assigned bgrant0607 Aug 21, 2015

0xmichalis reviewed Aug 24, 2015
View reviewed changes

bgrant0607 assigned nikhiljindal and unassigned bgrant0607 Aug 26, 2015

k8s-github-robot added the size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Aug 27, 2015

nikhiljindal reviewed Aug 28, 2015
View reviewed changes

k8s-github-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Sep 22, 2015

andronat closed this Sep 22, 2015

andronat reopened this Sep 22, 2015

andronat closed this Sep 23, 2015

andronat reopened this Sep 23, 2015

janetkuo changed the title ~~A new command to read types' description from Swagger~~ A new command to read types' description from Swagger - kubectl explain Sep 25, 2015

andronat added 2 commits September 26, 2015 14:25

client can return swagger schema

495433f

new kubectl explain command

e8b9dde

k8s-github-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Sep 26, 2015

janetkuo added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 26, 2015

k8s-github-robot added the needs-ok-to-merge label Sep 29, 2015

thockin added ok-to-merge and removed needs-ok-to-merge labels Sep 29, 2015

brendandburns added a commit that referenced this pull request Sep 30, 2015

Merge pull request #12677 from andronat/kubectl_doc_cmd

e827934

A new command to read types' description from Swagger - kubectl explain

brendandburns merged commit e827934 into kubernetes:master Sep 30, 2015

andronat deleted the kubectl_doc_cmd branch September 30, 2015 16:25

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

A new command to read types' description from Swagger - kubectl explain #12677

A new command to read types' description from Swagger - kubectl explain #12677

andronat commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 15, 2015

andronat commented Aug 18, 2015

k8s-bot commented Aug 18, 2015

k8s-bot commented Aug 18, 2015

bgrant0607 commented Aug 18, 2015

ghodss commented Aug 18, 2015

deads2k commented Aug 19, 2015

k8s-bot commented Aug 19, 2015

jwforres commented Aug 19, 2015

bgrant0607 commented Aug 21, 2015

0xmichalis Aug 24, 2015

andronat Aug 24, 2015

k8s-github-robot commented Aug 27, 2015

nikhiljindal commented Aug 28, 2015

nikhiljindal Aug 28, 2015

andronat Aug 31, 2015

k8s-bot commented Sep 22, 2015

k8s-github-robot commented Sep 22, 2015

k8s-bot commented Sep 23, 2015

janetkuo commented Sep 24, 2015

andronat commented Sep 25, 2015

k8s-bot commented Sep 25, 2015

janetkuo commented Sep 25, 2015

bgrant0607 commented Sep 25, 2015

k8s-github-robot commented Sep 26, 2015

k8s-bot commented Sep 26, 2015

andronat commented Sep 26, 2015

k8s-github-robot commented Sep 29, 2015

A new command to read types' description from Swagger - kubectl explain #12677

A new command to read types' description from Swagger - kubectl explain #12677

Conversation

andronat commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 13, 2015

k8s-bot commented Aug 15, 2015

andronat commented Aug 18, 2015

k8s-bot commented Aug 18, 2015

k8s-bot commented Aug 18, 2015

bgrant0607 commented Aug 18, 2015

ghodss commented Aug 18, 2015

deads2k commented Aug 19, 2015

k8s-bot commented Aug 19, 2015

jwforres commented Aug 19, 2015

bgrant0607 commented Aug 21, 2015

0xmichalis Aug 24, 2015

Choose a reason for hiding this comment

andronat Aug 24, 2015

Choose a reason for hiding this comment

k8s-github-robot commented Aug 27, 2015

nikhiljindal commented Aug 28, 2015

nikhiljindal Aug 28, 2015

Choose a reason for hiding this comment

andronat Aug 31, 2015

Choose a reason for hiding this comment

k8s-bot commented Sep 22, 2015

k8s-github-robot commented Sep 22, 2015

k8s-bot commented Sep 23, 2015

janetkuo commented Sep 24, 2015

andronat commented Sep 25, 2015

k8s-bot commented Sep 25, 2015

janetkuo commented Sep 25, 2015

bgrant0607 commented Sep 25, 2015

k8s-github-robot commented Sep 26, 2015

k8s-bot commented Sep 26, 2015

andronat commented Sep 26, 2015

k8s-github-robot commented Sep 29, 2015