Tancàvem la lliçó anterior assenyalant un fil solt que ha recorregut tot el mòdul. El selector d'un ReplicaSet que adopta pods, el selector d'un Service que troba els seus destins, l'etiqueta entorn amb què les polítiques de xarxa seleccionaran namespaces, l'anotació kubernetes.io/change-cause que documenta cada revisió, el pod-template-hash que el Deployment afegeix pel seu compte, i totes les consultes amb -l que fem servir des de la primera lliçó: tot això són etiquetes i anotacions. Les hem anat fent servir per necessitat, sense sistematitzar. Aquesta lliçó hi posa ordre, i no és un afer menor: en un clúster amb sis components per tres entorns, l'esquema d'etiquetatge és el que separa una plataforma navegable d'un caos d'objectes anònims. Veuràs la diferència exacta entre etiqueta i anotació, la sintaxi i les restriccions de claus i valors, les etiquetes recomanades per Kubernetes i com es concreten a l'esquema oficial de Rutas Norte, els selectors d'igualtat i de conjunt en totes les seves formes, qui els consumeix, per què el selector d'un Deployment és immutable, l'ús real de les anotacions i les consultes del dia a dia que et faran productiu.

1. Etiquetes enfront d'anotacions
2. Sintaxi i restriccions de claus i valors
3. Les etiquetes recomanades per Kubernetes
4. L'esquema d'etiquetatge de Rutas Norte
5. Selectors d'igualtat
6. Selectors de conjunt
7. Selectors en manifests: matchLabels i matchExpressions
8. Qui consumeix selectors
9. La regla d'or: el selector d'un Deployment és immutable
10. Anotacions a la pràctica
11. kubectl label i kubectl annotate
12. Consultes útils del dia a dia

Totes dues viuen a metadata i totes dues són parells clau-valor. Aquí s'acaba la semblança.

La regla de decisió, que resol el 100 % dels dubtes:

Voldràs buscar objectes per aquesta dada, o servirà a un selector? És una etiqueta. És informació que es llegeix però no es busca? És una anotació.

Exemples aplicats a Rutas Norte:

Kubernetes és estricte amb el format, i conèixer les regles evita rebutjos incomprensibles.

Una clau té un nom i, opcionalment, un prefix separat per /:

Regles del nom (la part obligatòria):

• Màxim 63 caràcters.
• Ha de començar i acabar per caràcter alfanumèric.
• Pot contenir -, _, . i alfanumèrics enmig.

Regles del prefix (opcional):

• Ha de ser un subdomini DNS vàlid: rutasnorte.example, app.kubernetes.io.
• Màxim 253 caràcters.
• Se separa del nom amb /.
• Reservats: els prefixos kubernetes.io/ i k8s.io/ estan reservats per al mateix Kubernetes i els seus components principals. No els facis servir per a les teves etiquetes.

• Màxim 63 caràcters (o buit, que és vàlid).
• Si no és buit, ha de començar i acabar per alfanumèric.
• Només alfanumèrics, -, _ i . enmig.
• Prohibits: espais, /, :, @, accents, ç, emojis.

Exemples vàlids i invàlids:

Comprova el rebuig tu mateix:

La versió correcta fa servir una anotació:

Les claus segueixen les mateixes regles que les de les etiquetes. Els valors, en canvi, són gairebé lliures: qualsevol cadena, inclosos JSON, salts de línia i caràcters especials, amb un límit conjunt de 256 KiB per a totes les anotacions d'un objecte.

Aquell límit generós és el que permet que kubectl apply desi el manifest complet a kubectl.kubernetes.io/last-applied-configuration, com vam veure a Objectes i Manifests.

Kubernetes defineix un conjunt d'etiquetes comunes sota el prefix app.kubernetes.io/. No són obligatòries ni les imposa res, però són el vocabulari compartit que entenen Helm, Kustomize, Argo CD, Prometheus i pràcticament qualsevol eina de l'ecosistema.

La diferència entre name i instance és la que més costa:

• name és què és: postgres. La mateixa en totes les instal·lacions.
• instance és quin és: postgres-reserves-pro. Distingeix dues instal·lacions del mateix.

Si Rutas Norte tingués dues bases de dades PostgreSQL —una de reserves i una altra de facturació—, totes dues portarien name: postgres però instance: postgres-reserves i instance: postgres-facturacio.

Un exemple complet amb les sis:

Nota pràctica: version: "2.5.0" va entre cometes. Sense elles, YAML podria interpretar valors com 1.0 com a número i provocar un error de tipus, ja que els valors d'etiqueta han de ser cadenes.

Un advertiment important que enllaça amb l'apartat 9: app.kubernetes.io/version no ha d'anar al selector. Si hi fos, en canviar de versió el selector deixaria d'encaixar amb els seus propis pods, i com que el selector és immutable, hauries de recrear el Deployment a cada desplegament. La versió és informativa; la identitat la donen name i instance.

Ha arribat el moment de fixar l'esquema definitiu del projecte. Fins ara hem fet servir tres etiquetes mínimes (app, app.kubernetes.io/part-of i entorn); les consolidem i les ampliem.

La regla d'or de l'esquema, que es deriva de tot el que hem après al mòdul:

Només app i entorn entren als selectors. Són les dues úniques etiquetes que identifiquen el component de forma inequívoca i que no canvien mai.

Tota la resta —versió, component, criticitat, gestor— és informativa i pot canviar sense recrear res.

Així queda api-reserves amb l'esquema complet aplicat:

Fixa't en l'asimetria, que és exactament la que vam aprendre amb els ReplicaSets: el template porta nou etiquetes i el selector només n'exigeix dues. Està permès i és el correcte: el selector ha de ser un subconjunt mínim i estable; la resta d'etiquetes viatgen amb els pods per poder-los consultar.

Aplica'l i observa la potència immediata:

Un selector és una consulta sobre etiquetes. El tipus més simple compara valors.

Es fan servir amb -l (o --selector), i diverses condicions separades per comes es combinen amb I lògic:

Un detall sobre != que convé conèixer: també selecciona els objectes que no tenen aquella etiqueta en absolut. entorn!=pro retorna tant els de dev i pre com els que no tenen l'etiqueta entorn.

No existeix l'O lògic als selectors d'igualtat. Per a això hi ha els de conjunt.

Més expressius. Operen sobre conjunts de valors i sobre l'existència de la clau.

Exemples aplicats:

Nota sobre les cometes: els selectors de conjunt porten parèntesis i espais, que la shell interpretaria. Tanca'ls sempre entre cometes simples.

I es poden combinar amb els d'igualtat, separant per comes:

Dins d'un YAML, els selectors tenen dues formes equivalents a les dues famílies que acabes de veure.

És un mapa: totes les claus han de coincidir (I lògic). És el que hem fet servir a tot el mòdul.

Es poden fer servir tots dos alhora; totes les condicions es combinen amb I lògic:

Traducció: "pods amb app=api-reserves i amb entorn igual a pre o a pro".

Atenció a l'excepció del Service, que ja vam veure a la seva lliçó i convé recordar aquí perquè és una asimetria real de l'API:

El motiu és històric: els Services són del grup core v1, anterior al selector enriquit, i només admeten igualtat.

Els selectors no són només per a consultes manuals. Són el mecanisme d'acoblament de tot Kubernetes: la manera com uns objectes en troben uns altres sense conèixer-ne els noms.

La lliçó de fons: les etiquetes d'un pod no són decoració, són la seva interfície amb la resta del sistema. Canviar una etiqueta d'un pod el pot treure d'un Service, deixar-lo fora d'una política de xarxa o fer-lo invisible per al seu ReplicaSet. Ho veurem a l'exercici 3.

Comprova-ho:

El mateix passa amb ReplicaSets, StatefulSets i DaemonSets. Els Services són l'excepció: el seu selector sí que es pot modificar, i això els converteix en l'eina de les estratègies blue-green del mòdul 11.

