Merge pull request #10894 from jlowdermilk/describe-docs

Update kubectl describe help to document prefix matching behavior

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)]()

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)]()

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
 

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 {
+const (
-	cmd := &cobra.Command{
+	describe_long = `Show details of a specific resource or group of resources.
-		Use:   "describe (RESOURCE NAME | RESOURCE/NAME)",
-		Short: "Show details of a specific resource",
-		Long: `Show details of a specific resource.
 
 This command joins many API calls together to form a detailed description of a
-given resource.`,
+given resource or group of resources.
-		Example: `// Describe a node
+
+$ 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)