La lección anterior terminó con una lista honesta de los defectos de Helm: las plantillas dejan de ser YAML válido, nindent y los espacios en blanco son una fuente constante de errores, y hace falta aprender el motor de plantillas de Go antes de poder tocar nada. Kustomize nace precisamente de ese descontento y parte de una premisa opuesta: no usar plantillas en absoluto.

En Kustomize, tus manifiestos siguen siendo YAML de Kubernetes perfectamente válido. Puedes abrirlos en el editor y que te valide el esquema, aplicarlos con kubectl apply -f, y leerlos sin descifrar nada. Lo que cambia entre entornos no se expresa con variables, sino con superposiciones: pequeños ficheros que declaran las diferencias respecto a una base común.

En esta lección migraremos el k8s/ de Rutas Norte de 120 ficheros duplicados a una base más tres superposiciones, resolveremos de forma limpia el problema del reinicio ante cambios de configuración que en 03-03 arreglábamos con una anotación a mano, y terminaremos comparando Helm y Kustomize sin favoritismos.

1. La filosofía sin plantillas
2. Kustomize dentro de kubectl y como binario propio
3. El modelo base + superposiciones
4. kustomization.yaml campo a campo
5. Parches: fusión estratégica y JSON Patch
6. Generadores de ConfigMaps y Secrets
7. Componentes: trozos opcionales reutilizables
8. Flujo de trabajo: kustomize, diff y apply
9. Migración completa de Rutas Norte
10. Helm frente a Kustomize
11. Combinar Helm y Kustomize
12. Errores comunes y consejos
13. Ejercicios
14. Conclusión

Compara los dos enfoques para el mismo objetivo: que api-reservas tenga 1 réplica en desarrollo y 4 en producción.

Con Helm, el manifiesto deja de ser YAML de Kubernetes: replicas: {{ .Values.apiReservas.replicaCount }}, image: {{ .Values.imageRegistry }}/api-reservas:{{ .Values.apiReservas.image.tag }}. Con Kustomize, la base es YAML normal y corriente (replicas: 1, image: registry.rutasnorte.example/api-reservas:2.4.0), aplicable con kubectl apply -f, y la superposición declara las diferencias:

Kustomize funciona como una canalización de transformaciones: lee los manifiestos base, aplica una serie de operaciones declaradas (cambiar el namespace, añadir etiquetas, sustituir la imagen, aplicar parches) y emite el YAML resultante.

Esa naturaleza de "transformar YAML existente" tiene una consecuencia elegante: Kustomize entiende los tipos de Kubernetes. Cuando fusiona dos listas de contenedores sabe que la clave de correlación es name; cuando cambia una imagen sabe dónde están los campos image en un Deployment, un StatefulSet, un CronJob o un DaemonSet. Helm, que solo concatena texto, no sabe nada de eso.

Ventaja enorme: no hay nada que instalar. Cualquiera con kubectl puede desplegar. Desventaja: la versión integrada va por detrás de la independiente y no se puede actualizar sin actualizar kubectl.

Recomendación para Rutas Norte: kubectl -k para el uso interactivo diario; el binario con versión fijada en la canalización ci-rutasnorte, para que todo el mundo genere exactamente el mismo YAML.

Tres conceptos:

• Base: los manifiestos comunes. Debe ser desplegable por sí sola y contiene los valores más conservadores.
• Superposición (overlay): un directorio que referencia una base y declara las diferencias. Una por entorno.
• Componente: un trozo reutilizable que las superposiciones activan opcionalmente.

Fíjate en que este fichero es directamente aplicable con kubectl apply -f. Eso no lo puedes hacer con una plantilla de Helm: es la ventaja principal del enfoque.

Y la superposición de desarrollo son once líneas:

Ficheros, directorios con su propio kustomization.yaml, o URL remotas:

Sobre los recursos remotos: fija siempre ?ref= a una etiqueta o commit. Sin eso apuntas a la rama principal y tu despliegue cambia cuando alguien ajeno hace un commit. Es el mismo principio que --version en Helm y las etiquetas inmutables de imagen (08-05).

namespace: rutas-norte-pro establece metadata.namespace en todos los objetos generados y actualiza las referencias cruzadas (el namespace de un subjects de RoleBinding, por ejemplo). Un solo campo elimina la principal duplicación entre entornos. Los objetos de ámbito de clúster (ClusterRole, StorageClass, CRD) no se ven afectados: Kustomize lo sabe.

