Getting started guides overhaul.

docs/user-guide/prereqs.md

@@ -3,9 +3,24 @@ assignees:
 - bgrant0607
 - mikedanese
 title: Installing and Setting up kubectl
+redirect_from:
+- "/docs/getting-started-guides/kubectl/"
+- "/docs/getting-started-guides/kubectl.html"
 ---
 
-To deploy and manage applications on Kubernetes, you'll use the Kubernetes command-line tool, [kubectl](/docs/user-guide/kubectl/). It lets you inspect your cluster resources, create, delete, and update components, and much more. You will use it to look at your new cluster and bring up example apps.
+To deploy and manage applications on Kubernetes, you'll use the
+Kubernetes command-line tool, [kubectl](/docs/user-guide/kubectl/). It
+lets you inspect your cluster resources, create, delete, and update
+components, and much more. You will use it to look at your new cluster
+and bring up example apps.
+
+You should use a version of kubectl that is at least as new as your
+server.  `kubectl version` will print the server and client versions.
+Using the same version of kubectl as your server naturally works;
+using a newer kubectl than your server also works; but if you use an
+older kubectl with a newer server you may see odd validation errors.
+
+Here are a few methods to install kubectl.
 
 ## Install kubectl Binary Via curl
 
@@ -65,6 +80,31 @@ export PATH=<path/to/kubernetes-directory>/platforms/darwin/amd64:$PATH
 export PATH=<path/to/kubernetes-directory>/platforms/linux/amd64:$PATH
 ```
 
+## Download as part of the Google Cloud SDK
+
+kubectl can be installed as part of the Google Cloud SDK:
+
+First install the [Google Cloud SDK](https://cloud.google.com/sdk/).
+
+After Google Cloud SDK installs, run the following command to install `kubectl`:
+
+```shell
+gcloud components install kubectl
+```
+
+Do check that the version is sufficiently up-to-date using `kubectl version`.
+
+## Install with brew
+
+If you are on MacOS and using brew, you can install with:
+
+```shell
+brew install kubectl
+```
+
+The homebrew project is independent from kubernetes, so do check that the version is
+sufficiently up-to-date using `kubectl version`.
+
 ## Configuring kubectl
 
 In order for kubectl to find and access the Kubernetes cluster, it needs a [kubeconfig file](/docs/user-guide/kubeconfig-file), which is created automatically when creating a cluster using kube-up.sh (see the [getting started guides](/docs/getting-started-guides/) for more about creating clusters). If you need access to a cluster you didn't create, see the [Sharing Cluster Access document](/docs/user-guide/sharing-clusters).
@@ -80,6 +120,49 @@ $ kubectl cluster-info
 
 If you see a url response, you are ready to go.
 
+## Enabling shell autocompletion
+
+kubectl includes autocompletion support, which can save a lot of typing!
+
+The completion script itself is generated by kubectl, so you typically just need to invoke it from your profile.
+
+Common examples are provided here, but for more details please consult `kubectl completion -h`
+
+### On Linux, using bash
+
+To add it to your current shell: `source <(kubectl completion bash)`
+
+To add kubectl autocompletion to your profile (so it is automatically loaded in future shells):
+
+```shell
+echo "source <(kubectl completion bash)" >> ~/.bashrc
+```
+
+### On MacOS, using bash
+
+On MacOS, you will need to install the bash-completion support first:
+
+```shell
+brew install bash-completion
+```
+
+To add it to your current shell:
+
+```shell
+source $(brew --prefix)/etc/bash_completion
+source <(kubectl completion bash)
+```
+
+To add kubectl autocompletion to your profile (so it is automatically loaded in future shells):
+
+```shell
+echo "source $(brew --prefix)/etc/bash_completion" >> ~/.bash_profile
+echo "source <(kubectl completion bash)" >> ~/.bash_profile
+```
+
+Please note that this only appears to work currently if you install using `brew install kubectl`,
+and not if you downloaded kubectl directly.
+
 ## What's next?
 
 [Learn how to launch and expose your application.](/docs/user-guide/quick-start)