Merge pull request #39540 from pwittrock/kubectldocs

Automatic merge from submit-queue (batch tested with PRs 39673, 39536, 39617, 39540, 39686)

Improve kubectl help with examples.

```release-note
NONE
```

pkg/kubectl/cmd/apiversions.go

@@ -25,15 +25,24 @@ import (
 	"github.com/spf13/cobra"
 
 	metav1 "k8s.io/kubernetes/pkg/apis/meta/v1"
+	"k8s.io/kubernetes/pkg/kubectl/cmd/templates"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
 )
 
+var (
+	apiversions_example = templates.Examples(`
+		# Print the supported API versions
+		kubectl api-versions`)
+)
+
 func NewCmdApiVersions(f cmdutil.Factory, out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use: "api-versions",
 		// apiversions is deprecated.
 		Aliases: []string{"apiversions"},
 		Short:   "Print the supported API versions on the server, in the form of \"group/version\"",
+		Long:    "Print the supported API versions on the server, in the form of \"group/version\"",
+		Example: apiversions_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunApiVersions(f, out)
 			cmdutil.CheckErr(err)

pkg/kubectl/cmd/certificates.go

@@ -33,6 +33,7 @@ func NewCmdCertificate(f cmdutil.Factory, out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "certificate SUBCOMMAND",
 		Short: "Modify certificate resources.",
+		Long:  "Modify certificate resources.",
 		Run: func(cmd *cobra.Command, args []string) {
 			cmd.Help()
 		},

pkg/kubectl/cmd/clusterinfo.go

@@ -31,10 +31,16 @@ import (
 	"github.com/spf13/cobra"
 )
 
-var longDescr = templates.LongDesc(`
+var (
+	longDescr = templates.LongDesc(`
   Display addresses of the master and services with label kubernetes.io/cluster-service=true
   To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.`)
 
+	clusterinfo_example = templates.Examples(`
+		# Print the address of the master and cluster services
+		kubectl cluster-info`)
+)
+
 func NewCmdClusterInfo(f cmdutil.Factory, out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
 		Use: "cluster-info",
@@ -42,6 +48,7 @@ func NewCmdClusterInfo(f cmdutil.Factory, out io.Writer) *cobra.Command {
 		Aliases: []string{"clusterinfo"},
 		Short:   "Display cluster info",
 		Long:    longDescr,
+		Example: clusterinfo_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunClusterInfo(f, out, cmd)
 			cmdutil.CheckErr(err)

pkg/kubectl/cmd/completion.go

@@ -44,26 +44,39 @@ const boilerPlate = `
 
 var (
 	completion_long = templates.LongDesc(`
-		Output shell completion code for the given shell (bash or zsh).
+		Output shell completion code for the specified shell (bash or zsh).
+		The shell code must be evalutated to provide interactive
+		completion of kubectl commands.  This can be done by sourcing it from
+		the .bash_profile.
 
-		This command prints shell code which must be evaluation to provide interactive
-		completion of kubectl commands.
-
-		    $ source <(kubectl completion bash)
-
-		will load the kubectl completion code for bash. Note that this depends on the
-		bash-completion framework. It must be sourced before sourcing the kubectl
-		completion, e.g. on the Mac:
+		Note: this requires the bash-completion framework, which is not installed
+		by default on Mac.  This can be installed by using homebrew:
 
 		    $ brew install bash-completion
+
+		Once installed, bash_completion must be evaluated.  This can be done by adding the
+		following line to the .bash_profile
+
 		    $ source $(brew --prefix)/etc/bash_completion
-		    $ source <(kubectl completion bash)
 
-		If you use zsh[1], the following will load kubectl zsh completion:
+		Note for zsh users: [1] zsh completions are only supported in versions of zsh >= 5.2`)
 
-		    $ source <(kubectl completion zsh)
+	completion_example = templates.Examples(`
+		# Install bash completion on a Mac using homebrew
+		brew install bash-completion
+		printf "\n# Bash completion support\nsource $(brew --prefix)/etc/bash_completion\n" >> $HOME/.bash_profile
+		source $HOME/.bash_profile
 
-		[1] zsh completions are only supported in versions of zsh >= 5.2`)
+		# Load the kubectl completion code for bash into the current shell
+		source <(kubectl completion bash)
+
+		# Write bash completion code to a file and source if from .bash_profile
+		kubectl completion bash > ~/.kube/completion.bash.inc
+		printf "\n# Kubectl shell completion\nsource '$HOME/.kube/completion.bash.inc'\n" >> $HOME/.bash_profile
+		source $HOME/.bash_profile
+
+		# Load the kubectl completion code for zsh[1] into the current shell
+		source <(kubectl completion zsh)`)
 )
 
 var (
@@ -80,9 +93,10 @@ func NewCmdCompletion(f cmdutil.Factory, out io.Writer) *cobra.Command {
 	}
 
 	cmd := &cobra.Command{
-		Use:   "completion SHELL",
-		Short: "Output shell completion code for the given shell (bash or zsh)",
-		Long:  completion_long,
+		Use:     "completion SHELL",
+		Short:   "Output shell completion code for the specified shell (bash or zsh)",
+		Long:    completion_long,
+		Example: completion_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunCompletion(out, cmd, args)
 			cmdutil.CheckErr(err)

pkg/kubectl/cmd/config/delete_cluster.go

@@ -22,13 +22,22 @@ import (
 
 	"github.com/spf13/cobra"
 	"k8s.io/kubernetes/pkg/client/unversioned/clientcmd"
+	"k8s.io/kubernetes/pkg/kubectl/cmd/templates"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
 )
 
+var (
+	delete_cluster_example = templates.Examples(`
+		# Delete the minikube cluster
+		kubectl config delete-cluster minikube`)
+)
+
 func NewCmdConfigDeleteCluster(out io.Writer, configAccess clientcmd.ConfigAccess) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "delete-cluster NAME",
-		Short: "Delete the specified cluster from the kubeconfig",
+		Use:     "delete-cluster NAME",
+		Short:   "Delete the specified cluster from the kubeconfig",
+		Long:    "Delete the specified cluster from the kubeconfig",
+		Example: delete_cluster_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := runDeleteCluster(out, configAccess, cmd)
 			cmdutil.CheckErr(err)

pkg/kubectl/cmd/config/delete_context.go

@@ -22,13 +22,22 @@ import (
 
 	"github.com/spf13/cobra"
 	"k8s.io/kubernetes/pkg/client/unversioned/clientcmd"
+	"k8s.io/kubernetes/pkg/kubectl/cmd/templates"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
 )
 
+var (
+	delete_context_example = templates.Examples(`
+		# Delete the context for the minikube cluster
+		kubectl config delete-context minikube`)
+)
+
 func NewCmdConfigDeleteContext(out io.Writer, configAccess clientcmd.ConfigAccess) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "delete-context NAME",
-		Short: "Delete the specified context from the kubeconfig",
+		Use:     "delete-context NAME",
+		Short:   "Delete the specified context from the kubeconfig",
+		Long:    "Delete the specified context from the kubeconfig",
+		Example: delete_context_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := runDeleteContext(out, configAccess, cmd)
 			cmdutil.CheckErr(err)

pkg/kubectl/cmd/config/get_clusters.go

@@ -22,15 +22,24 @@ import (
 
 	"github.com/spf13/cobra"
 	"k8s.io/kubernetes/pkg/client/unversioned/clientcmd"
+	"k8s.io/kubernetes/pkg/kubectl/cmd/templates"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
 )
 
+var (
+	get_clusters_example = templates.Examples(`
+		# List the clusters kubectl knows about
+		kubectl config get-clusters`)
+)
+
 // NewCmdConfigGetClusters creates a command object for the "get-clusters" action, which
 // lists all clusters defined in the kubeconfig.
 func NewCmdConfigGetClusters(out io.Writer, configAccess clientcmd.ConfigAccess) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "get-clusters",
-		Short: "Display clusters defined in the kubeconfig",
+		Use:     "get-clusters",
+		Short:   "Display clusters defined in the kubeconfig",
+		Long:    "Display clusters defined in the kubeconfig.",
+		Example: get_clusters_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := runGetClusters(out, configAccess)
 			cmdutil.CheckErr(err)

pkg/kubectl/cmd/config/use_context.go

@@ -25,9 +25,16 @@ import (
 
 	"k8s.io/kubernetes/pkg/client/unversioned/clientcmd"
 	clientcmdapi "k8s.io/kubernetes/pkg/client/unversioned/clientcmd/api"
+	"k8s.io/kubernetes/pkg/kubectl/cmd/templates"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
 )
 
+var (
+	use_context_example = templates.Examples(`
+		# Use the context for the minikube cluster
+		kubectl config use-context minikube`)
+)
+
 type useContextOptions struct {
 	configAccess clientcmd.ConfigAccess
 	contextName  string
@@ -37,9 +44,10 @@ func NewCmdConfigUseContext(out io.Writer, configAccess clientcmd.ConfigAccess)
 	options := &useContextOptions{configAccess: configAccess}
 
 	cmd := &cobra.Command{
-		Use:   "use-context CONTEXT_NAME",
-		Short: "Sets the current-context in a kubeconfig file",
-		Long:  `Sets the current-context in a kubeconfig file`,
+		Use:     "use-context CONTEXT_NAME",
+		Short:   "Sets the current-context in a kubeconfig file",
+		Long:    `Sets the current-context in a kubeconfig file`,
+		Example: use_context_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			if !options.complete(cmd) {
 				return

pkg/kubectl/cmd/options.go

@@ -24,10 +24,19 @@ import (
 	"github.com/spf13/cobra"
 )
 
+var (
+	options_example = templates.Examples(`
+		# Print flags inherited by all commands
+		kubectl options`)
+)
+
 // NewCmdOptions implements the options command
 func NewCmdOptions(out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use: "options",
+		Use:     "options",
+		Short:   "Print the list of flags inherited by all commands",
+		Long:    "Print the list of flags inherited by all commands",
+		Example: options_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			cmd.Usage()
 		},

pkg/kubectl/cmd/version.go

@@ -22,14 +22,23 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"k8s.io/kubernetes/pkg/kubectl/cmd/templates"
 	cmdutil "k8s.io/kubernetes/pkg/kubectl/cmd/util"
 	"k8s.io/kubernetes/pkg/version"
 )
 
+var (
+	version_example = templates.Examples(`
+		# Print the client and server versions for the current context
+		kubectl version`)
+)
+
 func NewCmdVersion(f cmdutil.Factory, out io.Writer) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "version",
-		Short: "Print the client and server version information",
+		Use:     "version",
+		Short:   "Print the client and server version information",
+		Long:    "Print the client and server version information for the current context",
+		Example: version_example,
 		Run: func(cmd *cobra.Command, args []string) {
 			err := RunVersion(f, out, cmd)
 			cmdutil.CheckErr(err)