Al final de la lección anterior tenías un clúster arrancado y verificado con un par de comandos prestados. Ahora vamos a por la herramienta en sí. kubectl es el cliente oficial de la API de Kubernetes y va a ser, con diferencia, el programa que más uses en este curso y en tu vida profesional con Kubernetes: crear, consultar, inspeccionar, depurar y borrar pasan todos por él. La buena noticia es que kubectl es extraordinariamente regular: una vez entiendes su gramática, sabes usarlo con cualquier tipo de objeto, incluidos los que aún no existen. Esta lección te enseña esa gramática, el fichero de configuración que decide con qué clúster hablas, los verbos que usarás a diario sobre los componentes de Rutas Norte, los formatos de salida que convierten kubectl en una herramienta de consulta seria, y los ajustes de productividad que separan a quien pelea con el clúster de quien trabaja con soltura.

1. Qué es kubectl e instalación
2. El fichero kubeconfig: clústeres, usuarios y contextos
3. Anatomía de un comando kubectl
4. Los verbos del día a día
5. Formatos de salida y consultas
6. Selección por etiquetas y observación en vivo
7. Imperativo frente a declarativo
8. Productividad: alias, autocompletado, explain y plugins

kubectl no tiene inteligencia propia: traduce tus comandos a peticiones HTTPS contra el kube-apiserver. Todo lo que puede hacer kubectl lo podría hacer curl con el certificado adecuado; lo que aporta es comodidad, formato y validación local.

Consecuencia práctica: cualquier cosa que kubectl no te deje hacer, te la está prohibiendo el servidor (RBAC), no la herramienta.

Linux:

macOS:

Windows (PowerShell):

Verificación:

Regla de compatibilidad (version skew): kubectl admite una diferencia de una versión menor arriba o abajo respecto al servidor. Un cliente 1.30 funciona con servidores 1.29, 1.30 y 1.31. Con diferencias mayores pueden fallar comandos concretos de forma poco evidente, así que mantén el cliente cerca del servidor.

Cuando en la lección anterior minikube dijo "kubectl is now configured to use rutas-norte", lo que hizo fue escribir en ~/.kube/config. Ese fichero responde a tres preguntas: ¿a qué servidor hablo?, ¿con qué credenciales? y ¿en qué namespace por defecto?

La idea clave: un contexto es una terna (clúster, usuario, namespace). Cambiar de contexto es cambiar de clúster o de identidad con un solo comando. En un entorno profesional tendrás contextos como rutas-norte-dev, rutas-norte-pre y rutas-norte-pro, y equivocarte de contexto es la forma más rápida de provocar un incidente.

Ese último comando —fijar el namespace por defecto— te ahorrará escribir -n rutas-norte-dev cientos de veces durante el curso. Hazlo en cuanto crees el namespace en la lección 01-07.

Variable KUBECONFIG: puedes tener varios ficheros y combinarlos. Es lo habitual cuando trabajas con varios clientes o entornos:

Consejo de seguridad: el kubeconfig contiene credenciales. Trátalo como una clave privada: permisos 600, nunca en Git, nunca por chat.

Toda la CLI sigue esta gramática:

Ejemplos leídos en voz alta:

Kubernetes acepta singular, plural y abreviatura indistintamente. kubectl get po, kubectl get pod y kubectl get pods son idénticos. Las abreviaturas que más ahorran:

La lista completa y autoritativa de tu clúster, con abreviaturas, grupo de API y si el recurso vive en un namespace:

La columna NAMESPACED es importante: explica por qué kubectl get nodes -n rutas-norte-dev ignora el namespace (los nodos son de ámbito de clúster).

Olvidar el namespace es la causa número uno de "mi pod ha desaparecido".

Trabajaremos sobre un escenario de Rutas Norte con la tienda web y la API ya desplegadas en rutas-norte-dev.

Cómo leer cada columna:

• READY 1/1: contenedores listos / contenedores totales del pod. 0/1 significa que el contenedor existe pero no ha superado su sonda de disponibilidad.
• STATUS: Running es lo normal; Pending (el scheduler no encuentra hueco), ContainerCreating, ImagePullBackOff (no puede descargar la imagen), CrashLoopBackOff (arranca y muere en bucle), Completed (tareas terminadas).
• RESTARTS: reinicios. Un número que crece es la señal más clara de un problema.
• AGE: desde la creación del objeto.

En esa salida, worker-notificaciones está claramente roto. Los tres verbos siguientes son cómo se investiga.

La sección Events es lo primero que hay que leer siempre. Es el diario de lo que el clúster ha intentado hacer con ese objeto y por qué ha fallado. Aquí nos dice que el contenedor termina con código 1 y el kubelet lo reintenta con espera creciente. También vemos que el scheduler sí lo asignó (luego no es un problema de recursos) y que la imagen se descargó bien (luego no es un problema de registro): el fallo está dentro de la aplicación.

