From 229cbd472dc9cc0e088861a56a0e966574782958 Mon Sep 17 00:00:00 2001 From: Jeff Lowdermilk Date: Tue, 7 Jul 2015 16:57:37 -0700 Subject: [PATCH] Update kubectl describe help to document prefix matching behavior --- docs/kubectl.md | 4 ++-- docs/kubectl_describe.md | 19 ++++++++++++++----- docs/man/man1/kubectl-describe.1 | 17 ++++++++++++++--- pkg/kubectl/cmd/describe.go | 30 ++++++++++++++++++++++-------- 4 files changed, 52 insertions(+), 18 deletions(-) diff --git a/docs/kubectl.md b/docs/kubectl.md index 4be9f0cb84..fdcc692c9f 100644 --- a/docs/kubectl.md +++ b/docs/kubectl.md @@ -49,7 +49,7 @@ kubectl * [kubectl config](kubectl_config.md) - config modifies kubeconfig files * [kubectl create](kubectl_create.md) - Create a resource by filename or stdin * [kubectl delete](kubectl_delete.md) - Delete a resource by filename, stdin, resource and name, or by resources and label selector. -* [kubectl describe](kubectl_describe.md) - Show details of a specific resource +* [kubectl describe](kubectl_describe.md) - Show details of a specific resource or group of resources * [kubectl exec](kubectl_exec.md) - Execute a command in a container. * [kubectl expose](kubectl_expose.md) - Take a replicated application and expose it as Kubernetes Service * [kubectl get](kubectl_get.md) - Display one or many resources @@ -66,6 +66,6 @@ kubectl * [kubectl stop](kubectl_stop.md) - Gracefully shut down a resource by name or filename. * [kubectl version](kubectl_version.md) - Print the client and server version information. -###### Auto generated by spf13/cobra at 2015-07-01 07:34:21.247298407 +0000 UTC +###### Auto generated by spf13/cobra at 2015-07-07 23:45:47.079572585 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/kubectl.md?pixel)]() diff --git a/docs/kubectl_describe.md b/docs/kubectl_describe.md index 3f3a8b3456..a054c01cb8 100644 --- a/docs/kubectl_describe.md +++ b/docs/kubectl_describe.md @@ -1,17 +1,22 @@ ## kubectl describe -Show details of a specific resource +Show details of a specific resource or group of resources ### Synopsis -Show details of a specific resource. +Show details of a specific resource or group of resources. This command joins many API calls together to form a detailed description of a -given resource. +given resource or group of resources. + +$ kubectl describe RESOURCE NAME_PREFIX + +will first check for an exact match on RESOURCE and NAME_PREFIX. If no such resource +exists, it will output details for every resource that has a name prefixed with NAME_PREFIX ``` -kubectl describe (RESOURCE NAME | RESOURCE/NAME) +kubectl describe (RESOURCE NAME_PREFIX | RESOURCE/NAME) ``` ### Examples @@ -25,6 +30,10 @@ $ kubectl describe pods/nginx // Describe pods by label name=myLabel $ kubectl describe po -l name=myLabel + +// Describe all pods managed by the 'frontend' replication controller (rc-created pods +// get the name of the rc as a prefix in the pod the name). +$ kubectl describe pods frontend ``` ### Options @@ -66,6 +75,6 @@ $ kubectl describe po -l name=myLabel ### SEE ALSO * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager -###### Auto generated by spf13/cobra at 2015-06-12 06:44:05.105790085 +0000 UTC +###### Auto generated by spf13/cobra at 2015-07-07 23:45:47.075376625 +0000 UTC [![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/kubectl_describe.md?pixel)]() diff --git a/docs/man/man1/kubectl-describe.1 b/docs/man/man1/kubectl-describe.1 index cfb438a691..766b6c87e3 100644 --- a/docs/man/man1/kubectl-describe.1 +++ b/docs/man/man1/kubectl-describe.1 @@ -3,7 +3,7 @@ .SH NAME .PP -kubectl describe \- Show details of a specific resource +kubectl describe \- Show details of a specific resource or group of resources .SH SYNOPSIS @@ -13,11 +13,18 @@ kubectl describe \- Show details of a specific resource .SH DESCRIPTION .PP -Show details of a specific resource. +Show details of a specific resource or group of resources. .PP This command joins many API calls together to form a detailed description of a -given resource. +given resource or group of resources. + +.PP +$ kubectl describe RESOURCE NAME\_PREFIX + +.PP +will first check for an exact match on RESOURCE and NAME\_PREFIX. If no such resource +exists, it will output details for every resource that has a name prefixed with NAME\_PREFIX .SH OPTIONS @@ -142,6 +149,10 @@ $ kubectl describe pods/nginx // Describe pods by label name=myLabel $ kubectl describe po \-l name=myLabel +// Describe all pods managed by the 'frontend' replication controller (rc\-created pods +// get the name of the rc as a prefix in the pod the name). +$ kubectl describe pods frontend + .fi .RE diff --git a/pkg/kubectl/cmd/describe.go b/pkg/kubectl/cmd/describe.go index 2307edd723..f5fd6c9f60 100644 --- a/pkg/kubectl/cmd/describe.go +++ b/pkg/kubectl/cmd/describe.go @@ -31,22 +31,36 @@ import ( "github.com/GoogleCloudPlatform/kubernetes/pkg/runtime" ) -func NewCmdDescribe(f *cmdutil.Factory, out io.Writer) *cobra.Command { - cmd := &cobra.Command{ - Use: "describe (RESOURCE NAME | RESOURCE/NAME)", - Short: "Show details of a specific resource", - Long: `Show details of a specific resource. +const ( + describe_long = `Show details of a specific resource or group of resources. This command joins many API calls together to form a detailed description of a -given resource.`, - Example: `// Describe a node +given resource or group of resources. + +$ kubectl describe RESOURCE NAME_PREFIX + +will first check for an exact match on RESOURCE and NAME_PREFIX. If no such resource +exists, it will output details for every resource that has a name prefixed with NAME_PREFIX` + describe_example = `// Describe a node $ kubectl describe nodes kubernetes-minion-emt8.c.myproject.internal // Describe a pod $ kubectl describe pods/nginx // Describe pods by label name=myLabel -$ kubectl describe po -l name=myLabel`, +$ kubectl describe po -l name=myLabel + +// Describe all pods managed by the 'frontend' replication controller (rc-created pods +// get the name of the rc as a prefix in the pod the name). +$ kubectl describe pods frontend` +) + +func NewCmdDescribe(f *cmdutil.Factory, out io.Writer) *cobra.Command { + cmd := &cobra.Command{ + Use: "describe (RESOURCE NAME_PREFIX | RESOURCE/NAME)", + Short: "Show details of a specific resource or group of resources", + Long: describe_long, + Example: describe_example, Run: func(cmd *cobra.Command, args []string) { err := RunDescribe(f, out, cmd, args) cmdutil.CheckErr(err)