Guía para gestionar múltiples clústeres de Kubernetes con kubectl config

Gestionar múltiples clústeres de Kubernetes es algo habitual cuando tienes entornos de desarrollo, staging, producción o clústeres en más de una nube. El riesgo es simple: un comando puede afectar al clúster equivocado si tu contexto no está claro.

Esta guía te muestra cómo usar kubectl config para inspeccionar contextos, cambiar de clúster, establecer espacios de nombres y organizar múltiples archivos kubeconfig.

Entendiendo el archivo Kubeconfig

Antes de sumergirnos en los comandos de kubectl config, es esencial entender el archivo kubeconfig. Este archivo almacena información sobre tus clústeres, usuarios y los contextos que los vinculan. kubectl utiliza este archivo para autenticarse y especificar con qué clúster interactuar. Por defecto, kubectl busca el archivo kubeconfig en $HOME/.kube/config.

Dentro de este archivo, encontrarás tres secciones principales:

clusters: Define los clústeres de Kubernetes, incluyendo sus puntos finales del servidor API y autoridades certificadoras.
users: Almacena credenciales de autenticación, como certificados de cliente y tokens.
contexts: Asocia un clúster, un usuario y opcionalmente un espacio de nombres. Un contexto proporciona una forma conveniente de agrupar estas configuraciones, permitiendo a kubectl cambiar fácilmente entre diferentes combinaciones de clúster/usuario.

Gestionando Contextos con `kubectl config`

Los contextos son la forma principal en que kubectl gestiona tu conexión a diferentes clústeres de Kubernetes. Actúan como atajos, permitiéndote cambiar entre ellos con un solo comando.

Visualizando Contextos Disponibles

Para ver todos los contextos disponibles en tu archivo kubeconfig actual, usa el siguiente comando:

kubectl config get-contexts

Este comando mostrará una lista de contextos, junto con el clúster, usuario y espacio de nombres asociados a cada uno. El contexto activo actualmente estará marcado con un asterisco (*).

Ejemplo de salida:

CURRENT   NAME                 CLUSTER              AUTHINFO       NAMESPACE
*         my-dev-context       my-dev-cluster       dev-user       default
          my-prod-context      my-prod-cluster      prod-user      production
          staging-context      staging-cluster      staging-user   staging

Obteniendo el Contexto Actual

Para verificar rápidamente qué contexto estás usando actualmente, ejecuta:

kubectl config current-context

Esto mostrará el nombre del contexto activo.

Cambiando de Contexto

Cambiar a un contexto diferente es sencillo. Usa el subcomando use-context seguido del nombre del contexto que deseas activar:

kubectl config use-context <nombre-del-contexto>

Por ejemplo, para cambiar a my-prod-context del ejemplo anterior:

kubectl config use-context my-prod-context

Después de ejecutar este comando, los comandos posteriores de kubectl se dirigirán al clúster especificado en my-prod-context.

Estableciendo un Contexto

También puedes establecer un contexto específico para un clúster y usuario sin necesariamente convertirlo en el predeterminado para uso futuro. Esto es útil para operaciones temporales.

kubectl config set-context <nombre-del-contexto> --cluster=<nombre-del-clúster> --user=<nombre-del-usuario> --namespace=<nombre-del-espacio-de-nombres>

Si omites --namespace, se usará el espacio de nombres predeterminado del clúster.

Gestionando Clústeres y Usuarios

Mientras que los contextos se usan para cambiar, también puedes gestionar directamente las configuraciones de clúster y usuario a las que se refieren los contextos.

Visualizando Información del Clúster

Para listar todos los clústeres configurados:

kubectl config get-clusters

Para ver detalles de un clúster específico:

kubectl config view --minify -o jsonpath='{.clusters[?(@.name=="<nombre-del-clúster>")].cluster}'

Reemplaza <nombre-del-clúster> con el nombre real de tu clúster.

Visualizando Información del Usuario

Para listar todos los usuarios configurados:

kubectl config get-users

Añadiendo y Modificando Configuraciones

Puedes añadir nuevos clústeres, usuarios y contextos, o modificar los existentes:

Añadir un nuevo clúster:

kubectl config set-cluster <nombre-del-clúster> --server=<url-del-servidor-api> --certificate-authority=<ruta-al-archivo-ca> --embed-certs=true

Añadir un nuevo usuario:

kubectl config set-credentials <nombre-del-usuario> --client-certificate=<ruta-al-archivo-de-certificado> --client-key=<ruta-al-archivo-de-clave> --embed-certs=true

Añadir un nuevo contexto:

kubectl config set-context <nombre-del-contexto> --cluster=<nombre-del-clúster> --user=<nombre-del-usuario> --namespace=<nombre-del-espacio-de-nombres>

Gestionando Múltiples Archivos Kubeconfig

Para una mayor seguridad y organización, especialmente al tratar con muchos clústeres o credenciales sensibles, es una buena práctica mantener tus archivos kubeconfig separados. kubectl puede gestionar múltiples archivos kubeconfig usando la variable de entorno KUBECONFIG o la bandera --kubeconfig.

Usando la Variable de Entorno `KUBECONFIG`

Puedes especificar una lista de archivos kubeconfig para cargar. kubectl fusiona estos archivos. Si el mismo clúster, usuario o contexto con el mismo nombre aparece en más de un archivo, la precedencia de fusión depende del orden de los archivos en KUBECONFIG, así que usa nombres únicos para evitar sorpresas.

Para establecer esta variable para tu sesión actual del shell:

export KUBECONFIG=~/.kube/config:~/.kube/config-dev:~/.kube/config-prod

Para hacerlo persistente, añade la línea export al archivo de perfil de tu shell (por ejemplo, ~/.bashrc, ~/.zshrc).

Usando la Bandera `--kubeconfig`

Alternativamente, puedes especificar un archivo kubeconfig particular para un solo comando de kubectl:

kubectl --kubeconfig=~/.kube/config-dev get pods

Esto es útil para comandos puntuales o cuando quieres estar absolutamente seguro de qué archivo se está usando.

Mejores Prácticas para la Gestión de Múltiples Clústeres

Usa Archivos Separados: Almacena configuraciones para diferentes entornos (dev, staging, prod) o proveedores de nube en archivos kubeconfig distintos (por ejemplo, config-dev, config-staging, config-prod).
Aprovecha KUBECONFIG: Establece la variable de entorno KUBECONFIG en el perfil de tu shell para fusionar y gestionar fácilmente múltiples archivos sin fusión manual.
Nombres de Contexto Descriptivos: Usa nombres claros y descriptivos para tus contextos (por ejemplo, aws-prod-us-east-1, gke-dev-eu-west-2) para evitar confusiones.
Conciencia del Espacio de Nombres: Siempre ten en cuenta el espacio de nombres en el que estás operando. Usa la bandera --namespace o establécelo en tu contexto para apuntar al espacio de nombres correcto.
Audita Regularmente: Revisa periódicamente tus contextos y configuraciones de clúster para asegurarte de que estén actualizados y sean seguros.
Asegura tu Kubeconfig: Trata tus archivos kubeconfig como credenciales sensibles. Restringe los permisos de archivo y evita comprometerlos en el control de versiones.

Conclusión Final

Haz que las comprobaciones de contexto sean parte de tu flujo de trabajo. Ejecuta kubectl config current-context antes de comandos arriesgados, usa nombres de contexto descriptivos, establece espacios de nombres intencionalmente y mantén las credenciales de producción fuera de sesiones casuales del shell cuando no las necesites.