describe funciona con cualquier tipo: kubectl describe node rutas-norte, kubectl describe svc api-reservas, kubectl describe pvc datos-postgres.

Ahí está la causa: el worker no encuentra redis-cache por DNS, probablemente porque el Service aún no existe. --previous es la bandera que más se olvida y la más útil: sin ella, en un CrashLoopBackOff verás los logs de un contenedor que acaba de arrancar y aún no ha fallado.

El -- separa las banderas de kubectl del comando a ejecutar dentro; olvidarlo es un error clásico. -it significa interactivo con terminal, igual que en Docker.

Nota profesional: muchas imágenes bien construidas son distroless y no tienen ni sh ni herramientas de red. Para esos casos existe kubectl debug, que inyecta un contenedor efímero con utilidades; lo veremos en el módulo 7.

apply es el corazón del modelo declarativo y lo estudiaremos a fondo en la próxima lección, Objetos, Manifiestos YAML y el Modelo Declarativo.

Sobre delete: recuerda que el borrado es asíncrono y que borrar un pod gestionado por un controlador no lo elimina, solo provoca que se cree uno nuevo. Para eliminarlo de verdad hay que borrar el controlador.

Abre el objeto en tu editor ($EDITOR) y al guardar aplica los cambios. Es cómodo para experimentar y peligroso en producción: el cambio no queda en Git, así que el siguiente apply desde el repositorio lo revertirá silenciosamente. Úsalo para explorar; nunca como forma de desplegar.

Ahora http://localhost:8080 llega a ese pod. El formato es puerto-local:puerto-del-contenedor. También funciona contra un Service (svc/api-reservas 8081:80). Es la forma más rápida de comprobar que algo funciona antes de tener Ingress, y es exactamente lo que usarás en la lección 01-07 para ver la tienda de Rutas Norte en tu navegador. El proceso queda en primer plano: se corta con Ctrl+C.

Este comando merece un párrafo aparte porque es el que más rentabilidad tiene a largo plazo. Consulta el esquema de tu propio clúster, incluidos los CRDs instalados, así que nunca te da información desactualizada ni de otra versión. Funciona a cualquier profundidad y con --recursive muestra el árbol completo de campos:

En la certificación CKA/CKAD, donde solo se permite consultar la documentación oficial, kubectl explain es el atajo que ahorra minutos.

La bandera -o transforma kubectl de visor en herramienta de consulta.

custom-columns y jsonpath son las dos herramientas que convierten a kubectl en algo apto para auditorías rápidas: "dame todas las imágenes en uso en producción", "dime qué pods no tienen límites de memoria".

Recuerda de la lección Conceptos y Terminología Clave que las etiquetas son el mecanismo de acoplamiento del sistema. La bandera -l te da acceso a ese mismo mecanismo desde la CLI:

Esa última consulta es la razón por la que merece la pena ser disciplinado con el esquema de etiquetas del proyecto: te permite ver, borrar o inspeccionar la plataforma entera con un solo comando.

Observación en vivo con --watch (o -w): el comando no termina y va imprimiendo los cambios conforme ocurren. Es la mejor forma de ver el bucle de reconciliación en acción:

Reconoces esa secuencia: es exactamente el recorrido de la lección Arquitectura de Kubernetes —Pending mientras el scheduler decide, ContainerCreating mientras el kubelet trabaja, Running cuando el contenedor vive— ocurriendo ante tus ojos porque el ReplicaSet ha repuesto un pod borrado.

Comandos hermanos que también esperan:

kubectl admite los dos estilos y conviene tener criterio sobre cuándo usar cada uno.

El punto intermedio, y probablemente el truco más útil de toda la lección: generar el manifiesto con un comando imperativo y guardarlo, usando --dry-run=client -o yaml.

Esto no crea nada en el clúster: solo imprime el YAML que kubectl habría enviado. Lo editas, lo versionas y lo aplicas. Es la forma habitual de no escribir manifiestos desde cero, y en la CKAD es prácticamente obligatorio para llegar a tiempo. La próxima lección profundiza en --dry-run, kubectl diff y la mecánica interna de apply.

Añade esto a tu ~/.bashrc o ~/.zshrc. La diferencia de comodidad es enorme:

Para zsh, sustituye completion bash por completion zsh. Con esto, k get po -n <TAB> te completa incluso los nombres de los namespaces existentes, porque el autocompletado consulta la API.

Otras herramientas que conviene conocer, aunque no las usemos aún:

Instalar krew y un plugin, a modo de ejemplo:

Nada de esto es imprescindible, pero en un día de trabajo real ahorra horas. Lo esencial es lo anterior: alias, autocompletado y kubectl explain.

