Skip to content

Commit

Permalink
Updating /docs/tasks/tools/install-kubectl
Browse files Browse the repository at this point in the history 
Adding instructions for how to validate kubectl binaries against checksum files (Linux, MacOS, Windows)

Updating links to download from https://dl.k8s.io/

Adding note annotation around optional download instructions

Markdown updates
* Updating numbered lists to use markdown syntax ("1." for each entry), should make it easier to add and remove list items in future
* Updating spacing throughout

Correcting "PowerShell" spelling

fixes: #25040

Signed-off-by: Nate W <4453979+nate-double-u@users.noreply.github.com>
  • Loading branch information
@nate-double-u
nate-double-u committed Nov 28, 2020
1 parent a0560f3 commit f5c0666
Showing 1 changed file with 168 additions and 100 deletions.
268 changes: 168 additions & 100 deletions content/en/docs/tasks/tools/install-kubectl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,32 +30,60 @@ Using the latest version of kubectl helps avoid unforeseen issues.

### Install kubectl binary with curl on Linux

1. Download the latest release with the command:
1. Download the latest stable 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"
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/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.
{{< note >}}
To download a specific version, replace the `$(curl -L -s https://dl.k8s.io/release/stable.txt)` portion of the command with the specific version.

For example, to download version {{< param "fullversion" >}} on Linux, type:

For example, to download version {{< param "fullversion" >}} on Linux, type:

```
curl -LO https://dl.k8s.io/release/{{< param "fullversion" >}}/bin/linux/amd64/kubectl
```
{{< /note >}}

**Validate the binary (optional)**

Checksum files are available to validate downloaded binaries.

To download the checksum file:
```
curl -LO https://storage.googleapis.com/kubernetes-release/release/{{< param "fullversion" >}}/bin/linux/amd64/kubectl
curl -LO "https://dl.k8s.io/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"
```

2. Make the kubectl binary executable.
Validate the binary against the checksum file:
```
echo "$(<kubectl.sha256) kubectl" | sha256sum --check
```

This should result in: `kubectl: OK`

If the check fails, `sha256` will report something like:
```
kubectl: FAILED
sha256sum: WARNING: 1 computed checksum did NOT match
```

{{< caution >}}
Be sure to download the same version of the binary and checksum.
{{< /caution >}}

1. Make the kubectl binary executable.

```
chmod +x ./kubectl
```

3. Move the binary in to your PATH.
1. Move the binary in to your PATH.

```
sudo mv ./kubectl /usr/local/bin/kubectl
```
4. Test to ensure the version you installed is up-to-date:
1. Test to ensure the version you installed is up-to-date:

```
kubectl version --client
Expand Down Expand Up @@ -117,33 +145,49 @@ kubectl version --client

### Install kubectl binary with curl on macOS

1. Download the latest release:
1. Download the latest stable release:

```bash
curl -LO "https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl"
```
```bash
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl"
```
{{< note >}}
To download a specific version, replace the `$(curl -L -s https://dl.k8s.io/release/stable.txt)` portion of the command with the specific version.

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:

For example, to download version {{< param "fullversion" >}} on macOS, type:
```bash
curl -LO https://dl.k8s.io/release/{{< param "fullversion" >}}/bin/darwin/amd64/kubectl
```
{{< /note >}}

```bash
curl -LO https://storage.googleapis.com/kubernetes-release/release/{{< param "fullversion" >}}/bin/darwin/amd64/kubectl
```
**Validate the binary (optional)**

Make the kubectl binary executable.
Checksum files are available to validate downloaded binaries.

```bash
chmod +x ./kubectl
```
To download the checksum file:
```
curl -LO "https://dl.k8s.io/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/amd64/kubectl.sha256"
```

Validate the binary against the checksum file by comparing `shasum`'s
output to the checksum file downloaded:
```
echo "$(<kubectl.sha256) kubectl" | shasum -a 256 --check
```
1. Make the kubectl binary executable.
```bash
chmod +x ./kubectl
```
3. Move the binary in to your PATH.
1. Move the binary in to your PATH.
```bash
sudo mv ./kubectl /usr/local/bin/kubectl
```
4. Test to ensure the version you installed is up-to-date:
1. Test to ensure the version you installed is up-to-date:
```bash
kubectl version --client
Expand All @@ -165,7 +209,7 @@ If you are on macOS and using [Homebrew](https://brew.sh/) package manager, you
brew install kubernetes-cli
```
2. Test to ensure the version you installed is up-to-date:
1. Test to ensure the version you installed is up-to-date:
```bash
kubectl version --client
Expand All @@ -182,7 +226,7 @@ If you are on macOS and using [Macports](https://macports.org/) package manager,
sudo port install kubectl
```
2. Test to ensure the version you installed is up-to-date:
1. Test to ensure the version you installed is up-to-date:
```bash
kubectl version --client
Expand All @@ -192,51 +236,75 @@ If you are on macOS and using [Macports](https://macports.org/) package manager,
### Install kubectl binary with curl on 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).
1. Download the latest release, {{< param "fullversion" >}}, from [this link](https://dl.k8s.io/release/{{< param "fullversion" >}}/bin/windows/amd64/kubectl.exe).
Or if you have `curl` installed, use this command:
Or if you have `curl` installed, use this command:
```bash
curl -LO https://storage.googleapis.com/kubernetes-release/release/{{< param "fullversion" >}}/bin/windows/amd64/kubectl.exe
```
```bash
curl -LO https://dl.k8s.io/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).
{{< note >}}
To find out the latest stable version (for example, for scripting), take a look at [https://dl.k8s.io/release/stable.txt](https://dl.k8s.io/release/stable.txt).
{{< /note >}}
2. Add the binary in to your PATH.
**Validate the binary (optional)**
3. Test to ensure the version of `kubectl` is the same as downloaded:
Checksum files are available to validate downloaded binaries.
```bash
kubectl version --client
```
To download the checksum file:
```
curl -LO https://dl.k8s.io/{{< param "fullversion" >}}/bin/windows/amd64/kubectl.exe.sha256
```
Validate the binary against the checksum file
Using Command Prompt to manually compare `CertUtil`'s output to the checksum file downloaded:
```
CertUtil -hashfile kubectl.exe SHA256
type kubectl.exe.sha256
```

Optionally, using PowerShell to automate the verification using the `-eq` operator to get a `True` or `False` result:
```
$($(CertUtil -hashfile .\kubectl.exe SHA256)[1] -replace " ", "") -eq $(type .\kubectl.exe.sha256)
```

1. Add the binary in to your PATH.

1. Test to ensure the version of `kubectl` is the same as downloaded:

```bash
kubectl version --client
```

{{< note >}}
[Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/#kubernetes) adds its own version of `kubectl` to PATH.
If you have installed Docker Desktop before, you may need to place your PATH entry before the one added by the Docker Desktop installer or remove the Docker Desktop's `kubectl`.
{{< /note >}}
### Install with Powershell from PSGallery
### 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.
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`):
```powershell
Install-Script -Name 'install-kubectl' -Scope CurrentUser -Force
install-kubectl.ps1 [-DownloadLocation <path>]
```powershell
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 >}}
{{< 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.
The installer creates `$HOME/.kube` and instructs it to create a config file.

2. Test to ensure the version you installed is up-to-date:
1. Test to ensure the version you installed is up-to-date:

```powershell
kubectl version --client
```
```powershell
kubectl version --client
```

{{< note >}}
Updating the installation is performed by rerunning the two commands listed in step 1.
Expand All @@ -246,50 +314,50 @@ Updating the installation is performed by rerunning the two commands listed in s

1. 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" %}}
```powershell
choco install kubernetes-cli
```
{{% /tab %}}
{{% tab name="scoop" %}}
```powershell
scoop install kubectl
```
{{% /tab %}}
{{< /tabs >}}
{{< tabs name="kubectl_win_install" >}}
{{% tab name="choco" %}}
```powershell
choco install kubernetes-cli
```
{{% /tab %}}
{{% tab name="scoop" %}}
```powershell
scoop install kubectl
```
{{% /tab %}}
{{< /tabs >}}


2. Test to ensure the version you installed is up-to-date:
1. Test to ensure the version you installed is up-to-date:

```powershell
kubectl version --client
```
```powershell
kubectl version --client
```

3. Navigate to your home directory:
1. Navigate to your home directory:

```powershell
# If you're using cmd.exe, run: cd %USERPROFILE%
cd ~
```
```powershell
# If you're using cmd.exe, run: cd %USERPROFILE%
cd ~
```

4. Create the `.kube` directory:
1. Create the `.kube` directory:

```powershell
mkdir .kube
```
```powershell
mkdir .kube
```

5. Change to the `.kube` directory you just created:
1. Change to the `.kube` directory you just created:

```powershell
cd .kube
```
```powershell
cd .kube
```

6. Configure kubectl to use a remote Kubernetes cluster:
1. Configure kubectl to use a remote Kubernetes cluster:

```powershell
New-Item config -type file
```
```powershell
New-Item config -type file
```

{{< note >}}
Edit the config file with a text editor of your choice, such as Notepad.
Expand All @@ -301,17 +369,17 @@ 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:
1. Run the `kubectl` installation command:

```shell
gcloud components install kubectl
```
```shell
gcloud components install kubectl
```

3. Test to ensure the version you installed is up-to-date:
1. Test to ensure the version you installed is up-to-date:

```shell
kubectl version --client
```
```shell
kubectl version --client
```

## Verifying kubectl configuration

Expand Down Expand Up @@ -382,14 +450,14 @@ You now need to ensure that the kubectl completion script gets sourced in all yo

- Source the completion script in your `~/.bashrc` file:

```bash
echo 'source <(kubectl completion bash)' >>~/.bashrc
```
```bash
echo 'source <(kubectl completion bash)' >>~/.bashrc
```
- Add the completion script to the `/etc/bash_completion.d` directory:

```bash
kubectl completion bash >/etc/bash_completion.d/kubectl
```
```bash
kubectl completion bash >/etc/bash_completion.d/kubectl
```
If you have an alias for kubectl, you can extend shell completion to work with that alias:

```bash
Expand Down Expand Up @@ -488,9 +556,9 @@ You now have to ensure that the kubectl completion script gets sourced in all yo
- If you installed kubectl with Homebrew (as explained [above](#install-with-homebrew-on-macos)), then the kubectl completion script should already be in `/usr/local/etc/bash_completion.d/kubectl`. In that case, you don't need to do anything.

{{< note >}}
The Homebrew installation of bash-completion v2 sources all the files in the `BASH_COMPLETION_COMPAT_DIR` directory, that's why the latter two methods work.
{{< /note >}}
{{< note >}}
The Homebrew installation of bash-completion v2 sources all the files in the `BASH_COMPLETION_COMPAT_DIR` directory, that's why the latter two methods work.
{{< /note >}}
In any case, after reloading your shell, kubectl completion should be working.
{{% /tab %}}
Expand Down

0 comments on commit f5c0666

Please sign in to comment.