Clarify kubectl shell autocompletion documentation (#13060)

* Clarify kubectl autocompletion documentation (#12405) * Clarify kubectl autocompletion documentation (#12405) Remove comments. * Clarify kubectl autocompletion documentation Fix according to review. * Clarify kubectl autocompletion documentation Use selectable tabs. * Fix note callouts in various sections * Clarify kubectl autocompletion documentation Change wording of intro paragraph.
2019-03-15 17:45:10 +01:00
parent 8585fbb1ab
commit 783ee875d0
1 changed files with 110 additions and 40 deletions
@@ -110,9 +110,7 @@ If you are on Windows and using [Powershell Gallery](https://www.powershellgalle
    install-kubectl.ps1 [-DownloadLocation <path>]
    ```
    
-    {{< note >}}
-    If you do not specify a `DownloadLocation`, `kubectl` will be installed in the user's temp Directory.
-    {{< /note >}}
+    {{< note >}}If you do not specify a `DownloadLocation`, `kubectl` will be installed in the user's temp Directory.{{< /note >}}
    
    The installer creates `$HOME/.kube` and instructs it to create a config file

@@ -122,9 +120,7 @@ If you are on Windows and using [Powershell Gallery](https://www.powershellgalle
    kubectl version
    ```

-    {{< note >}}
-    Updating the installation is performed by rerunning the two commands listed in step 1.
-    {{< /note >}}
+    {{< note >}}Updating the installation is performed by rerunning the two commands listed in step 1.{{< /note >}}

 ## Install on Windows using Chocolatey or scoop

@@ -170,9 +166,7 @@ To install kubectl on Windows you can use either [Chocolatey](https://chocolatey
    New-Item config -type file
    ```
    
-    {{< note >}}
-    Edit the config file with a text editor of your choice, such as Notepad.
-    {{< /note >}}
+    {{< note >}}Edit the config file with a text editor of your choice, such as Notepad.{{< /note >}}

 ## Download as part of the Google Cloud SDK

@@ -295,63 +289,139 @@ kubectl cluster-info dump

 ## Enabling shell autocompletion

-kubectl includes autocompletion support, which can save a lot of typing!
+kubectl provides autocompletion support for Bash and Zsh, which can save you a lot of typing!

-The completion script itself is generated by kubectl, so you typically just need to invoke it from your profile.
+Below are the procedures to set up autocompletion for Bash (including the difference between Linux and macOS) and Zsh.

-Common examples are provided here. For more details, consult `kubectl completion -h`.
+{{< tabs name="kubectl_autocompletion" >}}

-### On Linux, using bash
-On CentOS Linux, you may need to install the bash-completion package which is not installed by default.
+{{% tab name="Bash on Linux" %}}
+
+### Introduction
+
+The kubectl completion script for Bash can be generated with the command `kubectl completion bash`. Sourcing the completion script in your shell enables kubectl autocompletion.
+
+However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
+
+### Install bash-completion
+
+bash-completion is provided by many package managers (see [here](https://github.com/scop/bash-completion#installation)). You can install it with `apt-get install bash-completion` or `yum install bash-completion`, etc.
+
+The above commands create `/usr/share/bash-completion/bash_completion`, which is the main script of bash-completion. Depending on your package manager, you have to manually source this file in your `~/.bashrc` file.
+
+To find out, reload your shell and run `type _init_completion`. If the command succeeds, you're already set, otherwise add the following to your `~/.bashrc` file:

 ```shell
-yum install bash-completion -y
+source /usr/share/bash-completion/bash_completion
 ```

-To add kubectl autocompletion to your current shell, run `source <(kubectl completion bash)`.
+Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.

-To add kubectl autocompletion to your profile, so it is automatically loaded in future shells run:
+### Enable kubectl autocompletion
+
+You now need to ensure that the kubectl completion script gets sourced in all your shell sessions. There are two ways in which you can do this:
+
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(kubectl completion bash)' >>~/.bashrc
+    ```
+
+- Add the completion script to the `/etc/bash_completion.d` directory:
+
+    ```shell
+    kubectl completion bash >/etc/bash_completion.d/kubectl
+    ```
+
+{{< note >}}
+bash-completion sources all completion scripts in `/etc/bash_completion.d`.
+{{< /note >}}
+
+Both approaches are equivalent. After reloading your shell, kubectl autocompletion should be working.
+
+{{% /tab %}}
+
+
+{{% tab name="Bash on macOS" %}}
+
+{{< warning>}}
+macOS includes Bash 3.2 by default. The kubectl completion script requires Bash 4.1+ and doesn't work with Bash 3.2. A possible way around this is to install a newer version of Bash on macOS (see instructions [here](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The below instructions only work if you are using Bash 4.1+.
+{{< /warning >}}
+
+### Introduction
+
+The kubectl completion script for Bash can be generated with the command `kubectl completion bash`. Sourcing the completion script in your shell enables kubectl autocompletion.
+
+However, the completion script depends on [**bash-completion**](https://github.com/scop/bash-completion), which means that you have to install this software first (you can test if you have bash-completion already installed by running `type _init_completion`).
+
+### Install bash-completion
+
+You can install bash-completion with Homebrew:

 ```shell
-echo "source <(kubectl completion bash)" >> ~/.bashrc
-```
-
-### On macOS, using bash
-On macOS, you will need to install bash-completion support via [Homebrew](https://brew.sh/) first:
-
-```shell
-## If running Bash 3.2 included with macOS
-brew install bash-completion
-## or, if running Bash 4.1+
 brew install bash-completion@2
 ```

-Follow the "caveats" section of brew's output to add the appropriate bash completion path to your local .bashrc.
+{{< note >}}
+The `@2` stands for bash-completion 2, which is required by the kubectl completion script (it doesn't work with bash-completion 1). In turn, bash-completion 2 requires Bash 4.1+, that's why you needed to upgrade Bash.
+{{< /note >}}

-If you installed kubectl using the [Homebrew instructions](#install-with-homebrew-on-macos) then kubectl completion should start working immediately.
-
-If you have installed kubectl manually, you need to add kubectl autocompletion to the bash-completion:
+As stated in the output of `brew install` ("Caveats" section), add the following lines to your `~/.bashrc` or `~/.bash_profile` file:

 ```shell
-kubectl completion bash > $(brew --prefix)/etc/bash_completion.d/kubectl
+export BASH_COMPLETION_COMPAT_DIR=/usr/local/etc/bash_completion.d
+[[ -r /usr/local/etc/profile.d/bash_completion.sh ]] && . /usr/local/etc/profile.d/bash_completion.sh
 ```

-The Homebrew project is independent from Kubernetes, so the bash-completion packages are not guaranteed to work.
+Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.

-### Using Zsh
-If you are using zsh edit the ~/.zshrc file and add the following code to enable kubectl autocompletion:
+### Enable kubectl autocompletion
+
+You now need to ensure that the kubectl completion script gets sourced in all your shell sessions. There are multiple ways in which you can do this:
+
+- Source the completion script in your `~/.bashrc` file:
+
+    ```shell
+    echo 'source <(kubectl completion bash)' >>~/.bashrc
+
+    ```
+
+- Add the completion script to `/usr/local/etc/bash_completion.d`:
+
+    ```shell
+    kubectl completion bash >/usr/local/etc/bash_completion.d/kubectl
+    ```
+
+- If you installed kubectl with Homebrew (as explained [here](#install-with-homebrew-on-macos)), then the completion script was automatically installed to `/usr/local/etc/bash_completion.d/kubectl`. In that case, you don't need to do anything.
+
+{{< note >}}
+bash-completion (if installed with Homebrew) sources all the completion scripts in the directory that is set in the `BASH_COMPLETION_COMPAT_DIR` environment variable.
+{{< /note >}}
+
+All approaches are equivalent. After reloading your shell, kubectl autocompletion should be working.
+{{% /tab %}}
+
+{{% tab name="Zsh" %}}
+
+The kubectl completion script for Zsh can be generated with the command `kubectl completion zsh`. Sourcing the completion script in your shell enables kubectl autocompletion.
+
+To do so in all your shell sessions, add the following to your `~/.zshrc` file:

 ```shell
-if [ $commands[kubectl] ]; then
-  source <(kubectl completion zsh)
-fi
+source <(kubectl completion zsh)
 ```

-Or when using [Oh-My-Zsh](http://ohmyz.sh/), edit the ~/.zshrc file and update the `plugins=` line to include the kubectl plugin.
+After reloading your shell, kubectl autocompletion should be working.
+
+If you get an error like `complete:13: command not found: compdef`, then add the following to the beginning of your `~/.zshrc` file:

 ```shell
-plugins=(kubectl)
+autoload -Uz compinit
+compinit
 ```
+{{% /tab %}}
+{{< /tabs >}}
+
 {{% /capture %}}

 {{% capture whatsnext %}}