A la lliçó anterior vam fer servir kubectl apply com si fos una ordre òbvia i vam veure manifests YAML de passada, sense desmenuçar-los. Toca saldar aquest deute, perquè el manifest és la unitat de treball real de Kubernetes: tot el que desplegis durant els onze mòduls que queden serà un fitxer YAML que descriu un objecte. Aquesta lliçó t'ensenya l'anatomia exacta de qualsevol objecte de l'API —els quatre camps que hi són sempre, facis el que facis—, com descobrir quina apiVersion correspon a cada tipus, el subconjunt de YAML que has de dominar, la diferència real entre apply, create i replace i per què importa, com validar un manifest abans d'aplicar-lo, i com organitzar els fitxers del projecte Rutas Norte al directori k8s/ perquè el repositori sigui la font de veritat.

1. Anatomia d'un objecte de Kubernetes
2. Grups, versions i nivells d'estabilitat de l'API
3. El YAML que cal saber
4. Estat desitjat i estat observat
5. apply enfront de create i replace
6. Server-side apply i la propietat de camps
7. Validar abans d'aplicar
8. Organització dels manifests del projecte

Absolutament tots els objectes de Kubernetes —un pod, un secret, un permís RBAC, un CRD d'un operador— comparteixen la mateixa estructura de quatre camps de primer nivell. Aprendre aquesta estructura una vegada serveix per sempre.

Indica el grup i la versió de l'API que ha d'interpretar l'objecte. Determina quins camps són vàlids i com es comporten. Exemples: v1 (grup core), apps/v1, networking.k8s.io/v1, batch/v1. És el camp que més errors provoca quan es copien manifests antics d'internet.

El tipus concret: Pod, Deployment, Service, Ingress, ConfigMap. S'escriu sempre en CamelCase, mentre que el recurs a la URL de l'API va en minúscules i plural (pods, deployments). La parella apiVersion + kind identifica unívocament l'esquema de l'objecte.

La identitat de l'objecte. Els seus camps més rellevants:

Un detall que explica un comportament desconcertant: si un namespace o un PVC es queda "penjat" en estat Terminating, gairebé sempre és per un finalizer el responsable del qual no ha acabat la seva feina.

L'estat desitjat. És el que tu descrius i el seu contingut depèn completament del kind: l'spec d'un Pod té containers, el d'un Service té selector i ports, el d'un PVC té resources.requests.storage. Tot el curs consisteix, en el fons, a aprendre a escriure spec de tipus diferents.

No apareix al manifest de dalt perquè no l'escrius tu: l'escriu el clúster. És l'estat observat. Si consultes l'objecte ja creat el veuràs:

Fixa't en dues coses. Primera: conditions és el format estàndard amb què Kubernetes expressa "com va" un objecte, i és el que consulten kubectl wait i les eines de desplegament. Segona: imageID conté el digest real de la imatge que s'està executant, mentre que spec.image conté l'etiqueta que tu vas demanar. Quan algú reutilitza una etiqueta, aquests dos valors deixen de correspondre's; hi tornarem en parlar d'etiquetes immutables a la lliçó següent.

L'API de Kubernetes està dividida en grups per poder evolucionar per parts i permetre extensions.

El grup core és l'històric i per això la seva apiVersion no porta prefix: és v1, no core/v1. Tots els altres segueixen el format grup/versió.

No cal memoritzar aquesta taula: es consulta.

Aquest és el reflex que cal adquirir: abans de copiar una apiVersion d'un blog, comprova-la amb kubectl api-resources. La versió correcta és sempre la que diu el teu clúster.

Kubernetes retira versions antigues amb cada actualització, i aquest és el motiu que manifests copiats de tutorials vells fallin:

El grup extensions/v1beta1 va desaparèixer fa moltes versions. Avui un Deployment és apps/v1 i un Ingress és networking.k8s.io/v1, sense excepcions. Abans d'actualitzar un clúster, eines com kubent (kube-no-trouble) revisen els teus manifests a la recerca d'APIs a punt de retirar-se.

YAML és simple però té paranys. Aquest és el subconjunt que necessites.