• Trabajar en el contexto equivocado. El error más caro de todos. Antes de cualquier comando destructivo, kubectl config current-context. Configura tu prompt para mostrar contexto y namespace (kube-ps1, starship, oh-my-zsh) y trátalo como innegociable en cuanto tengas acceso a un entorno de producción.
• Olvidar el namespace. Si un objeto "no existe", pruébalo con -A antes de concluir nada. Fija el namespace por defecto con kubectl config set-context --current --namespace=....
• Leer logs sin --previous en un CrashLoopBackOff. Verás el arranque del contenedor actual, no el error que mató al anterior.
• Omitir el -- en kubectl exec. Sin él, kubectl interpreta las banderas de tu comando como suyas y falla de forma confusa.
• Usar kubectl edit como método de despliegue. El cambio no queda en ningún sitio y se pierde en el siguiente apply. Sirve para investigar, no para operar.
• Creer que kubectl delete pod elimina la aplicación. Si hay un controlador detrás, el pod vuelve. Hay que borrar el Deployment, o mejor, el manifiesto con kubectl delete -f.
• Ignorar kubectl explain. Es documentación exacta de tu versión, sin conexión a internet y sin cambiar de ventana. Acostúmbrate a usarlo antes que a buscar en la web.
• Consejo: memoriza este trío de diagnóstico y aplícalo siempre en este orden — kubectl get (¿existe y en qué estado?), kubectl describe (¿qué ha intentado el clúster y qué dicen los eventos?), kubectl logs (¿qué dice la aplicación?). Resuelve la gran mayoría de las incidencias.

Sobre tu clúster rutas-norte:

1. Muestra el contexto activo y comprueba que es el correcto.
2. Crea el namespace rutas-norte-dev y fíjalo como namespace por defecto del contexto.
3. Lista todos los pods del clúster, de todos los namespaces, mostrando el nodo y la IP.
4. Averigua, sin salir de la terminal y sin buscar en internet, qué significa el campo spec.restartPolicy de un pod y qué valores admite.
5. Muestra los pods de kube-system ordenados por antigüedad, del más antiguo al más reciente.

El equipo de seguridad de Rutas Norte pide un inventario. Escribe los comandos que responden a:

1. Todas las imágenes en uso en el clúster, con el pod y el namespace al que pertenecen, en formato de tabla.
2. Los pods de todo el clúster ordenados por número de reinicios, para localizar los inestables.
3. Solo los nombres de los pods que tengan la etiqueta app.kubernetes.io/part-of=rutas-norte, en formato apto para encadenar con otro comando.
4. Todos los recursos del clúster que no viven en un namespace.

Sin crear nada en el clúster, genera el manifiesto YAML de un pod llamado tienda-web con la imagen registry.rutasnorte.example/tienda-web:1.8.0, guárdalo en k8s/base/tienda-web-pod.yaml, y después explica qué diferencia hay entre ejecutar ese comando con --dry-run=client y sin él. Como comprobación adicional, averigua con kubectl si el recurso Pod pertenece al grupo de API core o a apps.

Solución 1

Solución 2

El punto 3 devuelve líneas del tipo pod/api-reservas-6c8d7f9b45-2xk9p, que pueden pasarse directamente a kubectl delete o kubectl describe. El punto 4 lista nodes, namespaces, persistentvolumes, storageclasses, clusterroles, entre otros: los recursos de ámbito de clúster que vimos en la lección de conceptos.

Solución 3

Diferencia: con --dry-run=client, kubectl construye el objeto localmente y lo imprime, sin enviar nada al servidor; no se crea ningún pod y no hace falta ni que el clúster esté arrancado. Sin esa bandera, la petición se envía al apiserver, pasa autenticación, autorización y admisión, se escribe en etcd y el pod se crea de verdad. Existe además --dry-run=server, que sí envía la petición pero le indica al servidor que no persista: valida contra los webhooks de admisión reales sin crear nada. Lo veremos en la próxima lección.

Para el grupo de API:

La columna APIVERSION muestra v1 a secas, sin barra ni prefijo de grupo: eso significa que Pod pertenece al grupo core (o "legacy"), a diferencia de Deployment, que aparece como apps/v1.

kubectl es un cliente HTTP con una gramática muy regular: verbo, tipo, nombre y banderas. Dominarlo consiste en interiorizar esa gramática, saber siempre en qué contexto y namespace estás trabajando, manejar con soltura el trío de diagnóstico get → describe → logs, y aprovechar los formatos de salida y la selección por etiquetas para convertir la CLI en una herramienta de consulta real. Con kubectl explain tienes además documentación exacta de tu propio clúster sin salir de la terminal, y con los alias y el autocompletado el trabajo diario deja de ser tecleo.

En esta lección hemos usado apply sin explicar del todo qué hace por dentro, y hemos visto manifiestos YAML sin desmenuzar su estructura. Esa deuda la salda la siguiente lección, Objetos, Manifiestos YAML y el Modelo Declarativo: anatomía campo a campo de un objeto, grupos y versiones de la API, el YAML que hace falta saber, la diferencia real entre apply, create y replace, las herramientas de validación previa y cómo organizar los manifiestos de Rutas Norte en el directorio k8s/.