Kubernetes · Cheatsheet 02

kubectl

kubectl es el comando para hablar con el cluster: consultar qué hay, crear y borrar objetos, ver logs y entrar a los Pods. Casi todos los comandos siguen el patrón kubectl <verbo> <tipo> <nombre>, por ejemplo kubectl get pods o kubectl delete deploy chanchito. Lo que está entre < > se reemplaza.

Términos de esta página

Los objetos (Pod, Deployment, Service…) están explicados en Conceptos.

Recurso / objeto: Cualquier cosa que existe en el cluster: un Pod, un Deployment, un Service, un namespace. Cada uno tiene un tipo y un nombre.
Verbo: Lo que querés hacer: get (listar), describe (detalle), apply (crear o actualizar), delete (borrar), logs, exec…
kubeconfig: El archivo ~/.kube/config donde kubectl guarda a qué clusters puede conectarse y con qué credenciales.
Contexto: Una combinación de cluster + usuario + namespace guardada en el kubeconfig. Cambiar de contexto = cambiar de cluster.
Namespace: Agrupación de recursos dentro del cluster. Si no indicás uno con -n, kubectl usa default.
Label: Una etiqueta clave=valor pegada a un objeto (app=chanchito), para filtrar y agrupar.
Rollout: El proceso de actualizar un Deployment a una versión nueva, reemplazando los Pods de a poco.
Port-forward: Un túnel temporal desde un puerto de tu PC hasta un Pod o Service del cluster, para probarlo desde el navegador.
Watch (-w): Dejar el comando abierto mostrando los cambios en vivo. Se corta con Ctrl+C.
Helm / chart: Helm es un gestor de paquetes para Kubernetes; un chart es un paquete listo para instalar (por ejemplo, una base de datos completa).

Cluster local para practicar

Elegí uno. En Windows lo más directo es el de Docker Desktop.

Docker Desktop

Abrí Docker Desktop → ícono de engranaje (Settings) → Kubernetes.
Marcá Enable Kubernetes y tocá Apply & restart. Si pregunta por el tipo de cluster, dejá la opción por defecto (kubeadm).
Esperá unos minutos a que abajo aparezca Kubernetes running.

Esto instala kubectl y crea el contexto docker-desktop.

kubectl config use-context docker-desktop
kubectl get nodes

La primera línea le dice a kubectl que use el cluster de Docker Desktop (por si tenías otro configurado). La segunda lista las máquinas del cluster: si aparece docker-desktop con STATUS Ready, está funcionando y listo para recibir Pods.

NAME             STATUS   ROLES           AGE   VERSION
docker-desktop   Ready    control-plane   2m    v1.3x.x

✓

Comparte las imágenes con tu Docker: lo que construís con docker build ya está disponible (usá imagePullPolicy: IfNotPresent).

minikube

minikube start
minikube stop
minikube delete

minikube es otra forma de tener un cluster local, independiente de Docker Desktop. start lo crea la primera vez (tarda unos minutos) y lo enciende las siguientes; stop lo apaga conservando todo; delete lo borra por completo. Al arrancar, configura kubectl para que apunte a él.

minikube image load chanchito:1

minikube tiene su propio Docker, separado del tuyo: una imagen construida con docker build en tu PC no está ahí. Este comando la copia al cluster para que los Pods puedan usarla sin un registro.

minikube service chanchito

Busca la dirección por la que se llega a un Service de tipo NodePort y la abre en el navegador. En Windows deja la terminal ocupada mientras mantiene el acceso abierto.

minikube dashboard
minikube tunnel

dashboard abre un panel web para ver Pods, Deployments y logs con el mouse. tunnel (se deja corriendo en otra terminal) le da una dirección accesible desde tu PC a los Services de tipo LoadBalancer, que en un cluster local, si no, quedan en pending.

kind (Kubernetes in Docker)

kind create cluster --name dev
kind delete cluster --name dev

kind (Kubernetes in Docker) crea un cluster cuyos nodos son contenedores de tu Docker. Es rápido de crear y borrar, ideal para pruebas. --name permite tener varios; delete lo elimina.

kind load docker-image chanchito:1 --name dev

Copia una imagen de tu Docker a los nodos del cluster kind, para que los Pods la encuentren sin subirla a un registro. Hay que repetirlo cada vez que reconstruís la imagen.

¿Funciona?

kubectl version

Muestra la versión de kubectl (Client) y la del cluster (Server). Si solo aparece Client y un error de conexión, kubectl no llega al cluster: revisá que esté encendido y el contexto.

kubectl cluster-info

