En la lección anterior usamos kubectl apply como si fuera un comando obvio y vimos manifiestos YAML de pasada, sin desmenuzarlos. Toca saldar esa deuda, porque el manifiesto es la unidad de trabajo real de Kubernetes: todo lo que despliegues durante los once módulos que quedan será un fichero YAML que describe un objeto. Esta lección te enseña la anatomía exacta de cualquier objeto de la API —los cuatro campos que siempre están, hagas lo que hagas—, cómo descubrir qué apiVersion corresponde a cada tipo, el subconjunto de YAML que necesitas dominar, la diferencia real entre apply, create y replace y por qué importa, cómo validar un manifiesto antes de aplicarlo, y cómo organizar los ficheros del proyecto Rutas Norte en el directorio k8s/ para que el repositorio sea la fuente de verdad.

1. Anatomía de un objeto de Kubernetes
2. Grupos, versiones y niveles de estabilidad de la API
3. El YAML que hace falta saber
4. Estado deseado y estado observado
5. apply frente a create y replace
6. Server-side apply y la propiedad de campos
7. Validar antes de aplicar
8. Organización de los manifiestos del proyecto

Absolutamente todos los objetos de Kubernetes —un pod, un secreto, un permiso RBAC, un CRD de un operador— comparten la misma estructura de cuatro campos de primer nivel. Aprender esa estructura una vez sirve para siempre.

Indica el grupo y la versión de la API que debe interpretar el objeto. Determina qué campos son válidos y cómo se comportan. Ejemplos: v1 (grupo core), apps/v1, networking.k8s.io/v1, batch/v1. Es el campo que más errores provoca cuando se copian manifiestos antiguos de internet.

El tipo concreto: Pod, Deployment, Service, Ingress, ConfigMap. Se escribe siempre en CamelCase, mientras que el recurso en la URL de la API va en minúsculas y plural (pods, deployments). La pareja apiVersion + kind identifica unívocamente el esquema del objeto.

La identidad del objeto. Sus campos más relevantes:

Un detalle que explica un comportamiento desconcertante: si un namespace o un PVC se queda "colgado" en estado Terminating, casi siempre es por un finalizer cuyo responsable no ha terminado su trabajo.

El estado deseado. Es lo que tú describes y su contenido depende por completo del kind: el spec de un Pod tiene containers, el de un Service tiene selector y ports, el de un PVC tiene resources.requests.storage. Todo el curso consiste, en el fondo, en aprender a escribir spec de distintos tipos.

No aparece en el manifiesto de arriba porque no lo escribes tú: lo escribe el clúster. Es el estado observado. Si consultas el objeto ya creado lo verás:

Fíjate en dos cosas. Primera: conditions es el formato estándar con el que Kubernetes expresa "cómo va" un objeto, y es lo que consultan kubectl wait y las herramientas de despliegue. Segunda: imageID contiene el digest real de la imagen que se está ejecutando, mientras que spec.image contiene la etiqueta que tú pediste. Cuando alguien reutiliza una etiqueta, esos dos valores dejan de corresponderse; volveremos a ello al hablar de etiquetas inmutables en la próxima lección.

La API de Kubernetes está dividida en grupos para poder evolucionar por partes y permitir extensiones.

El grupo core es el histórico y por eso su apiVersion no lleva prefijo: es v1, no core/v1. Todos los demás siguen el formato grupo/versión.

No hay que memorizar esta tabla: se consulta.

Este es el reflejo que hay que adquirir: antes de copiar un apiVersion de un blog, compruébalo con kubectl api-resources. La versión correcta es siempre la que tu clúster dice.

Kubernetes retira versiones antiguas con cada actualización, y ese es el motivo de que manifiestos copiados de tutoriales viejos fallen:

Grupo extensions/v1beta1 desapareció hace muchas versiones. Hoy un Deployment es apps/v1 y un Ingress es networking.k8s.io/v1, sin excepciones. Antes de actualizar un clúster, herramientas como kubent (kube-no-trouble) revisan tus manifiestos en busca de APIs a punto de retirarse.

