Todo lo que creas en Kubernetes es un objeto descrito en un manifiesto, un archivo YAML que dice lo que quieres. Esta guía cubre el YAML justo para poder leer uno, explica la estructura que comparten todos los manifiestos y recorre la ejecución de un Pod desde un archivo. Asume que tienes un clúster funcionando (consulta la guía anterior).

YAML en cinco minutos

YAML tiene dos bloques de construcción que necesitas reconocer.

Un mapa es un conjunto de pares clave: valor. La indentación muestra el anidamiento, y todo lo que está indentado bajo una clave le pertenece. Una lista es una serie de elementos, cada uno empezando con un guion:

app:
  name: shop
  enabled: true
  labels:
    tier: frontend
  ports:
    - 80
    - 443

Aquí app es un mapa con las claves name, enabled, labels y ports. labels es a su vez un mapa y ports es una lista de dos números. Usa espacios, nunca tabuladores. La indentación incorrecta es la causa más común de un manifiesto que no se aplica, y cambia en silencio qué pertenece a qué. Varios objetos pueden compartir un archivo si los separas con una línea que contenga ---.

Anatomía de un manifiesto

Todo objeto de Kubernetes tiene los mismos campos de nivel superior:

• apiVersion indica qué versión de la API define este tipo de objeto.
• kind es el tipo de objeto, como Pod o Deployment. Distingue mayúsculas de minúsculas.
• metadata identifica el objeto: su name, opcionalmente un namespace y cualquier labels y annotations.
• spec es el estado deseado, y su contenido depende del tipo.

Kubernetes añade una cuarta sección, status, que describe el estado real. No la escribes tú. Este es un Pod mínimo:

apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
spec:
  containers:
    - name: nginx
      image: nginx:1.25
      ports:
        - containerPort: 80

containers es una lista, así que un Pod podría ejecutar varios contenedores, cada uno empezando con su propio guion. El campo image es el que conviene revisar dos veces. Un error tipográfico significa que Kubernetes no puede descargarla y el Pod se quedará en un estado de error.

No escribas manifiestos desde cero

Copia un ejemplo funcional de la documentación de Kubernetes o haz que kubectl genere uno:

kubectl run web --image=nginx:1.25 --port=80 --dry-run=client -o yaml > pod.yaml

--dry-run=client construye el objeto en local sin crearlo, y -o yaml lo imprime como YAML. Eso te da un punto de partida válido para editar.

Acierta con el apiVersion

Distintos tipos viven en distintos grupos y versiones de la API. Los Pods son v1, los Deployments son apps/v1, los Ingresses son networking.k8s.io/v1. Si eliges el incorrecto, o usas una versión que un clúster más nuevo ha eliminado, obtienes un error como no matches for kind "X" in version "Y". Para encontrar el valor correcto:

kubectl api-resources | grep -i deployment
kubectl explain deployment | head

El primero muestra el grupo de cada tipo, y el segundo muestra su VERSION. Esto importa sobre todo cuando actualizas un clúster, porque los manifiestos antiguos pueden dejar de funcionar cuando se elimina una versión. La guía de deprecaciones de Kubernetes enumera lo que cambió en cada versión.

Crea, inspecciona y elimina

kubectl apply -f pod.yaml
kubectl get pods
kubectl describe pod web
kubectl delete -f pod.yaml

En kubectl get pods, la columna READY muestra cuántos de los contenedores del Pod están listos (1/1 es sano), STATUS muestra su fase y RESTARTS cuenta los reinicios de contenedores. Un número que sigue subiendo significa que algo sigue matando el contenedor. describe imprime todos los detalles del Pod, con los eventos recientes al final, que es el primer lugar donde mirar cuando algo va mal.

apply es declarativo: crea el objeto si no existe y lo actualiza si existe, así que puedes editar el archivo y volver a aplicar. kubectl create -f falla si el objeto ya existe.

Imperativo vs declarativo

Comandos como kubectl run y kubectl create son imperativos: le dices a Kubernetes que haga algo ahora. Son rápidos para experimentos y para exámenes de certificación. Los manifiestos aplicados con kubectl apply -f son declarativos, y eso es lo que quieres para cualquier cosa real, porque los archivos pueden vivir en Git, revisarse y volver a aplicarse. Las guías de Argo CD de esta serie muestran cómo llevar esa idea hasta su conclusión.