Muestra la dirección del control plane (el “cerebro” del cluster, que recibe tus comandos). Si responde, la conexión funciona.

kubectl get nodes

Lista las máquinas del cluster. Cada una debe estar Ready; NotReady significa que el nodo tiene un problema y no va a recibir Pods nuevos.

Contextos: a qué cluster estoy apuntando

Un contexto = cluster + usuario + namespace por defecto. Viven en ~/.kube/config.

Ver y cambiar contexto

kubectl config get-contexts

kubectl puede tener configurados varios clusters (local, de pruebas, de producción). Cada combinación de cluster + usuario + namespace es un contexto. Este comando los lista; el que está en uso tiene un * en la columna CURRENT.

kubectl config current-context

Muestra solo el nombre del contexto en uso. Conviene mirarlo antes de aplicar o borrar algo.

kubectl config use-context <contexto>

Cambia el cluster al que le habla kubectl. Todos los comandos siguientes van a ese cluster hasta que vuelvas a cambiarlo.

Namespace por defecto

kubectl config set-context --current --namespace=<ns>

Cambia el namespace por defecto del contexto actual. A partir de ahí, kubectl get pods muestra los de ese namespace sin escribir -n <ns> en cada comando.

kubectl config view --minify

Muestra la configuración del contexto actual: la dirección del cluster, el usuario y el namespace por defecto (las credenciales aparecen ocultas). Los datos vienen del archivo %USERPROFILE%\.kube\config.

Antes de borrar algo, revisá el contexto. Es el error clásico: ejecutar en producción creyendo que estás en local.

Ver recursos

get para listar, describe para el detalle con eventos.

Listar (get)

kubectl get pods

Lista los Pods del namespace actual (es el equivalente a docker ps). Columnas: READY (contenedores listos / total), STATUS (Running, Pending, CrashLoopBackOff…), RESTARTS (cuántas veces se reinició: si sube, algo falla) y AGE.

kubectl get pods -o wide

-o (output) cambia el formato; wide agrega columnas: la IP interna de cada Pod y en qué nodo corre.

kubectl get pods -A

-A (all namespaces) muestra los Pods de todos los namespaces, incluidos los del propio Kubernetes en kube-system. Agrega una columna NAMESPACE.

kubectl get pods -w

-w (watch) se queda mirando y agrega una línea cada vez que un Pod cambia de estado. Ideal justo después de un apply, para ver cómo arrancan. Ctrl+C para salir.

kubectl get all

Muestra de una vez los Pods, Services, Deployments y ReplicaSets del namespace. A pesar del nombre, no incluye ConfigMaps, Secrets, PVC ni Ingress: esos se piden aparte.

kubectl get deploy,svc,pvc,cm,secret

Lista varios tipos a la vez, separados por coma sin espacios. Se usan los nombres cortos: deploy (Deployment), svc (Service), pvc, cm (ConfigMap), secret.

Detalle (describe)

kubectl describe pod <pod>

Muestra todo sobre un Pod en forma legible: en qué nodo está, sus contenedores, imagen, variables, volúmenes y, al final, Events: la historia reciente (se programó, descargó la imagen, arrancó, falló la prueba de salud…). Ahí aparece el motivo de casi todos los errores.

kubectl describe deploy chanchito
kubectl describe svc chanchito

Lo mismo para un Deployment (réplicas deseadas y disponibles, imagen, eventos del rollout) y para un Service. En el Service mirá Endpoints: son las IPs de los Pods que recibe. Si está vacío, el selector no coincide con las etiquetas de ningún Pod listo.

kubectl get events --sort-by=.lastTimestamp

Lista los eventos de todo el namespace (no solo de un Pod), ordenados del más viejo al más nuevo. Útil cuando no sabés qué objeto está fallando. Los eventos se borran solos después de una hora.

kubectl get deploy chanchito -o yaml

Muestra el objeto completo en YAML, tal como lo guarda el cluster: lo que escribiste más los valores por defecto que agregó Kubernetes y una sección status con su estado actual.

kubectl explain deployment.spec.template.spec.containers

La documentación de cualquier campo de un manifiesto, sin salir de la terminal: qué tipo de valor lleva y para qué sirve. Agregá --recursive para ver todos los subcampos.

kubectl api-resources

Lista todos los tipos de objeto que entiende el cluster, con su nombre corto (SHORTNAMES), su apiVersion y si pertenecen a un namespace.

Crear, actualizar y borrar

Lo normal: escribir YAML y usar apply. Los comandos imperativos sirven para pruebas rápidas o para generar el YAML.

Declarativo (apply)

kubectl apply -f deployment.yaml