YAML es simple pero tiene trampas. Este es el subconjunto que necesitas.

Reglas innegociables:

• Espacios, nunca tabuladores. Un tabulador es un error de sintaxis en YAML. Configura tu editor para expandir tabuladores a 2 espacios en ficheros .yaml.
• La indentación define la jerarquía. Dos espacios por nivel es la convención en Kubernetes.
• El guion - indica elemento de lista y su contenido se indenta al mismo nivel que el guion o más.

El caso NO es célebre (se conoce como the Norway problem): YAML 1.1 interpreta yes, no, on, off, y, n como booleanos. Regla práctica: en un ConfigMap o Secret, entrecomilla siempre los valores, porque esos campos exigen cadenas y un valor mal tipado produce un error tan claro como este:

Fundamentales para incrustar ficheros de configuración en un ConfigMap:

El separador --- permite poner varios objetos en un mismo fichero, y kubectl apply los procesa en orden:

Criterio recomendado: agrupa en un fichero los objetos que forman una unidad desplegable (un componente con su ConfigMap y su Service) y separa en ficheros distintos los componentes diferentes. Un único fichero gigante con toda la plataforma es difícil de revisar y de aplicar parcialmente.

Aquí es donde el modelo declarativo se vuelve concreto. Ya conoces el bucle de reconciliación de la lección Arquitectura de Kubernetes; veámoslo desde el punto de vista del fichero.

Cuatro consecuencias prácticas que conviene tener muy claras:

1. Tú escribes spec; el sistema escribe status. Editar un status a mano no sirve de nada: el controlador lo sobrescribirá en su siguiente ciclo.
2. Aplicar no es ejecutar. kubectl apply termina cuando el objeto está guardado, no cuando la aplicación está lista. Para esperar de verdad:

3. Es idempotente. Aplicar diez veces el mismo fichero da el mismo resultado que aplicarlo una. Esto es lo que hace posible que un pipeline de CI/CD ejecute kubectl apply en cada despliegue sin comprobar antes qué existe.

4. El fichero es la fuente de verdad, no el clúster. Si alguien cambia algo con kubectl edit, el siguiente apply desde el repositorio lo revierte. Esa es exactamente la propiedad sobre la que se construye GitOps (módulo 10).

Tres comandos que parecen intercambiables y no lo son en absoluto.

La conclusión operativa es simple: usa apply siempre. create sirve para comandos imperativos rápidos (kubectl create namespace) y replace para casos muy concretos de sustitución total.

Imagina que aplicas un pod con dos etiquetas, luego editas el fichero y dejas solo una, y vuelves a aplicar. ¿Cómo sabe kubectl que debe eliminar la segunda etiqueta, en lugar de dejarla porque "no está en el fichero pero tampoco he pedido borrarla"?

La respuesta clásica es que apply guarda una copia de lo último que aplicaste en una anotación:

Con esa información, kubectl hace una fusión de tres vías: compara (a) lo que aplicaste la última vez, (b) lo que aplicas ahora y (c) lo que hay en el clúster. Lo que estaba en (a) y desaparece en (b) se borra; lo que solo está en (c) —porque lo puso un controlador o un webhook— se respeta.

Esto explica un error frecuente: si creaste un objeto con kubectl create y después lo modificas con apply, no existe la anotación de referencia y kubectl avisa de que la fusión puede ser incorrecta. Por coherencia, usa apply desde el principio de la vida de cada objeto.

Desde Kubernetes 1.22, la fusión puede hacerla el servidor en lugar del cliente, y es el mecanismo hacia el que se está migrando todo el ecosistema.

La diferencia es conceptual: en lugar de una anotación con el último estado, el servidor registra qué gestor es propietario de cada campo en metadata.managedFields.

Ventajas frente a la fusión en cliente:

• Detecta conflictos. Si intentas modificar un campo que pertenece a otro gestor (un HPA que controla replicas, por ejemplo), la petición falla con un aviso claro en lugar de provocar una pelea silenciosa entre herramientas:

Si de verdad quieres apropiarte del campo, se fuerza explícitamente:

• No depende de una anotación que en objetos grandes puede ser enorme.
• Varios gestores pueden coexistir sobre el mismo objeto de forma ordenada: tu pipeline, un operador y un autoescalador, cada uno dueño de sus campos.

Para el curso seguiremos usando kubectl apply a secas, que es lo habitual, pero conviene que reconozcas managedFields cuando aparezca en un -o yaml y que sepas qué significa un error de conflicto.

Aplicar sin comprobar es la receta del incidente. Kubernetes ofrece cuatro niveles de verificación, de más barato a más completo.

kubectl construye el objeto y valida el esquema sin enviar nada. Detecta errores de sintaxis YAML y campos inexistentes. No detecta problemas de permisos, cuotas ni webhooks. Es también la bandera que usamos en la lección anterior para generar manifiestos:

La petición sí llega al apiserver y recorre todo el camino de la lección 01-02 —autenticación, autorización RBAC, admisión, validación— pero no se escribe en etcd. Detecta lo que el cliente no puede ver: falta de permisos, cuotas superadas, políticas de seguridad de pods, webhooks de admisión propios. Es la validación que debe ejecutar tu pipeline de CI antes de desplegar.

Este es el comando que convierte un despliegue en algo revisable: te dice exactamente qué va a cambiar en el clúster antes de cambiarlo. Debería ser un paso obligatorio en cualquier despliegue manual a producción. Su código de salida es distinto de cero cuando hay diferencias, lo que permite usarlo en scripts.

Ya lo vimos en la lección anterior; aquí conviene subrayar que es la respuesta correcta a "¿existe este campo y qué tipo tiene?" cuando estás escribiendo un manifiesto.

Los manifiestos de Rutas Norte viven en el directorio k8s/ del repositorio del proyecto, versionados en Git. Esta es la estructura que usaremos durante todo el curso:

Convenciones que seguiremos:

Sobre el orden: aplicar un directorio completo funciona porque el modelo es reconciliador —un pod que no encuentra su ConfigMap se queda esperando y arranca cuando aparece—, pero para evitar errores transitorios conviene aplicar primero el namespace:

Un aviso importante para no invadir módulos posteriores: esta estructura de base/ y entornos/ es deliberadamente YAML plano, sin plantillas. Cuando la duplicación entre entornos se vuelva molesta, existen dos soluciones estándar —Helm (plantillas y empaquetado) y Kustomize (superposiciones sin plantillas)— que se estudian en las lecciones Helm y Kustomize. Aprender primero el YAML plano no es tiempo perdido: es lo que te permitirá entender qué generan esas herramientas.

• Usar tabuladores en YAML. Error de sintaxis puro. Configura el editor: expandtab, 2 espacios, y una extensión de YAML que valide al guardar.
• Copiar apiVersion de tutoriales antiguos. extensions/v1beta1 y apps/v1beta2 no existen. Verifica siempre con kubectl api-resources.
• Confundir el nombre del kind con el del recurso. kind: Deployment (CamelCase, singular) en el YAML; kubectl get deployments (minúsculas, plural) en la CLI.
• Valores sin comillar en ConfigMaps y Secrets. "3", "true", "NO". Esos campos exigen cadenas y YAML convierte tipos alegremente.
• Editar el status a mano. No tiene ningún efecto: lo escribe el controlador.
• Mezclar create y apply sobre el mismo objeto. Sin la anotación last-applied, la fusión puede comportarse de forma inesperada. Empieza siempre con apply.
• Aplicar sin diff en producción. kubectl diff cuesta dos segundos y evita despliegues sorpresa.
• Guardar un -o yaml como manifiesto. La salida del clúster incluye status, uid, resourceVersion, managedFields y creationTimestamp, que no deben versionarse. Límpialo (a mano o con el plugin kubectl neat) antes de guardarlo en k8s/.
• Consejo: trata el directorio k8s/ como código. Revisión por pull request, validación en CI con --dry-run=server, y la regla de oro: si un cambio no está en Git, no existe.

