Gestión de versiones de kubectl con asdf

Gestionar varios clústeres de Kubernetes suele implicar lidiar con distintas versiones de kube-apiserver en cada uno de ellos. Si las diferencias entre versiones son pequeñas, es posible que un mismo cliente kubectl funcione para las operaciones más habituales. Pero la propia documentación de Kubernetes deja claro que, para evitar problemas inesperados, la versión menor de kubectl no debería diferir en más de una unidad respecto a la de kube-apiserver.

Dicho de otro modo, usando versionado semántico (MAJOR.MINOR.PATCH):

Dadas dos versiones,

X1.Y1.Z1 y X2.Y2.Z2

debe cumplirse que:

X1 == X2 y |Y1 - Y2| <= 1

En este tipo de escenarios, asdf resulta especialmente útil: es una herramienta genérica basada en plugins para gestionar distintas versiones de runtimes. La usarás para tener disponibles varias versiones del cliente kubectl en la línea de comandos y elegir, en cada momento, la que corresponda al clúster con el que estés trabajando.

Este artículo está basado en los siguientes componentes y versiones:

• Ubuntu 22.04.3 LTS
• asdf 0.13.1
• kubectl 1.27.5

Instalación de la herramienta asdf

Aquí asumimos Bash y Git. Para obtener una combinación diferente de shell, sistema operativo o método de instalación, consulta la documentación completa.

Primero, asegúrate de que las dependencias necesarias para los paquetes que vas a instalar estén disponibles:

1

sudo apt update && sudo apt install -y curl git jq

Luego, descarga la última versión de asdf en el directorio ~/.asdf:

1
2

ASDF_VERSION=$(curl -sL https://api.github.com/repos/asdf-vm/asdf/releases/latest | jq -r ".name")
git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch $ASDF_VERSION

Ten en cuenta que, si ya has probado instalaciones anteriores, es posible que el directorio ~/.asdf ya exista.

Agrega scripts asdf a .bashrc para agregar el binario asdf a la RUTA y habilitar el autocompletado:

1
2
3

echo '. "$HOME/.asdf/asdf.sh"' >> ~/.bashrc
echo '. "$HOME/.asdf/completions/asdf.bash"' >> ~/.bashrc
source ~/.bashrc

Finalmente, verifica que asdf se haya instalado correctamente:

1

asdf version

Instalación del complemento asdf-kubectl

Los plugins son la forma en que asdf soporta distintas herramientas. Cada plugin vive en su propio repositorio e incluye scripts ejecutables para administrar versiones de esa herramienta.

Consulta una lista completa de plugins compatibles y sus repositorios aquí.

En nuestro caso, puedes agregar el plugin kubectl a través de la URL de Git correspondiente:

1

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

Instalando una versión específica de kubectl

asdf utiliza versiones exactas. Para enumerar todas las versiones disponibles de la herramienta kubectl, ejecuta:

1

asdf list all `kubectl`

Opcionalmente, también puedes obtener un subconjunto de versiones disponibles filtrando por versión principal o versión principal y secundaria, respectivamente:

1 2	asdf list all kubectl 1 asdf list all kubectl 1.27

El asistente latest está disponible para resolver el número de versión estable real en el momento de la ejecución.

Ahora que ya tienes un plugin para kubectl, puedes instalar cualquier versión disponible de la herramienta:

1

asdf install kubectl 1.27.5

Para enumerar las versiones de kubectl instaladas en cualquier momento, escribe:

1	asdf list kubectl

Configurar una versión específica de kubectl

Ahora configura la versión actual de kubectl con:

1

asdf global kubectl 1.27.5

Cuando configuramos la versión de una herramienta, se agrega al archivo .tool-versions. Los alcances de instalación, de menor a mayor prioridad, son:

• global escribe la versión en $HOME/.tool-versions
• local escribe la versión en $PWD/.tool-versions
• shell establece la versión a través de una variable de entorno llamada ASDF_${TOOL}_VERSION

Comprueba que la versión kubectl coincida con la versión actualmente establecida por asdf:

1
2

asdf current
kubectl version --client --short

Por último, pero no menos importante, habilita el autocompletado de kubectl y, si quieres, define k como alias:

1
2
3
4

echo 'source <(kubectl completion bash)' >> ~/.bashrc
echo 'alias k=kubectl' >>~/.bashrc
echo 'complete -F __start_kubectl k' >> ~/.bashrc
source ~/.bashrc

Definición de un comando de alias para cada clúster

Ahora que ya has instalado las versiones necesarias del cliente kubectl, es una buena idea asociar cada una con un clúster de la misma versión mediante un alias.

La siguiente configuración supone que hay un archivo kubeconfig por clúster:

1
2
3
4
5
6
7
8
9

cat << EOF >> ~/.bashrc
# Alias para el clúster DEV
alias kdev='asdf global kubectl 1.27.5 && \
export KUBECONFIG=$HOME/.kube/config.dev && \
source <(kubectl completion bash) && \
kubectl config current-context && \
asdf current kubectl'
EOF
source ~/.bashrc

De esta manera, al invocar el alias kdev se cambia de forma transparente a ese clúster y tu correspondiente versión de kubectl, mostrando esta información en la consola:

1
2
3

kdev
# kubernetes-admin@dev
# kubectl   1.27.5   /home/manuel/.tool-version

No olvides definir un alias distinto en ~/.bashrc para cada clúster que quieras gestionar con su versión específica de kubectl.

Conclusión

Con asdf puedes dejar atrás la limitación de depender de una única versión de kubectl en tu máquina y adoptar un flujo de trabajo mucho más flexible. En lugar de cambiar binarios manualmente o depender del gestor de paquetes de tu distribución, puedes mantener varias versiones del cliente disponibles y seleccionar la adecuada según el clúster con el que estés trabajando.

Este enfoque resulta especialmente útil cuando gestionas entornos de desarrollo, staging o producción con distintos niveles de compatibilidad, porque reduces el riesgo de incompatibilidades y facilitas la transición entre contextos. Además, la misma estrategia se puede aplicar a otras herramientas y runtimes, como Go, Node, Ruby o Python, simplemente sustituyendo kubectl por el plugin correspondiente.