Lee el archivo y hace que el cluster quede como dice: crea lo que no existe y actualiza lo que cambió. Se puede repetir todas las veces que quieras; si no cambió nada, responde unchanged. Es la forma normal de trabajar.

kubectl apply -f k8s/

Aplica todos los archivos .yaml de una carpeta de una vez: equivale a docker compose up -d para un proyecto completo.

kubectl diff -f k8s/

Muestra qué cambiaría en el cluster si aplicaras esos archivos, sin cambiar nada (las líneas con - se quitan, con + se agregan). Si no imprime nada, el cluster ya está igual a los archivos.

kubectl delete -f k8s/

Borra del cluster todo lo que está definido en esos archivos; los archivos no se tocan. Equivale a docker compose down. Si hay un PVC en la carpeta, sus datos también se pierden.

kubectl apply -k overlays/dev

Aplica con Kustomize (incluido en kubectl): una carpeta base con los manifiestos comunes y carpetas overlay que cambian solo lo que difiere por entorno (réplicas, imagen, namespace). -k apunta a la carpeta que tiene un kustomization.yaml.

Imperativo y generadores

kubectl create deployment chanchito --image=chanchito:1 --replicas=2

Crea un Deployment directamente con un comando (forma imperativa), sin escribir YAML. Sirve para probar rápido; en un proyecto conviene tenerlo en un archivo para poder versionarlo y repetirlo.

kubectl expose deployment chanchito --port=80 --target-port=3000

Crea un Service para ese Deployment: recibe en el puerto 80 y reenvía al 3000 de los Pods (donde escucha la app). Por defecto es de tipo ClusterIP, accesible solo dentro del cluster; agregá --type=NodePort para abrirlo en tu PC.

kubectl create deployment chanchito --image=chanchito:1 \
  --dry-run=client -o yaml > deployment.yaml

Truco: --dry-run=client no crea nada en el cluster y -o yaml imprime el manifiesto que hubiera creado; > lo guarda en un archivo. Así obtenés un YAML base correcto para editar en vez de escribirlo desde cero.

kubectl run tmp --rm -it --image=busybox -- sh

Crea un Pod temporal con busybox (una imagen mínima con herramientas de red) y te abre una terminal adentro. Sirve para probar desde el cluster si un Service responde o un nombre resuelve. --rm lo borra al salir con exit.

kubectl edit deploy chanchito

Abre el objeto en un editor de texto; al guardar y cerrar, el cambio se aplica al instante. Es cómodo para probar, pero el cambio no queda en tus archivos: el próximo apply lo pisa. Mejor editar el YAML y aplicar.

Borrar

kubectl delete pod <pod>

Borra un Pod. Si pertenece a un Deployment, este crea uno nuevo enseguida para mantener la cantidad de réplicas: en la práctica, funciona como “reiniciar ese Pod”. Para que no vuelva, hay que borrar o escalar el Deployment.

kubectl delete deploy chanchito
kubectl delete svc chanchito

Borra objetos indicando tipo y nombre. Al borrar un Deployment se borran también sus Pods; el Service es un objeto aparte y se borra por separado.

kubectl delete all -l app=chanchito

-l filtra por etiqueta (label): borra Pods, Services, Deployments y ReplicaSets que tengan app=chanchito. Igual que get all, no incluye ConfigMaps, Secrets ni PVC.

kubectl delete pod <pod> --grace-period=0 --force

Borra un Pod sin esperar a que termine ordenadamente. Solo para Pods trabados en Terminating durante minutos (por ejemplo, si se cayó el nodo). Usado en una base de datos, puede dejar datos a medio escribir.

Logs, entrar al Pod y acceder desde tu PC

Lo que más vas a usar para depurar.

Logs

kubectl logs <pod>

Muestra lo que el contenedor del Pod escribió en la consola (tus console.log y errores). Es lo primero que hay que mirar cuando un Pod no anda.

kubectl logs -f <pod>

-f (follow) sigue mostrando las líneas nuevas en vivo. Ctrl+C deja de mirar; el Pod sigue corriendo.

kubectl logs deploy/chanchito

Muestra los logs de uno de los Pods del Deployment sin tener que copiar el nombre largo del Pod. Si hay varias réplicas, elige una.

kubectl logs -l app=chanchito --tail=50

Muestra las últimas 50 líneas de todos los Pods que tengan la etiqueta app=chanchito. Agregá --prefix para ver de qué Pod viene cada línea.

kubectl logs <pod> --previous

Muestra los logs del contenedor anterior, el que se cayó antes del reinicio actual. Clave cuando un Pod está en CrashLoopBackOff: el contenedor nuevo todavía no escribió nada, pero el anterior tiene el error que lo hizo caer.