La raó és la seguretat de les dades... dels pods. Imagina que es permetés canviar-lo:

1. El Deployment té selector: app=api-reserves i governa 4 pods amb aquella etiqueta.
2. Canvies el selector a app=api-reserves-v2.
3. Instantàniament, els 4 pods deixen d'encaixar. Es converteixen en orfes, exactament com els de l'experiment --cascade=orphan de la lliçó de ReplicaSets.
4. El Deployment compta 0 pods propis i en crea 4 de nous.
5. Resultat: 8 pods corrent, 4 d'ells sense controlador, invisibles per al Deployment, consumint recursos i sense ningú que els actualitzi ni els recuperi si cauen.

Pitjor encara: si el Service continuava apuntant a app=api-reserves, aquells 4 orfes continuarien rebent trànsit de producció sense que cap controlador els vigili.

Kubernetes prefereix fallar en aplicar abans que deixar-te arribar a aquell estat.

Hi ha dos camins, i el primer és el bo:

Camí A: substituir el controlador sense tallar el servei.

Camí B: nom nou i transició pel Service. Es crea un Deployment amb un altre nom i el selector correcte, s'espera que estigui llest i es canvia el selector del Service perquè apunti als pods nous. És, en essència, un desplegament blue-green (11-04).

Pensa bé el selector abans del primer apply. És la decisió menys reversible d'un manifest.

I d'aquí la regla del projecte que ja coneixes: al selector, només app i entorn. Mai la versió, mai el gestor, mai la criticitat, mai part-of. Tot el que pugui canviar amb el temps es queda fora.

Les anotacions semblen menys importants que les etiquetes fins que descobreixes quantes coses funcionen gràcies a elles.

Aquest és l'ús més potent: molts controladors es configuren mitjançant anotacions, no mitjançant camps del spec. El cas paradigmàtic és el controlador d'Ingress:

Cap d'aquelles línies és a l'esquema de l'Ingress: són instruccions que el controlador d'NGINX i cert-manager llegeixen i apliquen. El motiu d'aquest disseny és que cada implementació d'Ingress té capacitats diferents, i l'API estàndard no les pot cobrir totes. S'estudien a Controladors d'Ingress i TLS i Certificats.

I l'ús més simple i més rendible: informació que salva una guàrdia nocturna.

Fixa't en dues coses impossibles amb etiquetes: valors amb @, : i /, i un valor multilínia. Aquesta és la raó que existeixin les anotacions.

A les tres de la matinada, això val el seu pes en or:

Mai no guardis contrasenyes, tokens, claus d'API ni certificats privats a les anotacions.

Els motius:

• Es llegeixen en clar amb kubectl get -o yaml o kubectl describe, que solen ser permisos àmpliament concedits.
• Apareixen als logs: qualsevol bolcat d'un objecte les inclou.
• Es copien a last-applied-configuration, i queden duplicades.
• Se'n van als backups i a les eines de GitOps, propagant-se arreu.
• No es xifren en repòs dins d'etcd tret que el clúster ho tingui configurat, i tot i així el mecanisme està pensat per a Secrets.

El mateix val per a les etiquetes, amb l'agreujant que a més són indexades i consultables.

Per a això hi ha els Secrets, a la lliçó 03-02, i la seva gestió segura al mòdul 8. Aquell POSTGRES_PASSWORD en clar que vam deixar al Deployment provisional de postgres-reserves és exactament el deute que pagarem al mòdul següent.

Totes dues ordres comparteixen sintaxi.

Si la clau ja existeix, l'ordre falla tret que ho indiquis:

És una protecció deliberada contra trepitjar sense voler una etiqueta que algun selector estigui fent servir.

Aquell guió final és fàcil de passar per alt en llegir un script. Recorda-ho: clau amb guió al final significa esborrar.

Advertiment de seguretat: --all combinat amb --overwrite sobre una etiqueta que apareix en algun selector pot treure pods del seu Service o del seu ReplicaSet a l'acte. Prova sempre primer amb --dry-run=server:

Canviar una etiqueta amb kubectl label sobre un pod gestionat per un Deployment no sobreviu: al pròxim desplegament, els pods es recreen a partir del template i el canvi desapareix. Perquè perduri, edita spec.template.metadata.labels al manifest.

I hi ha un efecte secundari molt més greu, que explorarem a l'exercici 3: si canvies una etiqueta que és al selector del ReplicaSet, el pod queda orfe a l'instant i el ReplicaSet en crea un altre per substituir-lo.

Aquí és on l'esquema d'etiquetatge deixa de ser burocràcia i es converteix en productivitat. Les consultes més rendibles combinen -l amb els formats de sortida que vam veure a La CLI de Kubernetes.

Truc de sintaxi important: a custom-columns, els punts que formen part de la clau de l'etiqueta cal escapar-los amb \.. Si no, kubectl els interpreta com a separadors de ruta JSONPath i no troba res.

La consulta que més vegades et demanaran:

Trobar el que incompleix la convenció del projecte:

Aquell --dry-run=client abans d'un delete massiu és un hàbit que convé adquirir.

El flag -L (ela majúscula) és un petit tresor: afegeix columnes amb el valor de les etiquetes indicades, sense filtrar res.

• Ficar la versió al selector. En desplegar una versió nova el selector deixa d'encaixar, i com que és immutable, t'obliga a recrear el Deployment. El selector només porta app i entorn.
• Selectors massa amplis. Un app.kubernetes.io/part-of: rutas-norte com a selector adopta i pot esborrar pods d'altres components, com vam veure a ReplicaSets.
• Fer servir caràcters prohibits en valors d'etiqueta. Res d'@, :, /, espais ni accents. Si la dada els necessita, és una anotació.
• Fer servir el prefix kubernetes.io/ per a etiquetes pròpies. Està reservat. Fes servir el domini de la teva organització: rutasnorte.example/.
• Guardar secrets a les anotacions o les etiquetes. Es llegeixen en clar amb describe, viatgen als backups i acaben a Git. Van en Secrets.
• Posar les etiquetes només a metadata i no a spec.template.metadata. Els pods hereten les del template, no les del Deployment. És l'error que trenca els Services.
• Oblidar --overwrite i pensar que l'ordre ha funcionat. kubectl label falla si la clau existeix. Llegeix sempre la sortida.
• Canviar amb kubectl label una etiqueta que és en un selector. El pod queda orfe i el controlador en crea un altre. Pot duplicar capacitat sense que te n'adonis.
• Esperar que un canvi amb kubectl label sobre un pod perduri. Es perd al pròxim desplegament. Edita el template.
• Oblidar les cometes simples als selectors de conjunt. Els parèntesis i els espais els interpreta la shell.
• No escapar els punts de les claus a custom-columns. app.kubernetes.io/version s'ha d'escriure app\.kubernetes\.io/version.
• Consell: defineix l'esquema d'etiquetatge abans de desplegar res. Afegir-lo després implica editar tots els manifests i, si toca selectors, recrear objectes.
• Consell: kubectl get pods -A -L entorn,app et dona una vista tabulada de tota la plataforma sense filtrar. És la consulta amb què començar qualsevol revisió.
• Consell: documenta l'esquema a k8s/README.md del repositori. Un esquema que només coneix qui el va dissenyar no és un esquema.

1. Actualitza k8s/base/botiga-web-deployment.yaml perquè el Deployment i el seu template portin les vuit etiquetes de l'esquema de Rutas Norte (app, entorn, les cinc d'app.kubernetes.io/ i criticitat), i quatre anotacions: responsable, panell, runbook i change-cause.
2. Assegura't que el selector continua tenint només app i entorn, i explica en dues línies per què.
3. Aplica'l i demostra amb una ordre que els pods porten les vuit etiquetes.
4. Recupera l'URL del runbook amb una sola ordre.

