Daniel Weibel
783ee875d0
* 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.
431 lines
14 KiB
Markdown
431 lines
14 KiB
Markdown
---
|
|
reviewers:
|
|
- bgrant0607
|
|
- mikedanese
|
|
title: Install and Set Up kubectl
|
|
content_template: templates/task
|
|
weight: 10
|
|
card:
|
|
name: tasks
|
|
weight: 20
|
|
title: Install kubectl
|
|
---
|
|
|
|
{{% capture overview %}}
|
|
Use the Kubernetes command-line tool, [kubectl](/docs/user-guide/kubectl/), to deploy and manage applications on Kubernetes. Using kubectl, you can inspect cluster resources; create, delete, and update components; look at your new cluster; and bring up example apps.
|
|
{{% /capture %}}
|
|
|
|
{{% capture prerequisites %}}
|
|
You must use a kubectl version that is within one minor version difference of your cluster. For example, a v1.2 client should work with v1.1, v1.2, and v1.3 master. Using the latest version of kubectl helps avoid unforeseen issues.
|
|
{{% /capture %}}
|
|
|
|
|
|
{{% capture steps %}}
|
|
|
|
## Install kubectl
|
|
|
|
Here are a few methods to install kubectl.
|
|
|
|
## Install kubectl binary using native package management
|
|
|
|
{{< tabs name="kubectl_install" >}}
|
|
{{< tab name="Ubuntu, Debian or HypriotOS" codelang="bash" >}}
|
|
sudo apt-get update && sudo apt-get install -y apt-transport-https
|
|
curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
|
|
echo "deb https://apt.kubernetes.io/ kubernetes-xenial main" | sudo tee -a /etc/apt/sources.list.d/kubernetes.list
|
|
sudo apt-get update
|
|
sudo apt-get install -y kubectl
|
|
{{< /tab >}}
|
|
{{< tab name="CentOS, RHEL or Fedora" codelang="bash" >}}cat <<EOF > /etc/yum.repos.d/kubernetes.repo
|
|
[kubernetes]
|
|
name=Kubernetes
|
|
baseurl=https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64
|
|
enabled=1
|
|
gpgcheck=1
|
|
repo_gpgcheck=1
|
|
gpgkey=https://packages.cloud.google.com/yum/doc/yum-key.gpg https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
|
|
EOF
|
|
yum install -y kubectl
|
|
{{< /tab >}}
|
|
{{< /tabs >}}
|
|
|
|
|
|
## Install with snap on Ubuntu
|
|
|
|
If you are on Ubuntu or one of other Linux distributions that support [snap](https://snapcraft.io/docs/core/install) package manager, kubectl is available as a [snap](https://snapcraft.io/) application.
|
|
|
|
1. Switch to the snap user and run the installation command:
|
|
|
|
```
|
|
sudo snap install kubectl --classic
|
|
```
|
|
|
|
2. Test to ensure the version you installed is sufficiently up-to-date:
|
|
|
|
```
|
|
kubectl version
|
|
```
|
|
|
|
## Install with Homebrew on macOS
|
|
|
|
If you are on macOS and using [Homebrew](https://brew.sh/) package manager, you can install kubectl with Homebrew.
|
|
|
|
1. Run the installation command:
|
|
|
|
```
|
|
brew install kubernetes-cli
|
|
```
|
|
|
|
2. Test to ensure the version you installed is sufficiently up-to-date:
|
|
|
|
```
|
|
kubectl version
|
|
```
|
|
|
|
## Install with Macports on macOS
|
|
|
|
If you are on macOS and using [Macports](https://macports.org/) package manager, you can install kubectl with Macports.
|
|
|
|
1. Run the installation command:
|
|
|
|
```
|
|
sudo port selfupdate
|
|
sudo port install kubectl
|
|
```
|
|
|
|
2. Test to ensure the version you installed is sufficiently up-to-date:
|
|
|
|
```
|
|
kubectl version
|
|
```
|
|
|
|
## Install with Powershell from PSGallery
|
|
|
|
If you are on Windows and using [Powershell Gallery](https://www.powershellgallery.com/) package manager, you can install and update kubectl with Powershell.
|
|
|
|
1. Run the installation commands (making sure to specify a `DownloadLocation`):
|
|
|
|
```
|
|
Install-Script -Name install-kubectl -Scope CurrentUser -Force
|
|
install-kubectl.ps1 [-DownloadLocation <path>]
|
|
```
|
|
|
|
{{< 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
|
|
|
|
2. Test to ensure the version you installed is sufficiently up-to-date:
|
|
|
|
```
|
|
kubectl version
|
|
```
|
|
|
|
{{< note >}}Updating the installation is performed by rerunning the two commands listed in step 1.{{< /note >}}
|
|
|
|
## Install on Windows using Chocolatey or scoop
|
|
|
|
To install kubectl on Windows you can use either [Chocolatey](https://chocolatey.org) package manager or [scoop](https://scoop.sh) command-line installer.
|
|
{{< tabs name="kubectl_win_install" >}}
|
|
{{% tab name="choco" %}}
|
|
|
|
choco install kubernetes-cli
|
|
|
|
{{% /tab %}}
|
|
{{% tab name="scoop" %}}
|
|
|
|
scoop install kubectl
|
|
|
|
{{% /tab %}}
|
|
{{< /tabs >}}
|
|
2. Test to ensure the version you installed is sufficiently up-to-date:
|
|
|
|
```
|
|
kubectl version
|
|
```
|
|
|
|
3. Navigate to your home directory:
|
|
|
|
```
|
|
cd %USERPROFILE%
|
|
```
|
|
4. Create the `.kube` directory:
|
|
|
|
```
|
|
mkdir .kube
|
|
```
|
|
|
|
5. Change to the `.kube` directory you just created:
|
|
|
|
```
|
|
cd .kube
|
|
```
|
|
|
|
6. Configure kubectl to use a remote Kubernetes cluster:
|
|
|
|
```
|
|
New-Item config -type file
|
|
```
|
|
|
|
{{< note >}}Edit the config file with a text editor of your choice, such as Notepad.{{< /note >}}
|
|
|
|
## Download as part of the Google Cloud SDK
|
|
|
|
You can install kubectl as part of the Google Cloud SDK.
|
|
|
|
1. Install the [Google Cloud SDK](https://cloud.google.com/sdk/).
|
|
2. Run the `kubectl` installation command:
|
|
|
|
```
|
|
gcloud components install kubectl
|
|
```
|
|
|
|
3. Test to ensure the version you installed is sufficiently up-to-date:
|
|
|
|
```
|
|
kubectl version
|
|
```
|
|
|
|
## Install kubectl binary using curl
|
|
|
|
{{< tabs name="kubectl_install_curl" >}}
|
|
{{% tab name="macOS" %}}
|
|
1. Download the latest release:
|
|
|
|
```
|
|
curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl
|
|
```
|
|
|
|
To download a specific version, replace the `$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)` portion of the command with the specific version.
|
|
|
|
For example, to download version {{< param "fullversion" >}} on macOS, type:
|
|
|
|
```
|
|
curl -LO https://storage.googleapis.com/kubernetes-release/release/{{< param "fullversion" >}}/bin/darwin/amd64/kubectl
|
|
```
|
|
|
|
2. Make the kubectl binary executable.
|
|
|
|
```
|
|
chmod +x ./kubectl
|
|
```
|
|
|
|
3. Move the binary in to your PATH.
|
|
|
|
```
|
|
sudo mv ./kubectl /usr/local/bin/kubectl
|
|
```
|
|
{{% /tab %}}
|
|
{{% tab name="Linux" %}}
|
|
|
|
1. Download the latest release with the command:
|
|
|
|
```
|
|
curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/linux/amd64/kubectl
|
|
```
|
|
|
|
To download a specific version, replace the `$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)` portion of the command with the specific version.
|
|
|
|
For example, to download version {{< param "fullversion" >}} on Linux, type:
|
|
|
|
```
|
|
curl -LO https://storage.googleapis.com/kubernetes-release/release/{{< param "fullversion" >}}/bin/linux/amd64/kubectl
|
|
```
|
|
|
|
2. Make the kubectl binary executable.
|
|
|
|
```
|
|
chmod +x ./kubectl
|
|
```
|
|
|
|
3. Move the binary in to your PATH.
|
|
|
|
```
|
|
sudo mv ./kubectl /usr/local/bin/kubectl
|
|
```
|
|
{{% /tab %}}
|
|
{{% tab name="Windows" %}}
|
|
1. Download the latest release {{< param "fullversion" >}} from [this link](https://storage.googleapis.com/kubernetes-release/release/{{< param "fullversion" >}}/bin/windows/amd64/kubectl.exe).
|
|
|
|
Or if you have `curl` installed, use this command:
|
|
|
|
```
|
|
curl -LO https://storage.googleapis.com/kubernetes-release/release/{{< param "fullversion" >}}/bin/windows/amd64/kubectl.exe
|
|
```
|
|
|
|
To find out the latest stable version (for example, for scripting), take a look at [https://storage.googleapis.com/kubernetes-release/release/stable.txt](https://storage.googleapis.com/kubernetes-release/release/stable.txt).
|
|
|
|
2. Add the binary in to your PATH.
|
|
{{% /tab %}}
|
|
{{< /tabs >}}
|
|
|
|
|
|
|
|
## Configure kubectl
|
|
|
|
In order for kubectl to find and access a Kubernetes cluster, it needs a [kubeconfig file](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/), which is created automatically when you create a cluster using kube-up.sh or successfully deploy a Minikube cluster. See the [getting started guides](/docs/setup/) for more about creating clusters. If you need access to a cluster you didn't create, see the [Sharing Cluster Access document](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
|
|
By default, kubectl configuration is located at `~/.kube/config`.
|
|
|
|
## Check the kubectl configuration
|
|
Check that kubectl is properly configured by getting the cluster state:
|
|
|
|
```shell
|
|
kubectl cluster-info
|
|
```
|
|
If you see a URL response, kubectl is correctly configured to access your cluster.
|
|
|
|
If you see a message similar to the following, kubectl is not correctly configured or not able to connect to a Kubernetes cluster.
|
|
|
|
```shell
|
|
The connection to the server <server-name:port> was refused - did you specify the right host or port?
|
|
```
|
|
|
|
For example, if you are intending to run a Kubernetes cluster on your laptop (locally), you will need a tool like minikube to be installed first and then re-run the commands stated above.
|
|
|
|
If kubectl cluster-info returns the url response but you can't access your cluster, to check whether it is configured properly, use:
|
|
|
|
```shell
|
|
kubectl cluster-info dump
|
|
```
|
|
|
|
## Enabling shell autocompletion
|
|
|
|
kubectl provides autocompletion support for Bash and Zsh, which can save you a lot of typing!
|
|
|
|
Below are the procedures to set up autocompletion for Bash (including the difference between Linux and macOS) and Zsh.
|
|
|
|
{{< tabs name="kubectl_autocompletion" >}}
|
|
|
|
{{% 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
|
|
source /usr/share/bash-completion/bash_completion
|
|
```
|
|
|
|
Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
|
|
|
|
### 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
|
|
brew install bash-completion@2
|
|
```
|
|
|
|
{{< 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 >}}
|
|
|
|
As stated in the output of `brew install` ("Caveats" section), add the following lines to your `~/.bashrc` or `~/.bash_profile` file:
|
|
|
|
```shell
|
|
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
|
|
```
|
|
|
|
Reload your shell and verify that bash-completion is correctly installed by typing `type _init_completion`.
|
|
|
|
### 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
|
|
source <(kubectl completion zsh)
|
|
```
|
|
|
|
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
|
|
autoload -Uz compinit
|
|
compinit
|
|
```
|
|
{{% /tab %}}
|
|
{{< /tabs >}}
|
|
|
|
{{% /capture %}}
|
|
|
|
{{% capture whatsnext %}}
|
|
[Learn how to launch and expose your application.](/docs/tasks/access-application-cluster/service-access-application-cluster/)
|
|
{{% /capture %}}
|
|
|