kubectl logs <pod> -c <contenedor>

Si el Pod tiene más de un contenedor, -c elige de cuál ver los logs (sin él, kubectl te pide que elijas). Los nombres están en kubectl describe pod.

Entrar y copiar

kubectl exec -it <pod> -- sh

Abre una terminal dentro del contenedor de un Pod que está corriendo. -it conecta tu teclado y el -- separa las opciones de kubectl del comando que se ejecuta adentro. Salís con exit.

kubectl exec -it deploy/monguito -- mongosh -u mati -p <password>

Abre la consola de MongoDB dentro del Pod de la base, eligiéndolo por su Deployment. Ahí podés escribir show dbs o consultar colecciones. Salís con exit.

kubectl cp <pod>:/home/app/log.txt ./log.txt

Copia archivos entre un Pod y tu PC, en cualquier dirección: primero el origen y después el destino; la parte del Pod se escribe pod:/ruta. Necesita que la imagen tenga el programa tar.

kubectl top pods
kubectl top nodes

Muestra cuánta CPU (en millicores: 100m = una décima de núcleo) y memoria usa cada Pod ahora. Requiere metrics-server, que Docker Desktop no trae instalado; sin él, da el error Metrics API not available.

Acceder desde tu PC

kubectl port-forward svc/chanchito 3000:80

Abre un túnel temporal: lo que entra por localhost:3000 en tu PC llega al puerto 80 del Service. El formato es tu PC:destino, como el -p de Docker. Queda corriendo mientras lo uses; Ctrl+C lo cierra.

kubectl port-forward svc/monguito 27017:27017

Lo mismo para la base: con el túnel abierto, MongoDB Compass o tu app local se conectan a localhost:27017 como si Mongo corriera en tu PC.

kubectl port-forward pod/<pod> 3000:3000

Túnel directo a un Pod concreto, sin pasar por el Service. Útil para probar una réplica específica o cuando el Service no funciona y querés descartar que el problema sea la app.

Queda corriendo en la terminal: Ctrl+C lo corta.

Escalar, actualizar y volver atrás

Un Deployment actualiza de a poco (rolling update): nunca te quedás sin Pods.

Rolling update de v1 a v2

kubectl set image deployment/chanchito chanchito=chanchito:2 (o cambiar la imagen en el YAML y apply)

v1 corriendo v2 terminando

Escalar

kubectl scale deploy chanchito --replicas=5

Cambia la cantidad de Pods que mantiene el Deployment: crea los que faltan o borra los que sobran. El cambio no queda en tu YAML; para que sea permanente, cambiá replicas: en el archivo.

kubectl autoscale deploy chanchito --min=2 --max=6 --cpu-percent=70

Crea un HorizontalPodAutoscaler (HPA): agrega Pods cuando el uso de CPU promedio supera el 70 % de lo pedido en resources.requests, y los quita cuando baja, siempre entre 2 y 6. Requiere metrics-server y que el contenedor declare requests de CPU.

kubectl get hpa

Muestra los autoscalers: el uso actual frente al objetivo (por ejemplo 45%/70%) y cuántas réplicas hay. Si dice <unknown>, falta metrics-server o los requests.

Actualizar y rollback

kubectl set image deployment/chanchito chanchito=chanchito:2

Cambia la imagen de un contenedor del Deployment. El formato es nombre-del-contenedor=imagen (el nombre es el de containers[].name en el YAML). Dispara un rolling update: reemplaza los Pods de a poco, sin cortar el servicio.

kubectl rollout status deploy/chanchito

Sigue el progreso de una actualización hasta que todos los Pods nuevos estén listos (successfully rolled out). Si se queda esperando, los Pods nuevos no arrancan: mirá get pods y sus logs.

kubectl rollout history deploy/chanchito

Lista las revisiones (versiones) que guardó el Deployment, numeradas. Cada cambio en el template del Pod (imagen, variables…) crea una revisión nueva.

kubectl rollout undo deploy/chanchito
kubectl rollout undo deploy/chanchito --to-revision=2

Vuelve a la revisión anterior, con otro rolling update. Con --to-revision=N vuelve a una revisión concreta de rollout history. Recordá corregir también tu YAML, o el próximo apply vuelve a poner la versión mala.

kubectl rollout restart deploy/chanchito

Reemplaza todos los Pods por Pods nuevos, de a poco y sin cortar el servicio, aunque no haya cambiado nada. Se usa después de cambiar un ConfigMap o un Secret, porque los Pods que ya corren no ven las variables nuevas.