Amb els tres entorns desplegats, escriu l'ordre exacta per a cada pregunta:

1. Tots els pods de la plataforma a pre o pro, en qualsevol namespace.
2. Tots els Deployments de la plataforma que no són de desenvolupament.
3. Els pods de components amb criticitat critica o alta que no estan en estat Running.
4. Una taula amb entorn, component, versió i node de tots els pods de la plataforma.
5. Els Deployments als quals els falta l'etiqueta rutasnorte.example/criticitat (auditoria de l'esquema).
6. Tots els pods, sense filtrar, mostrant entorn i app.kubernetes.io/component com a columnes addicionals.

Aquest exercici demostra per què les etiquetes són la interfície d'un pod amb la resta del sistema. Treballa a rutas-norte-dev amb el Deployment de botiga-web (3 rèpliques) i el seu Service.

1. Apunta quants pods hi ha i quants endpoints té el Service.
2. Tria un pod i canvia-li l'etiqueta app a botiga-web-aillat amb kubectl label --overwrite.
3. Observa immediatament: quants pods hi ha ara? Què ha fet el ReplicaSet? Continua viu el pod modificat? Qui n'és el propietari?
4. Comprova quants endpoints té ara el Service i explica per què.
5. Explica per a què serveix aquesta tècnica al món real i quin perill té.
6. Deixa el clúster com estava.

Solució 1

2. El selector porta només app i entorn perquè és immutable i ha d'identificar el component de forma estable. Si inclogués app.kubernetes.io/version, en desplegar la 1.9.0 el selector deixaria d'encaixar amb els pods nous, i com que no es pot modificar, caldria esborrar i recrear el Deployment a cada desplegament. A més, un selector mínim evita el risc d'adopcions indegudes si un altre objecte comparteix etiquetes informatives.

Les vuit de l'esquema, més el pod-template-hash que hi afegeix el Deployment.

Solució 2

Nota sobre la pregunta 3: -l filtra per etiquetes i --field-selector per camps de l'objecte. Són mecanismes diferents i complementaris; els camps disponibles per a --field-selector són limitats (status.phase, spec.nodeName, metadata.name, metadata.namespace i poca cosa més).

Solució 3

3 pods, 3 endpoints.

Ara hi ha 4 pods. El que ha passat, pas a pas:

• En canviar app de botiga-web a botiga-web-aillat, el pod va deixar d'encaixar amb el selector del ReplicaSet.
• A la volta següent del seu bucle de reconciliació, el ReplicaSet va comptar 2 pods propis on n'hi havia d'haver 3 i en va crear un de nou (h7pnk, amb 4 segons d'edat).
• El pod modificat continua viu, però ha quedat orfe: cap controlador no el vigila.

Sortida buida: no té propietari. Kubernetes li va retirar les ownerReferences en deixar d'encaixar amb el selector.

Continuen sent 3, però un ha canviat. El pod aïllat (10.244.0.81) ha sortit del Service perquè el seu selector també exigeix app=botiga-web; al seu lloc hi ha entrat el pod nou (10.244.0.87). El pod orfe ja no rep trànsit encara que continuï perfectament viu i sa.

5. Per a què serveix al món real: és la tècnica clàssica d'aïllament per depurar en producció. Si un de cinc pods presenta un comportament anòmal —una fuita de memòria, respostes erràtiques, un log sospitós—, canviar-li una etiqueta del selector el treu del Service i del ReplicaSet en un instant. Deixa de rebre trànsit de clients reals, el ReplicaSet crea un substitut per no perdre capacitat, i tu conserves el pod intacte, amb la seva memòria i el seu estat, per inspeccionar-lo amb calma: kubectl exec, kubectl logs, bolcats, perfilat. No cal reproduir el problema en un entorn de proves: tens el pacient viu sobre la taula.

   El perill és doble. Primer, aquell pod ja no el gestiona ningú: si el node cau o algú el desallotja, desapareix sense substitut, i sobretot és fàcil oblidar-se'n, consumint CPU i memòria indefinidament. Segon, si el canvi d'etiqueta es fa per error o en sentit contrari —donar a un pod solt les etiquetes d'un component governat—, provoques l'adopció i el possible esborrat immediat que vam veure a la lliçó de ReplicaSets. La disciplina obligatòria és etiquetar el pod aïllat amb la data i el motiu, i esborrar-lo en acabar:

Tres pods, tres endpoints, tot en ordre. I adona't que en esborrar l'orfe no va aparèixer cap substitut: el ReplicaSet ja tenia els seus tres pods i aquell no era seu.

Tanques el mòdul 2 amb el fil que el recorria sencer convertit en sistema. Saps distingir sense dubtar una etiqueta d'una anotació: les primeres identifiquen i es consulten, estan indexades, tenen 63 caràcters i un joc de caràcters restringit; les segones adjunten informació que es llegeix però no es busca, admeten fins a 256 KiB i qualsevol contingut, inclosos JSON i text multilínia. Coneixes la sintaxi completa de claus i valors, saps que kubernetes.io/ és un prefix reservat i que el domini de la teva organització és el lloc correcte per al que és propi, i domines les sis etiquetes recomanades per Kubernetes, inclosa la distinció entre name (què és) i instance (quin és).

Has fixat l'esquema d'etiquetatge definitiu de Rutas Norte per als seus sis components i els seus tres entorns, amb la seva regla d'or: només app i entorn entren als selectors, perquè el selector d'un Deployment és immutable i ficar-hi la versió et condemnaria a recrear l'objecte a cada desplegament. Fas servir les dues famílies de selectors —igualtat amb =, == i !=; conjunts amb in, notin, exists i la seva negació— tant a la línia d'ordres amb -l com als manifests amb matchLabels i matchExpressions, sense oblidar l'asimetria dels Services, que només admeten mapa pla. Saps qui consumeix selectors, que són gairebé tots: ReplicaSets, Deployments, Services, NetworkPolicies, PodDisruptionBudgets, afinitat i les eines de monitoratge. Fas servir les anotacions per al que serveixen —documentar el canvi, configurar controladors d'Ingress, deixar el runbook i el telèfon de guàrdia a mà— sense cometre mai l'error de guardar-hi un secret. I tens al cinturó kubectl label i kubectl annotate amb --overwrite i l'esborrat amb guió final, més el repertori de consultes que converteix un clúster gran en una cosa navegable.

Amb això tanques el mòdul 2 i la plataforma Rutas Norte ja és viva. botiga-web va passar de ser aquell pod fràgil del mòdul 1 a un Deployment de tres rèpliques que es recupera sol; api-reserves, redis-cache i worker-notificacions tenen els seus; els quatre components que reben connexions tenen una adreça estable amb balanceig entre rèpliques; saps desplegar sense tall de servei i desfer un desplegament trencat en menys d'un minut; tens tres entorns separats en namespaces amb el mateix manifest desplegat en diversos d'ells; i tot està etiquetat amb un esquema coherent que les lliçons següents explotaran.

Però hi ha deutes pendents molt visibles. La contrasenya de PostgreSQL continua escrita en clar dins d'un manifest que és a Git, i aquella base de dades guarda el nom, el DNI, el telèfon i el correu de cada client de Rutas Norte. L'URL de l'API va incrustada a la imatge en lloc d'injectar-se segons l'entorn. Cap namespace no té quota, així que un error a desenvolupament pot deixar sense recursos la producció. I tots els nostres pods declaren requests i limits a ull, sense criteri. El mòdul 3, Gestió de Configuració i Secrets, ataca exactament això: separarem la configuració del codi amb ConfigMaps, traurem les credencials dels manifests amb Secrets, injectarem tots dos com a variables d'entorn, posarem quotes i límits a cada entorn, entendrem les classes de qualitat de servei que decideixen quin pod mor primer quan falta memòria, i donarem a cada component la seva pròpia identitat davant de l'API amb ServiceAccounts.