Managing the many kubectl versions

Using asdf to manage kubectl installations

3 min readMar 19, 2023

It is important to use the kubectl version that matches the Kubernetes API version because kubectl is a command-line interface tool that is used to interact with the Kubernetes API server. The Kubernetes API is the primary interface for interacting with the Kubernetes cluster and its resources. The Kubernetes API is versioned and changes with each release of Kubernetes.

If you are using a kubectl version that is not compatible with the Kubernetes API version, you may encounter issues when interacting with the Kubernetes cluster. Different versions limit access to new features or cause errors.

Current popular Kubernetes versions

Across different popular cloud offerings, these are the current range of versions supported as of March 2023:

Elastic Kubernetes Service (EKS): 1.22, 1.23, 1.24, 1.25
Google Kubernetes Engine (GKE): 1.24, 1.25
Azure Kubernetes Service (AKS): 1.23, 1.24, 1.25, 1.26

The solution: asdf

So how can you managed multiple versions of kubectl on the same workstation?

There are many tools that manage a single versions for platforms like ruby (rvm, rbenv), python (pyenv), terraform (tfenv), nodejs (nvm). Instead of introducing yet another tool to manage a single platform tooling, I wanted to introduce an abstract version manager that can support many platforms through a plug-in interface with the tool called asdf.

Here’s how you can install different Kubernetes versions using this tool.

Install asdf on macOS

brew install coreutils curl git
brew install asdf
# add this line to shell startup script
. "$(brew --prefix asdf)/libexec/asdf.sh"

Install asdf on Linux

Make sure git and curl are installed, e.g. apt install curl git on Debian or Ubuntu.

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.11.3
# add this line to shell startup script
. "$HOME/.asdf/asdf.sh"

Installing Kubectl

Once asdf is set up, you can install the kubectl with the following:

asdf plugin-add kubectl \
  https://github.com/asdf-community/asdf-kubectl.git
asdf install kubectl latest

# install a specific version
KUBECTL_VERSION="1.24"
asdf install kubectl $KUBECTL_VERSION

Install many versions (not Macbook M2)

You can install a range of versions in bash or zsh with the following below. This grabs the latest minor version of the tool for each major version category of 1.19 to 1.23.

for VERSION in 1.{19..24}; do
 TARGET=$(asdf list all kubectl \
   | grep $VERSION \
   | grep -v rc \
   | tail -1
 )

 asdf install kubectl $TARGET
done

Installing many versions on Macbook M2

The Macbook M2 uses arm64 processor, but older versions of kubectl only work on the Intel processor. You can accommodate older Intel only binaries by using Rosetta and the arch command.

for VERSION in 1.{19..24}; do
 # 1.19 and 1.20 are amd64 only
 if (( $(echo "$VERSION < 1.21" | bc -l) )); then
   PREFIX="arch -x86_64"
 else 
   PREFIX=""
 fi
 
 TARGET=$($PREFIX asdf list all kubectl \
   | grep $VERSION \
   | grep -v rc \
   | tail -1
 )

 $PREFIX asdf install kubectl $TARGET
done

Using the desired kubectl

Now with a few versions of kubectl installed, we can select the desired version with the following:

asdf global kubectl $(asdf list kubectl | grep 1.19)
kubectl version --client --short
# Client Version: v1.19.16

asdf global kubectl $(asdf list kubectl | grep 1.20)
kubectl version --client --short
# Client Version: v1.20.15

Other asdf plugins

In addition to kubectl, you can install other plugins for tools that are popular with Kubernetes using asdf:

asdf plugin-add helm \
  https://github.com/Antiarchitect/asdf-helm.git
asdf plugin-add helmfile \
  https://github.com/feniix/asdf-helmfile.git
asdf plugin-add kustomize \
  https://github.com/Banno/asdf-kustomize.git

Beyond Kubernetes, there’s other plugins for tools that are popular with the cloud that can be installed, such as some tools from Hashicorp:

PLUGIN_URL="https://github.com/asdf-community/asdf-hashicorp.git"

for TOOL in terraform packer vault; do 
  asdf plugin-add $TOOL $PLUGIN_URL
done

Wrapping Up

I hope this is useful for managing different Kubernetes versions, as well as a new tool to manage a variety of tool and language platforms.