Namespaces y labels

Organizar y filtrar.

Namespaces

kubectl get ns

Lista los namespaces: espacios separados dentro de un mismo cluster, para que proyectos o entornos no se mezclen. Siempre existen default (donde va lo tuyo si no indicás otro), kube-system (los componentes de Kubernetes) y kube-public.

kubectl create ns chanchito-dev

Crea un namespace nuevo. Los nombres de objetos solo tienen que ser únicos dentro de cada namespace: puede haber un Deployment chanchito en chanchito-dev y otro en chanchito-qa.

kubectl get pods -n chanchito-dev
kubectl apply -f k8s/ -n chanchito-dev

-n <namespace> funciona en cualquier comando para trabajar en ese namespace: listar, aplicar, borrar, ver logs. Sin -n, se usa el del contexto (normalmente default).

kubectl delete ns chanchito-dev

⚠ Borra el namespace y todo lo que hay adentro: Deployments, Services, Secrets, PVC con sus datos. No pide confirmación.

Labels

kubectl get pods --show-labels

Agrega una columna con las etiquetas (labels) de cada Pod: pares clave=valor que se ponen en metadata.labels y que usan los Services y Deployments para encontrar sus Pods.

kubectl get pods -l app=chanchito
kubectl get pods -l 'env in (dev,qa)'

-l filtra por etiqueta: solo los Pods con app=chanchito. La segunda forma elige varios valores. Es el mismo mecanismo (el selector) que usa un Service para saber a qué Pods mandar tráfico.

kubectl label pod <pod> env=dev
kubectl label pod <pod> env-

Agrega o cambia una etiqueta en un objeto existente; con - al final del nombre (env-) la quita. Si le sacás a un Pod la etiqueta que usa su Deployment, el Deployment deja de considerarlo suyo y crea otro.

Formatos de salida

Flag -o en cualquier get.

Tabla de -o

Flag	Qué muestra	Ejemplo
`-o wide`	Columnas extra (IP, nodo, imagen)	`kubectl get pods -o wide`
`-o yaml` / `-o json`	El objeto completo	`kubectl get svc chanchito -o yaml`
`-o name`	Solo `tipo/nombre` (para scripts)	`kubectl get pods -o name`
`-o jsonpath`	Un campo puntual	`kubectl get pod <pod> -o jsonpath='{.status.podIP}'`
`-o custom-columns`	Tus propias columnas	`-o custom-columns=NOMBRE:.metadata.name,IMG:.spec.containers[0].image`
`--sort-by`	Ordenar	`kubectl get pods --sort-by=.status.startTime`
`-w`	Seguir mostrando cambios	`kubectl get pods -w`

Secret decodificado (PowerShell): kubectl get secret mongo-secret -o jsonpath='{.data.MONGO_PASSWORD}' y después [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String("<valor>")).

Atajos y Helm

Para escribir menos.

Alias y autocompletado

# PowerShell ($PROFILE)
Set-Alias k kubectl
kubectl completion powershell | Out-String | Invoke-Expression

Crea el alias k para no escribir kubectl y activa el autocompletado con Tab (nombres de comandos, tipos y hasta nombres de Pods). Pegalo en tu perfil de PowerShell (notepad $PROFILE) para que se cargue en cada terminal nueva. Después: k get po.

# Bash / Git Bash (~/.bashrc)
alias k=kubectl
source <(kubectl completion bash)

Lo mismo para Bash o Git Bash: agregá esas líneas al final de ~/.bashrc y abrí una terminal nueva.

Nombres cortos: po pods · deploy · svc · ns · cm · pvc · ing · sts · no nodes.

Helm (gestor de paquetes)

helm repo add traefik https://traefik.github.io/charts
helm repo update

Helm es un gestor de paquetes para Kubernetes: un chart es un paquete con todos los manifiestos de una aplicación, listos para instalar. repo add registra un repositorio de charts con un nombre corto; repo update descarga la lista actualizada de lo que ofrece.

helm install traefik traefik/traefik -n traefik --create-namespace

Instala el chart traefik/traefik (repositorio/chart) con el nombre traefik, en el namespace traefik, creándolo si no existe. A cada instalación Helm la llama release. Traefik es un Ingress controller: el programa que hace funcionar los Ingress.

helm list -A
helm upgrade traefik traefik/traefik -n traefik -f values.yaml
helm uninstall traefik -n traefik

list muestra los releases instalados en todos los namespaces. upgrade actualiza uno, aplicando tus valores de configuración de values.yaml. uninstall lo borra con todo lo que había creado.

No hay comandos que coincidan con la búsqueda.