1. Escribe el manifiesto de un ConfigMap llamado tienda-web-config en el namespace rutas-norte-dev, con las etiquetas del proyecto y dos claves: api_url con valor http://api-reservas y modo_mantenimiento con valor "NO". Explica por qué el segundo valor necesita comillas.
2. Averigua con kubectl, sin buscar en internet, a qué apiVersion pertenecen CronJob, Ingress y HorizontalPodAutoscaler, y cuáles de ellos son de ámbito de namespace.
3. Comprueba con kubectl explain si el campo spec.containers.imagePullPolicy existe en un Pod y qué valores admite.

Partiendo del manifiesto del pod api-reservas de la sección 1:

1. Valídalo en local sin tocar el clúster.
2. Aplícalo, y aplícalo otra vez sin cambiar nada. ¿Qué dice kubectl la segunda vez y por qué?
3. Cambia la imagen a la versión 2.5.0 en el fichero y, antes de aplicar, muestra exactamente qué cambiaría en el clúster.
4. Muestra el status.phase y la IP del pod usando jsonpath.
5. Explica qué diferencia habría si en el paso 2 hubieras usado kubectl create en lugar de apply.

Crea el fichero k8s/base/redis-cache.yaml que contenga, en un solo fichero y en el orden correcto, tres objetos:

1. Un ConfigMap redis-cache-config con una clave redis.conf que contenga varias líneas de configuración (usa el indicador literal).
2. Un Pod redis-cache con la imagen redis:7.2-alpine.
3. Todo ello en rutas-norte-dev, con las etiquetas del proyecto.

Después, indica qué comando aplicaría el directorio completo y por qué conviene aplicar antes namespace.yaml.

Solución 1

"NO" necesita comillas porque YAML 1.1 interpreta NO (igual que no, yes, on, off) como el booleano false. El campo data de un ConfigMap solo admite cadenas, así que sin comillas el apiserver rechazaría el objeto con un error de tipo.

Los tres son de ámbito de namespace (NAMESPACED = true).

Solución 2

En el paso 2, la segunda ejecución dice unchanged porque apply es idempotente: kubectl compara la anotación last-applied-configuration, el fichero actual y el objeto vivo, no encuentra diferencias y no envía ninguna modificación. Esa propiedad es la que permite ejecutar apply en cada despliegue de un pipeline sin efectos secundarios.

Con kubectl create en el paso 2, la primera vez habría funcionado y la segunda habría fallado con Error from server (AlreadyExists), porque create no fusiona: solo sabe crear objetos nuevos.

Solución 3

El ConfigMap va primero porque el pod lo consumirá y así se evita un error transitorio. Conviene aplicar namespace.yaml por separado y antes porque todos los demás objetos declaran namespace: rutas-norte-dev y, si ese namespace todavía no existe, sus creaciones fallan con namespaces "rutas-norte-dev" not found. El namespace es la única dependencia dura del conjunto.

Ya dominas la unidad de trabajo de Kubernetes. Todo objeto tiene la misma anatomía —apiVersion, kind, metadata, spec que escribes tú y status que escribe el clúster—, pertenece a un grupo de API cuya versión debes verificar en tu propio clúster con kubectl api-resources, y se expresa en un YAML con reglas estrictas sobre indentación, tipos y cadenas multilínea. Has visto por qué apply es superior a create y replace, cómo funciona la fusión de tres vías y su anotación last-applied, hacia dónde evoluciona el modelo con server-side apply y la propiedad de campos, y qué secuencia de validación —--dry-run=client, --dry-run=server, kubectl diff, kubectl explain— convierte un despliegue en algo predecible. Y tienes la estructura del directorio k8s/ que sostendrá el proyecto durante el resto del curso.

Tienes clúster, tienes CLI y tienes el lenguaje de los manifiestos. Solo falta el paciente. En la siguiente lección, El Proyecto del Curso: la Plataforma Rutas Norte, conocerás en detalle la empresa, cada uno de los seis componentes de la plataforma, la arquitectura objetivo y las convenciones del proyecto; y terminarás desplegando de verdad tu primer trozo de Rutas Norte en el clúster, viéndolo funcionar en tu navegador.