namePrefix: rn- y nameSuffix: -pro renombran los objetos, y —muy importante— Kustomize actualiza las referencias: el scaleTargetRef del HPA, el serviceName del StatefulSet, el name del ConfigMap en envFrom, el backend.service.name del Ingress. Rutas Norte no los usa, porque ya separa entornos por namespace y añadir -pro al nombre de todo complica las órdenes de diagnóstico; son útiles cuando despliegas dos instancias en el mismo namespace.

Este apartado merece atención especial porque es una trampa real que rompe despliegues.

commonLabels (la forma antigua) añade las etiquetas a metadata.labels y también a spec.selector.matchLabels del Deployment, a spec.template.metadata.labels del pod y a spec.selector del Service. Y ahí está el problema: spec.selector de un Deployment es inmutable (02-03, 02-07). Si la base ya está desplegada y añades una etiqueta, el siguiente apply falla:

La única salida es borrar el Deployment y recrearlo, con corte de servicio. En rutas-norte-pro, a las once de la mañana.

Hay un segundo problema, más sutil: si añade entorno: pro al selector del Service, ese Service dejará de encontrar los pods que ya existían sin esa etiqueta. Tráfico a ninguna parte, sin ningún error visible.

Regla de Rutas Norte: las etiquetas de selector se definen una vez en la base (app: api-reservas) y no se tocan nunca. Todo lo demás se añade con includeSelectors: false.

Kustomize busca el campo image en cualquier tipo que lo tenga, incluidos los initContainers. No hay que decirle dónde mirar. Esto es lo que la canalización ci-rutasnorte modifica en cada despliegue:

kustomize edit modifica el kustomization.yaml en el disco. Combinado con un commit automático, es la pieza que conecta la construcción de la imagen con GitOps (10-05).

Ahorra escribir un parche para algo tan común. Pero atención, retomando 09-01: si api-reservas tiene un HPA, declarar replicas aquí es contraproducente. Cada kubectl apply -k devolverá el Deployment a 4 réplicas aunque el HPA lo tenga en 15 por la carga del puente de mayo, con un bajón de capacidad hasta que el HPA reaccione.

Para componentes con HPA, la solución correcta es no declarar replicas en ninguna parte (ni en la base ni en la superposición) y dejar que minReplicas del HPA gobierne. Kubernetes no exige el campo: por defecto vale 1 y el HPA lo sube inmediatamente. La pieza que falta —que Argo CD no marque deriva cuando el HPA cambie ese campo— la resolveremos en 10-05 con ignoreDifferences.

Los campos anteriores cubren lo habitual. Para todo lo demás, hay parches.

Escribes un YAML parcial con la misma estructura del objeto. Kustomize lo fusiona entendiendo la semántica de los tipos de Kubernetes.

Lo que hace especial a la fusión estratégica es que Kustomize conoce el esquema: sabe que containers se correlaciona por name, ports por containerPort, volumeMounts por mountPath. Un parche que solo menciona el contenedor api deja intactos los sidecars.

Se puede escribir en línea con patch: |- dentro del kustomization.yaml, útil para cambios pequeños. Y hay dos directivas especiales: $patch: replace sustituye una lista entera en vez de fusionarla, y $patch: delete elimina el elemento que coincida.

Cuando la fusión estratégica no llega —porque hay que operar sobre índices de lista, o sobre un CRD que Kustomize no conoce— se usa JSON Patch: una lista de operaciones explícitas.

Detalles que hay que conocer: las rutas empiezan en la raíz del objeto y los índices de lista son numéricos (/spec/template/spec/containers/0/); replace falla si la ruta no existe, mientras que add la crea o la sustituye, así que ante la duda usa add.

Aquí está la potencia real del sistema. Un parche puede dirigirse a muchos objetos a la vez.

Los selectores disponibles en target son kind, name (exacto o regex), namespace, group, version, labelSelector y annotationSelector.

Verás mucho código antiguo con esos dos campos. El campo unificado patches reemplaza a ambos: detecta automáticamente si el contenido es una fusión estratégica o un JSON Patch, y admite target con selectores en los dos casos, que los antiguos no permitían.

kustomize edit fix migra los campos obsoletos automáticamente.

Esta es la funcionalidad más elegante de Kustomize, y resuelve limpiamente un problema que en 03-03 solucionábamos a mano.