Regles innegociables:

• Espais, mai tabuladors. Un tabulador és un error de sintaxi en YAML. Configura el teu editor per expandir tabuladors a 2 espais en fitxers .yaml.
• La indentació defineix la jerarquia. Dos espais per nivell és la convenció a Kubernetes.
• El guionet - indica element de llista i el seu contingut s'indenta al mateix nivell que el guionet o més.

El cas NO és cèlebre (es coneix com the Norway problem): YAML 1.1 interpreta yes, no, on, off, y, n com a booleans. Regla pràctica: en un ConfigMap o Secret, posa sempre els valors entre cometes, perquè aquests camps exigeixen cadenes i un valor mal tipat produeix un error tan clar com aquest:

Fonamentals per incrustar fitxers de configuració en un ConfigMap:

El separador --- permet posar diversos objectes en un mateix fitxer, i kubectl apply els processa en ordre:

Criteri recomanat: agrupa en un fitxer els objectes que formen una unitat desplegable (un component amb el seu ConfigMap i el seu Service) i separa en fitxers diferents els components diferents. Un únic fitxer gegant amb tota la plataforma és difícil de revisar i d'aplicar parcialment.

Aquí és on el model declaratiu es torna concret. Ja coneixes el bucle de reconciliació de la lliçó Arquitectura de Kubernetes; vegem-lo des del punt de vista del fitxer.

Quatre conseqüències pràctiques que convé tenir molt clares:

1. Tu escrius spec; el sistema escriu status. Editar un status a mà no serveix de res: el controlador el sobreescriurà en el seu cicle següent.
2. Aplicar no és executar. kubectl apply acaba quan l'objecte està desat, no quan l'aplicació està llesta. Per esperar de debò:

3. És idempotent. Aplicar deu vegades el mateix fitxer dona el mateix resultat que aplicar-lo una. Això és el que fa possible que una canalització de CI/CD executi kubectl apply a cada desplegament sense comprovar abans què existeix.

4. El fitxer és la font de veritat, no el clúster. Si algú canvia alguna cosa amb kubectl edit, el següent apply des del repositori ho reverteix. Aquesta és exactament la propietat sobre la qual es construeix GitOps (mòdul 10).

Tres ordres que semblen intercanviables i no ho són gens.

La conclusió operativa és simple: fes servir apply sempre. create serveix per a ordres imperatives ràpides (kubectl create namespace) i replace per a casos molt concrets de substitució total.

Imagina que apliques un pod amb dues etiquetes, després edites el fitxer i en deixes només una, i tornes a aplicar. Com sap kubectl que ha d'eliminar la segona etiqueta, en lloc de deixar-la perquè "no és al fitxer però tampoc he demanat esborrar-la"?

La resposta clàssica és que apply desa una còpia de l'últim que vas aplicar en una anotació:

Amb aquesta informació, kubectl fa una fusió de tres vies: compara (a) el que vas aplicar l'última vegada, (b) el que apliques ara i (c) el que hi ha al clúster. El que era a (a) i desapareix a (b) s'esborra; el que només és a (c) —perquè ho va posar un controlador o un webhook— es respecta.

Això explica un error freqüent: si vas crear un objecte amb kubectl create i després el modifiques amb apply, no existeix l'anotació de referència i kubectl avisa que la fusió pot ser incorrecta. Per coherència, fes servir apply des del principi de la vida de cada objecte.

Des de Kubernetes 1.22, la fusió la pot fer el servidor en lloc del client, i és el mecanisme cap al qual està migrant tot l'ecosistema.

La diferència és conceptual: en lloc d'una anotació amb l'últim estat, el servidor registra quin gestor és propietari de cada camp a metadata.managedFields.

Avantatges respecte a la fusió en client:

• Detecta conflictes. Si intentes modificar un camp que pertany a un altre gestor (un HPA que controla replicas, per exemple), la petició falla amb un avís clar en lloc de provocar una baralla silenciosa entre eines:

Si de debò vols apropiar-te del camp, es força explícitament:

• No depèn d'una anotació que en objectes grans pot ser enorme.
• Diversos gestors poden coexistir sobre el mateix objecte de manera ordenada: la teva canalització, un operador i un autoescalador, cadascun amo dels seus camps.

Per al curs continuarem fent servir kubectl apply a seques, que és l'habitual, però convé que reconeguis managedFields quan aparegui en un -o yaml i que sàpigues què significa un error de conflicte.

Aplicar sense comprovar és la recepta de l'incident. Kubernetes ofereix quatre nivells de verificació, del més barat al més complet.

kubectl construeix l'objecte i valida l'esquema sense enviar res. Detecta errors de sintaxi YAML i camps inexistents. No detecta problemes de permisos, quotes ni webhooks. És també la bandera que vam fer servir a la lliçó anterior per generar manifests:

La petició sí que arriba a l'apiserver i recorre tot el camí de la lliçó 01-02 —autenticació, autorització RBAC, admissió, validació— però no s'escriu a etcd. Detecta el que el client no pot veure: manca de permisos, quotes superades, polítiques de seguretat de pods, webhooks d'admissió propis. És la validació que ha d'executar la teva canalització de CI abans de desplegar.

Aquesta és l'ordre que converteix un desplegament en una cosa revisable: et diu exactament què canviarà al clúster abans de canviar-ho. Hauria de ser un pas obligatori en qualsevol desplegament manual a producció. El seu codi de sortida és diferent de zero quan hi ha diferències, la qual cosa permet fer-lo servir en scripts.

Ja el vam veure a la lliçó anterior; aquí convé subratllar que és la resposta correcta a "existeix aquest camp i quin tipus té?" quan estàs escrivint un manifest.

Els manifests de Rutas Norte viuen al directori k8s/ del repositori del projecte, versionats a Git. Aquesta és l'estructura que farem servir durant tot el curs:

Convencions que seguirem:

Sobre l'ordre: aplicar un directori complet funciona perquè el model és reconciliador —un pod que no troba el seu ConfigMap es queda esperant i arrenca quan apareix—, però per evitar errors transitoris convé aplicar primer el namespace:

Un avís important per no envair mòduls posteriors: aquesta estructura de base/ i entorns/ és deliberadament YAML pla, sense plantilles. Quan la duplicació entre entorns es torni molesta, existeixen dues solucions estàndard —Helm (plantilles i empaquetat) i Kustomize (superposicions sense plantilles)— que s'estudien a les lliçons Helm i Kustomize. Aprendre primer el YAML pla no és temps perdut: és el que et permetrà entendre què generen aquestes eines.

• Fer servir tabuladors en YAML. Error de sintaxi pur. Configura l'editor: expandtab, 2 espais, i una extensió de YAML que validi en desar.
• Copiar apiVersion de tutorials antics. extensions/v1beta1 i apps/v1beta2 no existeixen. Verifica-ho sempre amb kubectl api-resources.
• Confondre el nom del kind amb el del recurs. kind: Deployment (CamelCase, singular) al YAML; kubectl get deployments (minúscules, plural) a la CLI.
• Valors sense cometes en ConfigMaps i Secrets. "3", "true", "NO". Aquests camps exigeixen cadenes i YAML converteix tipus alegrement.
• Editar el status a mà. No té cap efecte: l'escriu el controlador.
• Barrejar create i apply sobre el mateix objecte. Sense l'anotació last-applied, la fusió es pot comportar de manera inesperada. Comença sempre amb apply.
• Aplicar sense diff en producció. kubectl diff costa dos segons i evita desplegaments sorpresa.
• Desar un -o yaml com a manifest. La sortida del clúster inclou status, uid, resourceVersion, managedFields i creationTimestamp, que no s'han de versionar. Neteja-la (a mà o amb el plugin kubectl neat) abans de desar-la a k8s/.
• Consell: tracta el directori k8s/ com a codi. Revisió per petició de canvi, validació a CI amb --dry-run=server, i la regla d'or: si un canvi no és a Git, no existeix.

