diff --git a/docs/user-guide/kubectl-overview.md b/docs/user-guide/kubectl-overview.md
index 1c1aff053fe..aeb55110988 100644
--- a/docs/user-guide/kubectl-overview.md
+++ b/docs/user-guide/kubectl-overview.md
@@ -33,160 +33,282 @@ Documentation for other releases can be found at
# kubectl overview
-**Table of Contents**
+Use this overview of the `kubectl` command line interface to help you start running commands against Kubernetes clusters. This overview quickly covers `kubectl` syntax, describes the command operations, and provides common examples. For details about each command, including all the supported flags and subcommands, see the [kubectl](kubectl/kubectl.md) reference documentation.
+
+**Table of contents:**
+
- [kubectl overview](#kubectl-overview)
- - [Overview](#overview)
- - [Common Operations](#common-operations)
- - [Kubectl Operations](#kubectl-operations)
- - [Resource Types](#resource-types)
+ - [Syntax](#syntax)
+ - [Operations](#operations)
+ - [Resource types](#resource-types)
+ - [Output options](#output-options)
+ - [Formatting output](#formatting-output)
+ - [Syntax](#syntax)
+ - [Example](#example)
+ - [Custom columns](#custom-columns)
+ - [Examples](#examples)
+ - [Sorting list objects](#sorting-list-objects)
+ - [Syntax](#syntax)
+ - [Example](#example)
+ - [Examples: Common operations](#examples-common-operations)
+ - [Next steps](#next-steps)
-This overview is intended for anyone who wants to use `kubectl` command line tool to interact with Kubernetes cluster. Please remember that it is built for quick started with `kubectl`; for complete and detailed information, please refer to [kubectl](kubectl/kubectl.md).
+
-TODO: auto-generate this file to stay up with `kubectl` changes. Please see [#14177](https://github.com/kubernetes/kubernetes/pull/14177).
+TODO: Auto-generate this file to ensure it's always in sync with any `kubectl` changes, see [#14177](http://pr.k8s.io/14177).
-## Overview
+## Syntax
-`kubectl` controls the Kubernetes cluster manager. The synopsis is:
+Use the following syntax to run `kubectl` commands from your terminal window:
```
kubectl [command] [TYPE] [NAME] [flags]
```
-This specifies:
+where `command`, `TYPE`, `NAME`, and `flags` are:
-- `command` is a certain operation performed on a given resource(s), such as `create`, `get`, `describe`, `delete` etc.
-- `TYPE` is the type of resource(s). Both singular and plural forms are accepted. For example, `node(s)`, `namespace(s)`, `pod(s)`, `replicationcontroller(s)`, `service(s)` etc.
-- `NAME` is the name of resource(s). `TYPE NAME` can be specified as `TYPE name1 name2` or `TYPE/name1 TYPE/name2`. `TYPE NAME` can also be specified by one or more file arguments: `-f file1 -f file2 ...`, [use YAML rather than JSON](config-best-practices.md) since YAML tends to be more user-friendly for config.
-- `flags` are used to provide more control information when running a command. For example, you can use `-s` or `--server` to specify the address and port of the Kubernetes API server. Command line flags override their corresponding default values and environment variables. [Use short flags sparingly, only for the most frequently used options](../devel/kubectl-conventions.md).
+* `command`: Specifies the operation that you want to perform on one or more resources, for example `create`, `get`, `describe`, `delete`.
+* `TYPE`: Specifies the [resource type](#resource-types). Resource types are case-sensitive and you can specify the singular, plural, or abbreviated forms. For example, the following commands produce the same output:
-Please use `kubectl help [command]` for detailed information about a command.
+ ```
+ $ kubectl get pod pod1
+ $ kubectl get pods pod1
+ $ kubectl get po pod1
+ ```
-Please refer to [kubectl](kubectl/kubectl.md) for a complete list of available commands and flags.
+* `NAME`: Specifies the name of the resource. Names are case-sensitive. If the name is omitted, details for all resources are displayed, for example `$ kubectl get pods`.
-## Common Operations
+ When performing an operation on multiple resources, you can specify each resource by type and name or specify one or more files:
+ * To specify resources by type and name:
+ * To group resources if they are all the same type: `TYPE1 name1 name2 name<#>`
+ Example: `$ kubectl get pod example-pod1 example-pod2`
+ * To specify multiple resource types individually: `TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>`
+ Example: `$ kubectl get pod/example-pod1 replicationcontroller/example-rc1`
+ * To specify resources with one or more files: `-f file1 -f file2 -f file<#>`
+ [Use YAML rather than JSON](config-best-practices.md) since YAML tends to be more user-friendly, especially for configuration files.
+ Example: `$ kubectl get pod -f ./pod.yaml`
+* `flags`: Specifies optional flags. For example, you can use the `-s` or `--server` flags to specify the address and port of the Kubernetes API server.
+**Important**: Flags that you specify from the command line override default values and any corresponding environment variables.
-For explanation, here I gave some mostly often used `kubectl` command examples. Please replace sample names with actual values if you would like to try these commands.
+If you need help, just run `kubectl help` from the terminal window.
-1. `kubectl create` - Create a resource by filename or stdin
+## Operations
- // Create a service using the data in example-service.yaml.
+The following table includes short descriptions and the general syntax for all of the `kubectl` operations:
+
+Operation | Syntax | Description
+-------------------- | -------------------- | --------------------
+`annotate` | `kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]` | Add or update the annotations of one or more resources.
+`api-versions` | `kubectl api-versions [flags]` | List the API versions that are available.
+`apply` | `kubectl apply -f FILENAME [flags]`| Apply a configuration change to a resource from a file or stdin.
+`attach` | `kubectl attach POD -c CONTAINER [-i] [-t] [flags]` | Attach to a running container either to view the output stream or interact with the container (stdin).
+`autoscale` | `autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags]` | Automatically scale the set of pods that are managed by a replication controller.
+`cluster-info` | `kubectl cluster-info [flags]` | Display endpoint information about the master and services in the cluster.
+`config` | `kubectl config SUBCOMMAND [flags]` | Modifies kubeconfig files. See the individual subcommands for details.
+`create` | `kubectl create -f FILENAME [flags]` | Create one or more resources from a file or stdin.
+`delete` | `kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags]` | Delete resources either from a file, stdin, or specifying label selectors, names, resource selectors, or resources.
+`describe` | `kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags]` | Display the detailed state of one or more resources.
+`edit` | `kubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags]` | Edit and update the definition of one or more resources on the server by using the default editor.
+`exec` | `kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]` | Execute a command against a container in a pod.
+`expose` | `kubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [----external-ip=external-ip-of-service] [--type=type] [flags]` | Expose a replication controller, service, or pod as a new Kubernetes service.
+`get` | `kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags]` | List one or more resources.
+`label` | `kubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]` | Add or update the labels of one or more resources.
+`logs` | `kubectl logs POD [-c CONTAINER] [--follow] [flags]` | Print the logs for a container in a pod.
+`patch` | `kubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags]` | Update one or more fields of a resource by using the strategic merge patch process.
+`port-forward` | `kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]` | Forward one or more local ports to a pod.
+`proxy` | `kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]` | Run a proxy to the Kubernetes API server.
+`replace` | `kubectl replace -f FILENAME` | Replace a resource from a file or stdin.
+`rolling-update` | `kubectl rolling-update OLD_CONTROLLER_NAME ([NEW_CONTROLLER_NAME] --image=NEW_CONTAINER_IMAGE | -f NEW_CONTROLLER_SPEC) [flags]` | Perform a rolling update by gradually replacing the specified replication controller and its pods.
+`run` | `kubectl run NAME --image=image [--env="key=value"] [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json] [flags]` | Run a specified image on the cluster.
+`scale` | `kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags]` | Update the size of the specified replication controller.
+`stop` | `kubectl stop` | Deprecated: Instead, see `kubectl delete`.
+`version` | `kubectl version [--client] [flags]` | Display the Kubernetes version running on the client and server.
+
+Remember: For more about command operations, see the [kubectl](kubectl/kubectl.md) reference documentation.
+
+## Resource types
+
+The following table includes a list of all the supported resource types and their abbreviated aliases:
+
+Resource type | Abbreviated alias
+-------------------- | --------------------
+`componentstatuses` | `cs`
+`events` | `ev`
+`endpoints` | `ep`
+`horizontalpodautoscalers` | `hpa`
+`limitranges` | `limits`
+`nodes` | `no`
+`namespaces` | `ns`
+`pods` | `po`
+`persistentvolumes` | `pv`
+`persistentvolumeclaims` | `pvc`
+`resourcequotas` | `quota`
+`replicationcontrollers` | `rc`
+`secrets` |
+`serviceaccounts` |
+`services` | `svc`
+`ingress` | `ing`
+
+## Output options
+
+Use the following sections for information about how you can format or sort the output of certain commands. For details about which commands support the various output options, see the [kubectl](kubectl/kubectl.md) reference documentation.
+
+### Formatting output
+
+The default output format for all `kubectl` commands is the human readable plain-text format. To output details to your terminal window in a specific format, you can add either the `-o` or `-output` flags to a supported `kubectl` command.
+
+#### Syntax
+
+```
+kubectl [command] [TYPE] [NAME] -o=
+```
+
+Depending on the `kubectl` operation, the following output formats are supported:
+
+Output format | Description
+--------------| -----------
+`-o=custom-columns=` | Print a table using a comma separated list of [custom columns](#custom-columns).
+`-o=custom-columns-file=` | Print a table using the [custom columns](#custom-columns) template in the `` file.
+`-o=json` | Output a JSON formatted API object.
+`-o=jsonpath=` | Print the fields defined in a [jsonpath](jsonpath.md) expression.
+`-o=jsonpath-file=` | Print the fields defined by the [jsonpath](jsonpath.md) expression in the `` file.
+`-o=name` | Print only the resource name and nothing else.
+`-o=wide` | Output in the plain-text format with any additional information. For pods, the node name is included.
+`-o=yaml` | Output a YAML formatted API object.
+
+##### Example
+
+In this example, the following command outputs the details for a single pod as a YAML formatted object:
+
+`$ kubectl get pod web-pod-13je7 -o=yaml`
+
+Remember: See the [kubectl](kubectl/kubectl.md) reference documentation for details about which output format is supported by each command.
+
+#### Custom columns
+
+To define custom columns and output only the details that you want into a table, you can use the `custom-columns` option. You can choose to define the custom columns inline or use a template file: `-o=custom-columns=` or `-o=custom-columns-file=`.
+
+##### Examples
+
+ * Inline:
+
+ ```console
+ $ kubectl get pods -o=custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion
+ ```
+
+ * Template file:
+
+ ```console
+ $ kubectl get pods -o=custom-columns-file=template.txt
+ ```
+
+ where the `template.txt` file contains:
+
+ ```
+ NAME RSRC
+ metadata.name metadata.resourceVersion
+ ```
+
+The result of running either command is:
+
+```console
+NAME RSRC
+submit-queue 610995
+```
+
+### Sorting list objects
+
+To output objects to a sorted list in your terminal window, you can add the `--sort-by` flag to a supported `kubectl` command. Sort your objects by specifying any numeric or string field with the `--sort-by` flag. To specify a field, use a [jsonpath](jsonpath.md) expression.
+
+#### Syntax
+
+```
+kubectl [command] [TYPE] [NAME] --sort-by=
+```
+
+##### Example
+
+To print a list of pods sorted by name, you run:
+
+`$ kubectl get pods --sort-by=.metadata.name`
+
+## Examples: Common operations
+
+Use the following set of examples to help you familiarize yourself with running the commonly used `kubectl` operations:
+
+ * `kubectl create` - Create a resource from a file or stdin.
+
+ // Create a service using the definition in example-service.yaml.
$ kubectl create -f example-service.yaml
- // Create a replication controller using the data in example-controller.yaml.
+ // Create a replication controller using the definition in example-controller.yaml.
$ kubectl create -f example-controller.yaml
- // Create objects whose definitions are in a directory. This looks for config objects in all .yaml, .yml, and .json files in and passes them to create.
+ // Create the objects that are defined in any .yaml, .yml, or .json file within the directory.
$ kubectl create -f
-2. `kubectl get` - Display one or many resources
+ * `kubectl get` - List one or more resources.
- // List all pods in ps output format.
+ // List all pods in plain-text output format.
$ kubectl get pods
- // List all pods in ps output format with more information (such as node name).
+ // List all pods in plain-text output format and includes additional information (such as node name).
$ kubectl get pods -o wide
- // List a single replication controller with specified name in ps output format. You can use the alias 'rc' instead of 'replicationcontroller'.
+ // List the replication controller with the specified name in plain-text output format. Tip: You can shorten and replace the 'replicationcontroller' resource type with the alias 'rc'.
$ kubectl get replicationcontroller
- // List all replication controllers and services together in ps output format.
+ // List all replication controllers and services together in plain-text output format.
$ kubectl get rc,services
-3. `kubectl describe` - Show details of a specific resource or group of resources
+ * `kubectl describe` - Display detailed state of one or more resources.
- // Describe a node
+ // Display the details of the node with name .
$ kubectl describe nodes
- // Describe a pod
+ // Display the details of the pod with name .
$ kubectl describe pods/
- // Describe all pods managed by the replication controller
- // (rc-created pods get the name of the rc as a prefix in the pod the name).
+ // Display the details of all the pods that are managed by the replication controller named .
+ // Remember: Any pods that are created by the replication controller get prefixed with the name of the replication controller.
$ kubectl describe pods
-4. `kubectl delete` - Delete resources by filenames, stdin, resources and names, or by resources and label selector
+ * `kubectl delete` - Delete resources either from a file, stdin, or specifying label selectors, names, resource selectors, or resources.
- // Delete a pod using the type and name specified in pod.yaml.
+ // Delete a pod using the type and name specified in the pod.yaml file.
$ kubectl delete -f pod.yaml
- // Delete pods and services with label name=.
+ // Delete all the pods and services that have the label name=.
$ kubectl delete pods,services -l name=
- // Delete all pods
+ // Delete all pods.
$ kubectl delete pods --all
-5. `kubectl exec` - Execute a command in a container
+ * `kubectl exec` - Execute a command against a container in a pod.
- // Get output from running 'date' from pod , using the first container by default.
+ // Get output from running 'date' from pod . By default, output is from the first container.
$ kubectl exec date
- // Get output from running 'date' in from pod .
+ // Get output from running 'date' in container of pod .
$ kubectl exec -c date
- // Get an interactive tty and run /bin/bash from pod , using the first container by default.
+ // Get an interactive TTY and run /bin/bash from pod . By default, output is from the first container.
$ kubectl exec -ti /bin/bash
-6. `kubectl logs` - Print the logs for a container in a pod.
+ * `kubectl logs` - Print the logs for a container in a pod.
- // Returns snapshot of logs from pod .
+ // Return a snapshot of the logs from pod .
$ kubectl logs
- // Starts streaming of logs from pod , it is something like 'tail -f'.
+ // Start streaming the logs from pod . This is similiar to the 'tail -f' Linux command.
$ kubectl logs -f
-## Kubectl Operations
-The following table describes all `kubectl` operations and their general synopsis:
+## Next steps
-Operation | Synopsis | Description
--------------------- | -------------------- | --------------------
-annotate | `kubectl annotate [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]` | Update the annotations on a resource
-api-versions | `kubectl api-versions` | Print available API versions
-attach | `kubectl attach POD -c CONTAINER` | Attach to a running container
-cluster-info | `kubectl cluster-info` | Display cluster info
-config | `kubectl config SUBCOMMAND` | Modifies kubeconfig files
-create | `kubectl create -f FILENAME` | Create a resource by filename or stdin
-delete | `kubectl delete ([-f FILENAME] | TYPE [(NAME | -l label | --all)])` | Delete resources by filenames, stdin, resources and names, or by resources and label selector
-describe | `kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | -l label] | TYPE/NAME)` | Show details of a specific resource or group of resources
-edit | `kubectl edit (RESOURCE/NAME | -f FILENAME)` | Edit a resource on the server
-exec | `kubectl exec POD [-c CONTAINER] -- COMMAND [args...]` | Execute a command in a container
-expose | `kubectl expose (-f FILENAME | TYPE NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [----external-ip=external-ip-of-service] [--type=type]` | Take a replication controller, service or pod and expose it as a new Kubernetes Service
-get | `kubectl get [(-o|--output=)json|yaml|wide|go-template=...|go-template-file=...|jsonpath=...|jsonpath-file=...] (TYPE [NAME | -l label] | TYPE/NAME ...) [flags]` | Display one or many resources
-label | `kubectl label [--overwrite] (-f FILENAME | TYPE NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--resource-version=version]` | Update the labels on a resource
-logs | `kubectl logs [-f] [-p] POD [-c CONTAINER]` | Print the logs for a container in a pod
-namespace | `kubectl namespace [namespace]` | SUPERSEDED: Set and view the current Kubernetes namespace
-patch | `kubectl patch (-f FILENAME | TYPE NAME) -p PATCH` | Update field(s) of a resource by stdin
-port-forward | `kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N]` | Forward one or more local ports to a pod
-proxy | `kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix]` | Run a proxy to the Kubernetes API server
-replace | `kubectl replace -f FILENAME` | Replace a resource by filename or stdin
-rolling-update | `kubectl rolling-update OLD_CONTROLLER_NAME ([NEW_CONTROLLER_NAME] --image=NEW_CONTAINER_IMAGE | -f NEW_CONTROLLER_SPEC)` | Perform a rolling update of the given ReplicationController
-run | `kubectl run NAME --image=image [--env="key=value"] [--port=port] [--replicas=replicas] [--dry-run=bool] [--overrides=inline-json]` | Run a particular image on the cluster
-scale | `kubectl scale [--resource-version=version] [--current-replicas=count] --replicas=COUNT (-f FILENAME | TYPE NAME)` | Set a new size for a Replication Controller
-stop | `kubectl stop (-f FILENAME | TYPE (NAME | -l label | --all))` | Deprecated: Gracefully shut down a resource by name or filename
-version | `kubectl version` | Print the client and server version information
+Start using the [kubectl](kubectl/kubectl.md) commands.
-## Resource Types
-
-The `kubectl` supports the following resource types, and their abbreviated aliases:
-
-Resource Type | Abbreviated Alias
--------------------- | --------------------
-componentstatuses | cs
-events | ev
-endpoints | ep
-horizontalpodautoscalers | hpa
-limitranges | limits
-nodes | no
-namespaces | ns
-pods | po
-persistentvolumes | pv
-persistentvolumeclaims | pvc
-resourcequotas | quota
-replicationcontrollers | rc
-daemonsets | ds
-services | svc
-ingress | ing
[]()