Kustomize añade un hash del contenido al nombre. Y —esto es lo importante— actualiza automáticamente todas las referencias, así que el Deployment queda con configMapRef: { name: api-reservas-config-9t2hmf6b4d }.

Piensa en lo que implica. Cuando cambias LOG_LEVEL de info a warn: cambia el contenido → cambia el hash → cambia la referencia en el Deployment → cambia la plantilla del pod → el Deployment hace un rollout automáticamente.

Esto resuelve, de forma nativa y sin trucos, el problema de 03-03. Allí explicamos que un ConfigMap actualizado no reinicia los pods y que el apaño era añadir a mano una anotación con el hash. Con Kustomize no hay apaño: es el comportamiento por defecto. Y comparado con Helm (10-03), donde había que escribir checksum/config: {{ include ... | sha256sum }} en cada plantilla, aquí no escribes nada.

Ventaja adicional: el rollback funciona de verdad. Como cada versión de la configuración es un objeto distinto con nombre distinto, un kubectl rollout undo devuelve el pod a la referencia anterior, y el ConfigMap viejo sigue existiendo mientras algún ReplicaSet lo referencie. Con un ConfigMap de nombre fijo, el rollback devolvería el código viejo pero con la configuración nueva: lo peor de ambos mundos.

También por generador, con options: { disableNameSuffixHash: true } dentro de una entrada concreta.

¿Cuándo desactivarlo? Solo cuando algo externo referencia el ConfigMap por un nombre fijo que Kustomize no puede actualizar: un CRD de un operador que Kustomize no sabe interpretar, un pod que relee el ConfigMap en caliente a propósito, o uno compartido entre aplicaciones gestionadas por sistemas distintos. Consejo firme: no lo desactives sin una razón concreta. El hash es la mejor característica de Kustomize.

Si la base define api-reservas-config con LOG_LEVEL=info, RESERVA_TTL_MINUTOS=15 y CACHE_HOST=redis-cache, y la superposición de producción declara:

El resultado combina las tres claves heredadas con LOG_LEVEL sobreescrito y PASARELA_URL añadida.

Misma mecánica, con codificación base64 automática y soporte de type: kubernetes.io/tls para certificados desde ficheros.

Advertencia crítica: secretGenerator no cifra nada. Base64 no es cifrado (03-02). Si pones la contraseña de postgres-reservas en un literals o en un fichero del repositorio, esa contraseña está en claro en Git para siempre, incluso si luego la borras.

La forma correcta en Rutas Norte, retomando lo anunciado en 03-02, es referenciar un Secret cifrado con SOPS o Sealed Secrets, o mejor aún un recurso del External Secrets Operator que va a buscar el valor a Vault:

Ese fichero es inocuo: solo dice dónde está el secreto, no cuál es. Volveremos a ello en 10-05.

Un componente es como una superposición, pero pensado para ser incluido por varias. Resuelve el caso "esto lo quiero en pre y en pro, pero no en dev". Rutas Norte tiene tres candidatos claros: las NetworkPolicies (04-06), la alta disponibilidad (09-05) y la observabilidad (07-03). En desarrollo estorban; en los otros dos entornos son obligatorios.

Un componente puede tener también parches, no solo recursos:

Y las superposiciones lo activan: dev no lleva ninguno, pre lleva politicas-red y observabilidad, y pro añade además alta-disponibilidad.

Los componentes se aplican en el orden en que aparecen, después de los resources. Si dos parchean el mismo campo, gana el último.

Esa salida cuenta exactamente lo que va a pasar: cambia el hash de la configuración (habrá rollout) y sube el límite de memoria. Es el equivalente a helm diff de la lección anterior, pero integrado en kubectl, sin plugins.

Un problema real: si borras un manifiesto del repositorio, kubectl apply -k no borra el objeto del clúster. Se queda huérfano. Existe --prune con --applyset y --prune-allowlist, pero es engorroso y hay que enumerar los tipos. Es otro de los problemas que GitOps (10-05) resuelve de forma nativa: Argo CD y Flux saben qué objetos les pertenecen y los podan solos.

Y lo importante no es el número de ficheros, sino que cada línea de configuración existe una sola vez.

Paso 1: elegir la base. El entorno más simple, normalmente dev. Copiar sus manifiestos a k8s/base/, quitándoles el namespace (lo pondrá la superposición) con yq -i 'del(.metadata.namespace)' k8s/base/**/*.yaml.

Paso 2: escribir los kustomization.yaml de la base (apartado 3).

Paso 3: calcular el diferencial real de cada entorno.

