From 783ee875d0b05cc0bb28503f113c147750505db5 Mon Sep 17 00:00:00 2001 From: Daniel Weibel Date: Fri, 15 Mar 2019 17:45:10 +0100 Subject: [PATCH] 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. --- .../en/docs/tasks/tools/install-kubectl.md | 150 +++++++++++++----- 1 file changed, 110 insertions(+), 40 deletions(-) diff --git a/content/en/docs/tasks/tools/install-kubectl.md b/content/en/docs/tasks/tools/install-kubectl.md index 28b46d9178..c9f1d892f6 100644 --- a/content/en/docs/tasks/tools/install-kubectl.md +++ b/content/en/docs/tasks/tools/install-kubectl.md @@ -110,9 +110,7 @@ If you are on Windows and using [Powershell Gallery](https://www.powershellgalle install-kubectl.ps1 [-DownloadLocation ] ``` - {{< 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 %}}