La lliçó anterior va acabar amb una llista honesta dels defectes de Helm: les plantilles deixen de ser YAML vàlid, nindent i els espais en blanc són una font constant d'errors, i cal aprendre el motor de plantilles de Go abans de poder tocar res. Kustomize neix precisament d'aquest descontentament i parteix d'una premissa oposada: no fer servir plantilles en absolut.

A Kustomize, els teus manifestos continuen sent YAML de Kubernetes perfectament vàlid. Pots obrir-los a l'editor i que et validi l'esquema, aplicar-los amb kubectl apply -f, i llegir-los sense desxifrar res. El que canvia entre entorns no s'expressa amb variables, sinó amb superposicions: petits fitxers que declaren les diferències respecte a una base comuna.

En aquesta lliçó migrarem el k8s/ de Rutas Norte de 120 fitxers duplicats a una base més tres superposicions, resoldrem de forma neta el problema del reinici davant de canvis de configuració que a 03-03 arreglàvem amb una anotació a mà, i acabarem comparant Helm i Kustomize sense favoritismes.

1. La filosofia sense plantilles
2. Kustomize dins de kubectl i com a binari propi
3. El model base + superposicions
4. kustomization.yaml camp a camp
5. Pedaços: fusió estratègica i JSON Patch
6. Generadors de ConfigMaps i Secrets
7. Components: trossos opcionals reutilitzables
8. Flux de treball: kustomize, diff i apply
9. Migració completa de Rutas Norte
10. Helm davant de Kustomize
11. Combinar Helm i Kustomize
12. Errors comuns i consells
13. Exercicis
14. Conclusió

Compara els dos enfocaments per al mateix objectiu: que api-reserves tingui 1 rèplica en desenvolupament i 4 en producció.

Amb Helm, el manifest deixa de ser YAML de Kubernetes: replicas: {{ .Values.apiReserves.replicaCount }}, image: {{ .Values.imageRegistry }}/api-reserves:{{ .Values.apiReserves.image.tag }}. Amb Kustomize, la base és YAML normal i corrent (replicas: 1, image: registry.rutasnorte.example/api-reserves:2.4.0), aplicable amb kubectl apply -f, i la superposició declara les diferències:

Kustomize funciona com una canalització de transformacions: llegeix els manifestos base, aplica una sèrie d'operacions declarades (canviar el namespace, afegir etiquetes, substituir la imatge, aplicar pedaços) i emet el YAML resultant.

Aquesta naturalesa de "transformar YAML existent" té una conseqüència elegant: Kustomize entén els tipus de Kubernetes. Quan fusiona dues llistes de contenidors sap que la clau de correlació és name; quan canvia una imatge sap on són els camps image en un Deployment, un StatefulSet, un CronJob o un DaemonSet. Helm, que només concatena text, no en sap res.

Avantatge enorme: no hi ha res a instal·lar. Qualsevol amb kubectl pot desplegar. Desavantatge: la versió integrada va endarrerida respecte de la independent i no es pot actualitzar sense actualitzar kubectl.

Recomanació per a Rutas Norte: kubectl -k per a l'ús interactiu diari; el binari amb versió fixada a la canalització ci-rutasnorte, perquè tothom generi exactament el mateix YAML.

Tres conceptes:

• Base: els manifestos comuns. Ha de ser desplegable per si sola i conté els valors més conservadors.
• Superposició (overlay): un directori que referencia una base i declara les diferències. Una per entorn.
• Component: un tros reutilitzable que les superposicions activen opcionalment.

Fixa't que aquest fitxer és directament aplicable amb kubectl apply -f. Això no ho pots fer amb una plantilla de Helm: és l'avantatge principal de l'enfocament.

I la superposició de desenvolupament són onze línies:

Fitxers, directoris amb el seu propi kustomization.yaml, o URL remotes:

Sobre els recursos remots: fixa sempre ?ref= a una etiqueta o commit. Sense això apuntes a la branca principal i el teu desplegament canvia quan algú aliè fa un commit. És el mateix principi que --version a Helm i les etiquetes immutables d'imatge (08-05).