Cuatro diferencias. Tres se resuelven con campos de kustomization.yaml (namespace, replicas, images) y solo una necesita parche (resources).

Paso 4: escribir las superposiciones.

Paso 5: verificar que la migración no cambia nada. Este es el paso que da confianza.

Un diff vacío significa que puedes hacer kubectl apply -k y no pasará absolutamente nada. La migración es una operación sin riesgo.

Paso 6: borrar los directorios viejos con git rm -r k8s/dev k8s/pre k8s/pro y actualizar la canalización.

Helm para consumir, Kustomize para producir. Es la decisión de Rutas Norte y la de la mayoría de equipos maduros: nadie quiere mantener a mano los 60 objetos de kube-prometheus-stack, y nadie quiere convertir su propio Deployment en una plantilla ilegible. La excepción: si distribuyes tu software a clientes que lo instalan en sus clústeres, necesitas un paquete versionado y configurable, y ahí Helm no tiene rival.

Hay dos formas de usar las dos herramientas juntas, y sirven para lo mismo: modificar un chart de terceros en un campo que su autor no parametrizó.

Un solo fichero declara todo y actualizar es cambiar el número de versión, pero necesita --enable-helm y tener helm instalado, el resultado no está en Git, y el soporte es desigual (kubectl -k no lo admite bien; Argo CD y Flux requieren configuración extra).

Recomendación para Rutas Norte: la forma A. Tener el YAML generado en Git es exactamente lo que hace que GitOps funcione bien: cualquiera puede leer el repositorio y saber qué hay desplegado.

1. Usar commonLabels (o labels con includeSelectors: true) sobre algo ya desplegado. Modifica spec.selector, que es inmutable, y el apply falla. La única salida es borrar y recrear, con corte de servicio. Usa siempre includeSelectors: false.

2. Declarar replicas en un componente con HPA. Cada apply deshace el escalado automático hasta que el HPA reacciona. Para lo que tenga HPA, no declares replicas en ningún sitio.

3. Secretos en secretGenerator con literals. Base64 no es cifrado. Si escribes la contraseña de postgres-reservas en un fichero del repositorio, está en claro en el historial de Git para siempre. Usa SOPS, Sealed Secrets o External Secrets Operator.

4. Desactivar disableNameSuffixHash sin necesidad. Pierdes el rollout automático al cambiar la configuración, que es la mejor característica de Kustomize.

5. Recursos remotos sin ?ref=. Tu despliegue cambia cuando un desconocido hace un commit. Fija siempre etiqueta o commit.

6. Poner demasiado en la base. Si la base contiene cosas que la mitad de los entornos tienen que parchear para quitar, está mal diseñada. La base es el mínimo común; lo opcional va en componentes.

7. Cadenas de superposiciones muy profundas. Base → común → región → entorno → cliente es técnicamente posible y humanamente impracticable: nadie sabe de dónde sale un valor. Dos niveles, tres como mucho.

8. Parche que no se aplica y nadie se entera. Si el target no casa con nada, Kustomize no siempre avisa. Verifica siempre con kubectl kustomize que el cambio aparece en la salida.

9. replace en un JSON Patch sobre una ruta que no existe. Falla con "missing value". Usa add, que crea o sustituye.

10. Olvidar escapar / en las claves de un JSON Patch. rutasnorte.example/revision se escribe rutasnorte.example~1revision.

11. Aplicar sin kubectl diff -k antes. Es gratis, tarda dos segundos y te enseña exactamente qué va a cambiar. En producción debería ser obligatorio.

12. Suponer que las listas se fusionan siempre. En la fusión estratégica, las listas con clave de correlación conocida (containers por name) se fusionan; las que no la tienen (args, command) se sustituyen enteras.

13. Editar objetos a mano con kubectl edit y olvidarlo. Kustomize no reconcilia: solo actúa cuando alguien ejecuta apply. El siguiente despliegue pisará el cambio manual sin avisar. Este es exactamente el problema que resuelve GitOps.

Partiendo de la base descrita en la lección, escribe k8s/entornos/pre/kustomization.yaml que: use el namespace rutas-norte-pre, etiquete todo con entorno: pre sin tocar los selectores, fije las imágenes a rc-2.4.0, active los componentes de políticas de red y observabilidad, fusione un ConfigMap con LOG_LEVEL=info y una URL de pasarela de pruebas, y aplique un parche que suba los recursos a la mitad de los de producción. Verifica el resultado sin aplicar nada.