1. Escriu el manifest d'un ConfigMap anomenat botiga-web-config al namespace rutas-norte-dev, amb les etiquetes del projecte i dues claus: api_url amb valor http://api-reserves i mode_manteniment amb valor "NO". Explica per què el segon valor necessita cometes.
2. Esbrina amb kubectl, sense buscar a internet, a quina apiVersion pertanyen CronJob, Ingress i HorizontalPodAutoscaler, i quins d'ells són d'àmbit de namespace.
3. Comprova amb kubectl explain si el camp spec.containers.imagePullPolicy existeix en un Pod i quins valors admet.

Partint del manifest del pod api-reserves de la secció 1:

1. Valida'l en local sense tocar el clúster.
2. Aplica'l, i aplica'l una altra vegada sense canviar res. Què diu kubectl la segona vegada i per què?
3. Canvia la imatge a la versió 2.5.0 al fitxer i, abans d'aplicar, mostra exactament què canviaria al clúster.
4. Mostra el status.phase i la IP del pod fent servir jsonpath.
5. Explica quina diferència hi hauria si al pas 2 haguessis fet servir kubectl create en lloc d'apply.

Crea el fitxer k8s/base/redis-cache.yaml que contingui, en un sol fitxer i en l'ordre correcte, tres objectes:

1. Un ConfigMap redis-cache-config amb una clau redis.conf que contingui diverses línies de configuració (fes servir l'indicador literal).
2. Un Pod redis-cache amb la imatge redis:7.2-alpine.
3. Tot això a rutas-norte-dev, amb les etiquetes del projecte.

Després, indica quina ordre aplicaria el directori complet i per què convé aplicar abans namespace.yaml.

Solució 1

"NO" necessita cometes perquè YAML 1.1 interpreta NO (igual que no, yes, on, off) com el booleà false. El camp data d'un ConfigMap només admet cadenes, així que sense cometes l'apiserver rebutjaria l'objecte amb un error de tipus.

Tots tres són d'àmbit de namespace (NAMESPACED = true).

Solució 2

Al pas 2, la segona execució diu unchanged perquè apply és idempotent: kubectl compara l'anotació last-applied-configuration, el fitxer actual i l'objecte viu, no hi troba diferències i no envia cap modificació. Aquesta propietat és la que permet executar apply a cada desplegament d'una canalització sense efectes secundaris.

Amb kubectl create al pas 2, la primera vegada hauria funcionat i la segona hauria fallat amb Error from server (AlreadyExists), perquè create no fusiona: només sap crear objectes nous.

Solució 3

El ConfigMap va primer perquè el pod el consumirà i així s'evita un error transitori. Convé aplicar namespace.yaml per separat i abans perquè tots els altres objectes declaren namespace: rutas-norte-dev i, si aquest namespace encara no existeix, les seves creacions fallen amb namespaces "rutas-norte-dev" not found. El namespace és l'única dependència dura del conjunt.

Ja domines la unitat de treball de Kubernetes. Tot objecte té la mateixa anatomia —apiVersion, kind, metadata, spec que escrius tu i status que escriu el clúster—, pertany a un grup d'API la versió del qual has de verificar al teu propi clúster amb kubectl api-resources, i s'expressa en un YAML amb regles estrictes sobre indentació, tipus i cadenes multilínia. Has vist per què apply és superior a create i replace, com funciona la fusió de tres vies i la seva anotació last-applied, cap a on evoluciona el model amb server-side apply i la propietat de camps, i quina seqüència de validació —--dry-run=client, --dry-run=server, kubectl diff, kubectl explain— converteix un desplegament en una cosa predictible. I tens l'estructura del directori k8s/ que sostindrà el projecte durant la resta del curs.

Tens clúster, tens CLI i tens el llenguatge dels manifests. Només falta el pacient. A la lliçó següent, El Projecte del Curs: la Plataforma Rutas Norte, coneixeràs en detall l'empresa, cadascun dels sis components de la plataforma, l'arquitectura objectiu i les convencions del projecte; i acabaràs desplegant de debò el teu primer tros de Rutas Norte al clúster, veient-lo funcionar al teu navegador.