namespace: rutas-norte-pro estableix metadata.namespace a tots els objectes generats i actualitza les referències creuades (el namespace d'un subjects de RoleBinding, per exemple). Un sol camp elimina la principal duplicació entre entorns. Els objectes d'àmbit de clúster (ClusterRole, StorageClass, CRD) no en resulten afectats: Kustomize ho sap.

namePrefix: rn- i nameSuffix: -pro reanomenen els objectes, i —molt important— Kustomize actualitza les referències: el scaleTargetRef de l'HPA, el serviceName del StatefulSet, el name del ConfigMap a envFrom, el backend.service.name de l'Ingress. Rutas Norte no els fa servir, perquè ja separa entorns per namespace i afegir -pro al nom de tot complica les ordres de diagnòstic; són útils quan desplegues dues instàncies al mateix namespace.

Aquest apartat mereix atenció especial perquè és un parany real que trenca desplegaments.

commonLabels (la forma antiga) afegeix les etiquetes a metadata.labels i també a spec.selector.matchLabels del Deployment, a spec.template.metadata.labels del pod i a spec.selector del Service. I aquí hi ha el problema: spec.selector d'un Deployment és immutable (02-03, 02-07). Si la base ja està desplegada i afegeixes una etiqueta, el següent apply falla:

L'única sortida és esborrar el Deployment i recrear-lo, amb tall de servei. A rutas-norte-pro, a les onze del matí.

Hi ha un segon problema, més subtil: si afegeix entorn: pro al selector del Service, aquest Service deixarà de trobar els pods que ja existien sense aquesta etiqueta. Trànsit a enlloc, sense cap error visible.

Regla de Rutas Norte: les etiquetes de selector es defineixen una vegada a la base (app: api-reserves) i no es toquen mai. Tota la resta s'afegeix amb includeSelectors: false.

Kustomize busca el camp image a qualsevol tipus que el tingui, inclosos els initContainers. No cal dir-li on ha de mirar. Això és el que la canalització ci-rutasnorte modifica a cada desplegament:

kustomize edit modifica el kustomization.yaml al disc. Combinat amb un commit automàtic, és la peça que connecta la construcció de la imatge amb GitOps (10-05).

Estalvia escriure un pedaç per a una cosa tan comuna. Però atenció, reprenent 09-01: si api-reserves té un HPA, declarar replicas aquí és contraproduent. Cada kubectl apply -k tornarà el Deployment a 4 rèpliques encara que l'HPA el tingui a 15 per la càrrega del pont de maig, amb una davallada de capacitat fins que l'HPA reaccioni.

Per a components amb HPA, la solució correcta és no declarar replicas enlloc (ni a la base ni a la superposició) i deixar que minReplicas de l'HPA governi. Kubernetes no exigeix el camp: per defecte val 1 i l'HPA el puja immediatament. La peça que falta —que Argo CD no marqui deriva quan l'HPA canviï aquest camp— la resoldrem a 10-05 amb ignoreDifferences.

Els camps anteriors cobreixen l'habitual. Per a tota la resta, hi ha pedaços.

Escrius un YAML parcial amb la mateixa estructura de l'objecte. Kustomize el fusiona entenent la semàntica dels tipus de Kubernetes.

El que fa especial la fusió estratègica és que Kustomize coneix l'esquema: sap que containers es correlaciona per name, ports per containerPort, volumeMounts per mountPath. Un pedaç que només menciona el contenidor api deixa intactes els sidecars.

Es pot escriure en línia amb patch: |- dins del kustomization.yaml, útil per a canvis petits. I hi ha dues directives especials: $patch: replace substitueix una llista sencera en comptes de fusionar-la, i $patch: delete elimina l'element que coincideixi.

Quan la fusió estratègica no arriba —perquè cal operar sobre índexs de llista, o sobre un CRD que Kustomize no coneix— es fa servir JSON Patch: una llista d'operacions explícites.

Detalls que cal conèixer: els camins comencen a l'arrel de l'objecte i els índexs de llista són numèrics (/spec/template/spec/containers/0/); replace falla si el camí no existeix, mentre que add el crea o el substitueix, així que davant del dubte fes servir add.

Aquí hi ha la potència real del sistema. Un pedaç es pot dirigir a molts objectes alhora.

Els selectors disponibles a target són kind, name (exacte o regex), namespace, group, version, labelSelector i annotationSelector.

Veuràs molt codi antic amb aquests dos camps. El camp unificat patches els reemplaça tots dos: detecta automàticament si el contingut és una fusió estratègica o un JSON Patch, i admet target amb selectors en els dos casos, cosa que els antics no permetien.

kustomize edit fix migra els camps obsolets automàticament.

Aquesta és la funcionalitat més elegant de Kustomize, i resol netament un problema que a 03-03 solucionàvem a mà.

Kustomize afegeix un hash del contingut al nom. I —això és l'important— actualitza automàticament totes les referències, així que el Deployment queda amb configMapRef: { name: api-reserves-config-9t2hmf6b4d }.

Pensa en el que implica. Quan canvies LOG_LEVEL d'info a warn: canvia el contingut → canvia el hash → canvia la referència al Deployment → canvia la plantilla del pod → el Deployment fa un rollout automàticament.

Això resol, de forma nativa i sense trucs, el problema de 03-03. Allà vam explicar que un ConfigMap actualitzat no reinicia els pods i que l'apedaçament era afegir a mà una anotació amb el hash. Amb Kustomize no hi ha apedaçament: és el comportament per defecte. I comparat amb Helm (10-03), on calia escriure checksum/config: {{ include ... | sha256sum }} a cada plantilla, aquí no escrius res.

Avantatge addicional: el rollback funciona de debò. Com que cada versió de la configuració és un objecte diferent amb nom diferent, un kubectl rollout undo torna el pod a la referència anterior, i el ConfigMap vell continua existint mentre algun ReplicaSet el referenciï. Amb un ConfigMap de nom fix, el rollback tornaria el codi vell però amb la configuració nova: el pitjor de tots dos mons.

També per generador, amb options: { disableNameSuffixHash: true } dins d'una entrada concreta.

Quan cal desactivar-lo? Només quan alguna cosa externa referencia el ConfigMap per un nom fix que Kustomize no pot actualitzar: un CRD d'un operador que Kustomize no sap interpretar, un pod que rellegeix el ConfigMap en calent a propòsit, o un de compartit entre aplicacions gestionades per sistemes diferents. Consell ferm: no el desactivis sense una raó concreta. El hash és la millor característica de Kustomize.

Si la base defineix api-reserves-config amb LOG_LEVEL=info, RESERVA_TTL_MINUTS=15 i CACHE_HOST=redis-cache, i la superposició de producció declara:

El resultat combina les tres claus heretades amb LOG_LEVEL sobreescrit i PASSARELLA_URL afegida.

La mateixa mecànica, amb codificació base64 automàtica i suport de type: kubernetes.io/tls per a certificats des de fitxers.

Advertiment crític: secretGenerator no xifra res. Base64 no és xifratge (03-02). Si poses la contrasenya de postgres-reserves en un literals o en un fitxer del repositori, aquesta contrasenya està en clar a Git per sempre, fins i tot si després l'esborres.

La forma correcta a Rutas Norte, reprenent el que vam anunciar a 03-02, és referenciar un Secret xifrat amb SOPS o Sealed Secrets, o millor encara un recurs de l'External Secrets Operator que va a buscar el valor a Vault:

Aquest fitxer és innocu: només diu on és el secret, no quin és. Hi tornarem a 10-05.

Un component és com una superposició, però pensat per ser inclòs per diverses. Resol el cas "això ho vull a pre i a pro, però no a dev". Rutas Norte té tres candidats clars: les NetworkPolicies (04-06), l'alta disponibilitat (09-05) i l'observabilitat (07-03). En desenvolupament fan nosa; als altres dos entorns són obligatoris.

Un component també pot tenir pedaços, no només recursos:

I les superposicions l'activen: dev no en porta cap, pre porta politiques-xarxa i observabilitat, i pro hi afegeix a més alta-disponibilitat.

Els components s'apliquen en l'ordre en què apareixen, després dels resources. Si dos pedacen el mateix camp, guanya l'últim.

Aquesta sortida explica exactament el que passarà: canvia el hash de la configuració (hi haurà rollout) i puja el límit de memòria. És l'equivalent a helm diff de la lliçó anterior, però integrat a kubectl, sense plugins.

Un problema real: si esborres un manifest del repositori, kubectl apply -k no esborra l'objecte del clúster. Es queda orfe. Existeix --prune amb --applyset i --prune-allowlist, però és empipador i cal enumerar els tipus. És un altre dels problemes que GitOps (10-05) resol de forma nativa: Argo CD i Flux saben quins objectes els pertanyen i els poden ells sols.

I l'important no és el nombre de fitxers, sinó que cada línia de configuració existeix una sola vegada.

Pas 1: triar la base. L'entorn més simple, normalment dev. Copiar els seus manifestos a k8s/base/, traient-los el namespace (el posarà la superposició) amb yq -i 'del(.metadata.namespace)' k8s/base/**/*.yaml.

Pas 2: escriure els kustomization.yaml de la base (apartat 3).

Pas 3: calcular el diferencial real de cada entorn.

Quatre diferències. Tres es resolen amb camps de kustomization.yaml (namespace, replicas, images) i només una necessita pedaç (resources).

Pas 4: escriure les superposicions.

Pas 5: verificar que la migració no canvia res. Aquest és el pas que dona confiança.

Un diff buit significa que pots fer kubectl apply -k i no passarà absolutament res. La migració és una operació sense risc.

Pas 6: esborrar els directoris vells amb git rm -r k8s/dev k8s/pre k8s/pro i actualitzar la canalització.

Helm per consumir, Kustomize per produir. És la decisió de Rutas Norte i la de la majoria d'equips madurs: ningú vol mantenir a mà els 60 objectes de kube-prometheus-stack, i ningú vol convertir el seu propi Deployment en una plantilla il·legible. L'excepció: si distribueixes el teu programari a clients que l'instal·len als seus clústers, necessites un paquet versionat i configurable, i aquí Helm no té rival.

Hi ha dues formes de fer servir les dues eines juntes, i serveixen per al mateix: modificar un chart de tercers en un camp que el seu autor no va parametritzar.

Un sol fitxer ho declara tot i actualitzar és canviar el número de versió, però necessita --enable-helm i tenir helm instal·lat, el resultat no és a Git, i el suport és desigual (kubectl -k no l'admet bé; Argo CD i Flux requereixen configuració extra).

Recomanació per a Rutas Norte: la forma A. Tenir el YAML generat a Git és exactament el que fa que GitOps funcioni bé: qualsevol pot llegir el repositori i saber què hi ha desplegat.

1. Fer servir commonLabels (o labels amb includeSelectors: true) sobre una cosa ja desplegada. Modifica spec.selector, que és immutable, i l'apply falla. L'única sortida és esborrar i recrear, amb tall de servei. Fes servir sempre includeSelectors: false.

2. Declarar replicas en un component amb HPA. Cada apply desfà l'escalat automàtic fins que l'HPA reacciona. Per al que tingui HPA, no declaris replicas enlloc.

3. Secrets a secretGenerator amb literals. Base64 no és xifratge. Si escrius la contrasenya de postgres-reserves en un fitxer del repositori, està en clar a l'historial de Git per sempre. Fes servir SOPS, Sealed Secrets o External Secrets Operator.

4. Desactivar disableNameSuffixHash sense necessitat. Perds el rollout automàtic en canviar la configuració, que és la millor característica de Kustomize.

5. Recursos remots sense ?ref=. El teu desplegament canvia quan un desconegut fa un commit. Fixa sempre etiqueta o commit.

6. Posar massa coses a la base. Si la base conté coses que la meitat dels entorns han de pedaçar per treure, està mal dissenyada. La base és el mínim comú; l'opcional va en components.

7. Cadenes de superposicions molt profundes. Base → comú → regió → entorn → client és tècnicament possible i humanament impracticable: ningú sap d'on surt un valor. Dos nivells, tres com a molt.

8. Pedaç que no s'aplica i ningú se n'assabenta. Si el target no casa amb res, Kustomize no sempre avisa. Verifica sempre amb kubectl kustomize que el canvi apareix a la sortida.

9. replace en un JSON Patch sobre un camí que no existeix. Falla amb "missing value". Fes servir add, que crea o substitueix.

10. Oblidar escapar / a les claus d'un JSON Patch. rutasnorte.example/revisio s'escriu rutasnorte.example~1revisio.

11. Aplicar sense kubectl diff -k abans. És gratis, triga dos segons i t'ensenya exactament què canviarà. En producció hauria de ser obligatori.

12. Suposar que les llistes es fusionen sempre. A la fusió estratègica, les llistes amb clau de correlació coneguda (containers per name) es fusionen; les que no en tenen (args, command) se substitueixen senceres.

13. Editar objectes a mà amb kubectl edit i oblidar-ho. Kustomize no reconcilia: només actua quan algú executa apply. El següent desplegament trepitjarà el canvi manual sense avisar. Aquest és exactament el problema que resol GitOps.

Partint de la base descrita a la lliçó, escriu k8s/entorns/pre/kustomization.yaml que: faci servir el namespace rutas-norte-pre, etiqueti tot amb entorn: pre sense tocar els selectors, fixi les imatges a rc-2.4.0, activi els components de polítiques de xarxa i observabilitat, fusioni un ConfigMap amb LOG_LEVEL=info i una URL de passarel·la de proves, i apliqui un pedaç que pugi els recursos a la meitat dels de producció. Verifica el resultat sense aplicar res.

Escriu un pedaç que afegeixi a tots els Deployments etiquetats amb app.kubernetes.io/part-of: rutas-norte un initContainer que esperi que postgres-reserves sigui accessible abans d'arrencar (06-04), sense modificar cap fitxer de la base. Explica per què necessites JSON Patch i no fusió estratègica.

Amb la superposició de dev desplegada, demostra en tres passos que canviar una línia de config.env provoca un rollout automàtic: captura el nom del ConfigMap i la generació del Deployment abans, canvia el valor, aplica, i compara. Explica per què això no passaria amb un ConfigMap de nom fix.

Solució 1

Solució 2

Nota: la primera operació buidaria una llista initContainers ja existent. Si alguns Deployments ja tenen init containers que cal conservar, la solució robusta és separar en dos pedaços amb target diferents.

Per què JSON Patch: la fusió estratègica exigeix un fitxer per objecte amb el seu metadata.name exacte, així que no es pot dirigir a "tots els que casin amb una etiqueta". JSON Patch combinat amb labelSelector a target arriba a N objectes amb una sola declaració, i /- permet afegir al final sense saber quants elements hi havia.

Solució 3

Explicació: el hash forma part del nom del ConfigMap, i aquest nom apareix dins de spec.template del Deployment. En canviar la plantilla del pod, el controlador crea un ReplicaSet nou i executa el desplegament gradual (02-03).

Per què no passaria amb nom fix: spec.template continuaria sent byte a byte idèntic, metadata.generation no canviaria, i no hi hauria ReplicaSet nou. Els pods continuarien amb les variables velles fins que algú executés kubectl rollout restart a mà. Aquest és justament l'apedaçament de l'anotació checksum/config de 03-03, que aquí no cal.

Kustomize ha reduït el k8s/ de Rutas Norte de 114 fitxers duplicats a 43, amb cada valor definit una sola vegada. L'essencial:

• Sense plantilles: els manifestos de k8s/base/ continuen sent YAML de Kubernetes vàlid, aplicable amb kubectl apply -f i validable per l'editor. El que canvia entre entorns es declara com a transformacions a la superposició.
• Ve dins de kubectl (apply -k, diff -k, kubectl kustomize), tot i que el binari propi va més al dia i és el que convé fixar a la canalització.
• El model base + superposicions + components cobreix els tres eixos reals: el comú, el propi de cada entorn, i les capacitats opcionals que només volen alguns entorns.
• namespace, images, replicas i labels resolen la majoria de diferències sense escriure un pedaç. I labels ha de portar includeSelectors: false: commonLabels toca els selectors immutables i trenca desplegaments en marxa.
• Per a la resta hi ha patches, amb fusió estratègica o JSON Patch, i un target dirigible per tipus, nom, etiqueta o anotació. patchesStrategicMerge i patchesJson6902 són obsolets.
• Els generadors amb el seu sufix de hash són la joia: canviar una línia de configuració canvia el nom del ConfigMap, canvia la plantilla del pod i provoca un rollout automàtic. Resol de forma nativa el que a 03-03 arreglàvem a mà, i a més fa que el rollback torni codi i configuració alhora.
• I en la comparació honesta amb Helm, la regla és clara: Helm per consumir programari de tercers, Kustomize per a les aplicacions pròpies, amb dues formes de combinar-los quan cal pedaçar un chart aliè.

Però queda un problema que ni Helm ni Kustomize resolen, i que ha aparegut a les dues lliçons. Totes dues eines només actuen quan algú executa una ordre. Si algú fa kubectl edit en producció, cap se n'assabenta. Si el portàtil de qui desplega s'espatlla, ningú sap desplegar. Si la canalització ci-rutasnorte necessita credencials d'administrador del clúster per executar kubectl apply, tenim un problema de seguretat seriós que contradiu el RBAC mínim que vam definir a 08-01.

A la lliçó següent, GitOps amb Argo CD i Flux, fem el pas final: un agent que viu dins del clúster, estira de Git contínuament i reconcilia la realitat amb el que està declarat. Veurem el recurs Application d'Argo CD, els ApplicationSet per desplegar els tres entorns des d'una sola definició, l'equivalent a Flux, les tres solucions al problema dels secrets en un repositori, i per fi tancarem el conflicte entre l'HPA i el camp replicas que vam deixar anunciat a 09-01.