Escribe un parche que añada a todos los Deployments etiquetados con app.kubernetes.io/part-of: rutas-norte un initContainer que espere a que postgres-reservas esté accesible antes de arrancar (06-04), sin modificar ningún fichero de la base. Explica por qué necesitas JSON Patch y no fusión estratégica.

Con la superposición de dev desplegada, demuestra en tres pasos que cambiar una línea de config.env provoca un rollout automático: captura el nombre del ConfigMap y la generación del Deployment antes, cambia el valor, aplica, y compara. Explica por qué esto no ocurriría con un ConfigMap de nombre fijo.

Solución 1

Solución 2

Nota: la primera operación vaciaría una lista initContainers ya existente. Si algunos Deployments ya tienen init containers que hay que conservar, la solución robusta es separar en dos parches con target distintos.

Por qué JSON Patch: la fusión estratégica exige un fichero por objeto con su metadata.name exacto, así que no puede dirigirse a "todos los que casen con una etiqueta". JSON Patch combinado con labelSelector en target alcanza N objetos con una sola declaración, y /- permite añadir al final sin conocer cuántos elementos había.

Solución 3

Explicación: el hash forma parte del nombre del ConfigMap, y ese nombre aparece dentro de spec.template del Deployment. Al cambiar la plantilla del pod, el controlador crea un ReplicaSet nuevo y ejecuta el despliegue gradual (02-03).

Por qué no ocurriría con nombre fijo: spec.template seguiría siendo byte a byte idéntico, metadata.generation no cambiaría, y no habría ReplicaSet nuevo. Los pods seguirían con las variables viejas hasta que alguien ejecutara kubectl rollout restart a mano. Ese es justamente el apaño de la anotación checksum/config de 03-03, que aquí no hace falta.

Kustomize ha reducido el k8s/ de Rutas Norte de 114 ficheros duplicados a 43, con cada valor definido una sola vez. Lo esencial:

• Sin plantillas: los manifiestos de k8s/base/ siguen siendo YAML de Kubernetes válido, aplicable con kubectl apply -f y validable por el editor. Lo que cambia entre entornos se declara como transformaciones en la superposición.
• Viene en kubectl (apply -k, diff -k, kubectl kustomize), aunque el binario propio va más al día y es el que conviene fijar en la canalización.
• El modelo base + superposiciones + componentes cubre los tres ejes reales: lo común, lo propio de cada entorno, y las capacidades opcionales que solo quieren algunos entornos.
• namespace, images, replicas y labels resuelven la mayoría de diferencias sin escribir un parche. Y labels debe llevar includeSelectors: false: commonLabels toca los selectores inmutables y rompe despliegues en marcha.
• Para lo demás hay patches, con fusión estratégica o JSON Patch, y un target dirigible por tipo, nombre, etiqueta o anotación. patchesStrategicMerge y patchesJson6902 están obsoletos.
• Los generadores con su sufijo de hash son la joya: cambiar una línea de configuración cambia el nombre del ConfigMap, cambia la plantilla del pod y provoca un rollout automático. Resuelve de forma nativa lo que en 03-03 arreglábamos a mano, y además hace que el rollback devuelva código y configuración a la vez.
• Y en la comparación honesta con Helm, la regla es clara: Helm para consumir software de terceros, Kustomize para las aplicaciones propias, con dos formas de combinarlos cuando hace falta parchear un chart ajeno.

Pero queda un problema que ni Helm ni Kustomize resuelven, y que ha aparecido en las dos lecciones. Ambas herramientas solo actúan cuando alguien ejecuta una orden. Si alguien hace kubectl edit en producción, ninguna se entera. Si el portátil de quien despliega se estropea, nadie sabe desplegar. Si la canalización ci-rutasnorte necesita credenciales de administrador del clúster para ejecutar kubectl apply, tenemos un problema de seguridad serio que contradice el RBAC mínimo que definimos en 08-01.

En la siguiente lección, GitOps con Argo CD y Flux, damos el paso final: un agente que vive dentro del clúster, tira de Git continuamente y reconcilia la realidad con lo declarado. Veremos el recurso Application de Argo CD, los ApplicationSet para desplegar los tres entornos desde una sola definición, el equivalente en Flux, las tres soluciones al problema de los secretos en un repositorio, y por fin cerraremos el conflicto entre el HPA y el campo replicas que dejamos anunciado en 09-01.