Al final de la lliçó anterior tenies un clúster arrencat i verificat amb un parell d'ordres manllevades. Ara anem a per l'eina en si. kubectl és el client oficial de l'API de Kubernetes i serà, de bon tros, el programa que més facis servir en aquest curs i en la teva vida professional amb Kubernetes: crear, consultar, inspeccionar, depurar i esborrar hi passen tots. La bona notícia és que kubectl és extraordinàriament regular: un cop n'entens la gramàtica, saps fer-lo servir amb qualsevol tipus d'objecte, inclosos els que encara no existeixen. Aquesta lliçó t'ensenya aquesta gramàtica, el fitxer de configuració que decideix amb quin clúster parles, els verbs que faràs servir cada dia sobre els components de Rutas Norte, els formats de sortida que converteixen kubectl en una eina de consulta seriosa, i els ajustos de productivitat que separen qui es baralla amb el clúster de qui hi treballa amb desimboltura.

1. Què és kubectl i instal·lació
2. El fitxer kubeconfig: clústers, usuaris i contextos
3. Anatomia d'una ordre kubectl
4. Els verbs del dia a dia
5. Formats de sortida i consultes
6. Selecció per etiquetes i observació en viu
7. Imperatiu enfront de declaratiu
8. Productivitat: àlies, autocompletat, explain i plugins

kubectl no té intel·ligència pròpia: tradueix les teves ordres a peticions HTTPS contra el kube-apiserver. Tot el que pot fer kubectl ho podria fer curl amb el certificat adequat; el que aporta és comoditat, format i validació local.

Conseqüència pràctica: qualsevol cosa que kubectl no et deixi fer, te la està prohibint el servidor (RBAC), no l'eina.

Linux:

macOS:

Windows (PowerShell):

Verificació:

Regla de compatibilitat (version skew): kubectl admet una diferència d'una versió menor amunt o avall respecte al servidor. Un client 1.30 funciona amb servidors 1.29, 1.30 i 1.31. Amb diferències més grans poden fallar ordres concretes de manera poc evident, així que mantén el client a prop del servidor.

Quan a la lliçó anterior minikube va dir "kubectl is now configured to use rutas-norte", el que va fer va ser escriure a ~/.kube/config. Aquest fitxer respon a tres preguntes: a quin servidor parlo?, amb quines credencials? i en quin namespace per defecte?

La idea clau: un context és una terna (clúster, usuari, namespace). Canviar de context és canviar de clúster o d'identitat amb una sola ordre. En un entorn professional tindràs contextos com rutas-norte-dev, rutas-norte-pre i rutas-norte-pro, i equivocar-te de context és la manera més ràpida de provocar un incident.

Aquesta última ordre —fixar el namespace per defecte— t'estalviarà escriure -n rutas-norte-dev centenars de vegades durant el curs. Fes-ho tan bon punt creïs el namespace a la lliçó 01-07.

Variable KUBECONFIG: pots tenir diversos fitxers i combinar-los. És l'habitual quan treballes amb diversos clients o entorns:

Consell de seguretat: el kubeconfig conté credencials. Tracta'l com una clau privada: permisos 600, mai a Git, mai per xat.

Tota la CLI segueix aquesta gramàtica:

Exemples llegits en veu alta:

Kubernetes accepta singular, plural i abreviatura indistintament. kubectl get po, kubectl get pod i kubectl get pods són idèntics. Les abreviatures que més estalvien:

La llista completa i autoritativa del teu clúster, amb abreviatures, grup d'API i si el recurs viu en un namespace:

La columna NAMESPACED és important: explica per què kubectl get nodes -n rutas-norte-dev ignora el namespace (els nodes són d'àmbit de clúster).

Oblidar el namespace és la causa número u de "el meu pod ha desaparegut".

Treballarem sobre un escenari de Rutas Norte amb la botiga web i l'API ja desplegades a rutas-norte-dev.

Com llegir cada columna:

• READY 1/1: contenidors llestos / contenidors totals del pod. 0/1 significa que el contenidor existeix però no ha superat la seva sonda de disponibilitat.
• STATUS: Running és el normal; Pending (el scheduler no troba lloc), ContainerCreating, ImagePullBackOff (no pot descarregar la imatge), CrashLoopBackOff (arrenca i mor en bucle), Completed (tasques acabades).
• RESTARTS: reinicis. Un nombre que creix és el senyal més clar d'un problema.
• AGE: des de la creació de l'objecte.

En aquesta sortida, worker-notificacions està clarament trencat. Els tres verbs següents són com s'investiga.

La secció Events és el primer que cal llegir sempre. És el diari del que el clúster ha intentat fer amb aquell objecte i per què ha fallat. Aquí ens diu que el contenidor acaba amb codi 1 i el kubelet el reintenta amb espera creixent. També veiem que el scheduler sí que el va assignar (per tant no és un problema de recursos) i que la imatge es va descarregar bé (per tant no és un problema de registre): la fallada és dins de l'aplicació.

describe funciona amb qualsevol tipus: kubectl describe node rutas-norte, kubectl describe svc api-reserves, kubectl describe pvc dades-postgres.

Aquí hi ha la causa: el worker no troba redis-cache per DNS, probablement perquè el Service encara no existeix. --previous és la bandera que més s'oblida i la més útil: sense ella, en un CrashLoopBackOff veuràs els logs d'un contenidor que acaba d'arrencar i encara no ha fallat.

El -- separa les banderes de kubectl de l'ordre a executar a dins; oblidar-lo és un error clàssic. -it significa interactiu amb terminal, igual que a Docker.

Nota professional: moltes imatges ben construïdes són distroless i no tenen ni sh ni eines de xarxa. Per a aquests casos existeix kubectl debug, que injecta un contenidor efímer amb utilitats; ho veurem al mòdul 7.

apply és el cor del model declaratiu i l'estudiarem a fons a la lliçó següent, Objectes, Manifests YAML i el Model Declaratiu.

Sobre delete: recorda que l'esborrat és asíncron i que esborrar un pod gestionat per un controlador no l'elimina, només provoca que se'n creï un de nou. Per eliminar-lo de debò cal esborrar el controlador.

Obre l'objecte al teu editor ($EDITOR) i en desar aplica els canvis. És còmode per experimentar i perillós en producció: el canvi no queda a Git, així que el següent apply des del repositori el revertirà silenciosament. Fes-lo servir per explorar; mai com a forma de desplegar.

Ara http://localhost:8080 arriba a aquell pod. El format és port-local:port-del-contenidor. També funciona contra un Service (svc/api-reserves 8081:80). És la manera més ràpida de comprovar que alguna cosa funciona abans de tenir Ingress, i és exactament el que faràs servir a la lliçó 01-07 per veure la botiga de Rutas Norte al teu navegador. El procés queda en primer pla: es talla amb Ctrl+C.

Aquesta ordre mereix un paràgraf a part perquè és la que més rendibilitat té a llarg termini. Consulta l'esquema del teu propi clúster, inclosos els CRDs instal·lats, així que mai no et dona informació desactualitzada ni d'una altra versió. Funciona a qualsevol profunditat i amb --recursive mostra l'arbre complet de camps:

A la certificació CKA/CKAD, on només es permet consultar la documentació oficial, kubectl explain és la drecera que estalvia minuts.

La bandera -o transforma kubectl de visor en eina de consulta.

custom-columns i jsonpath són les dues eines que converteixen kubectl en una cosa apta per a auditories ràpides: "dona'm totes les imatges en ús a producció", "digues-me quins pods no tenen límits de memòria".

Recorda de la lliçó Conceptes i Terminologia Clau que les etiquetes són el mecanisme d'acoblament del sistema. La bandera -l et dona accés a aquest mateix mecanisme des de la CLI:

Aquesta última consulta és la raó per la qual val la pena ser disciplinat amb l'esquema d'etiquetes del projecte: et permet veure, esborrar o inspeccionar la plataforma sencera amb una sola ordre.

Observació en viu amb --watch (o -w): l'ordre no acaba i va imprimint els canvis a mesura que passen. És la millor manera de veure el bucle de reconciliació en acció:

Reconeixes aquesta seqüència: és exactament el recorregut de la lliçó Arquitectura de Kubernetes —Pending mentre el scheduler decideix, ContainerCreating mentre el kubelet treballa, Running quan el contenidor viu— passant davant dels teus ulls perquè el ReplicaSet ha reposat un pod esborrat.

Ordres germanes que també esperen:

kubectl admet els dos estils i convé tenir criteri sobre quan fer servir cadascun.

El punt intermedi, i probablement el truc més útil de tota la lliçó: generar el manifest amb una ordre imperativa i desar-lo, fent servir --dry-run=client -o yaml.

Això no crea res al clúster: només imprimeix el YAML que kubectl hauria enviat. L'edites, el versiones i l'apliques. És la manera habitual de no escriure manifests des de zero, i a la CKAD és pràcticament obligatori per arribar a temps. La lliçó següent aprofundeix en --dry-run, kubectl diff i la mecànica interna d'apply.

Afegeix això al teu ~/.bashrc o ~/.zshrc. La diferència de comoditat és enorme:

Per a zsh, substitueix completion bash per completion zsh. Amb això, k get po -n <TAB> et completa fins i tot els noms dels namespaces existents, perquè l'autocompletat consulta l'API.

Altres eines que convé conèixer, encara que no les fem servir encara:

Instal·lar krew i un plugin, a tall d'exemple:

Res d'això no és imprescindible, però en un dia de feina real estalvia hores. L'essencial és l'anterior: àlies, autocompletat i kubectl explain.

• Treballar al context equivocat. L'error més car de tots. Abans de qualsevol ordre destructiva, kubectl config current-context. Configura el teu prompt per mostrar context i namespace (kube-ps1, starship, oh-my-zsh) i tracta-ho com a innegociable tan bon punt tinguis accés a un entorn de producció.
• Oblidar el namespace. Si un objecte "no existeix", prova-ho amb -A abans de concloure res. Fixa el namespace per defecte amb kubectl config set-context --current --namespace=....
• Llegir logs sense --previous en un CrashLoopBackOff. Veuràs l'arrencada del contenidor actual, no l'error que va matar l'anterior.
• Ometre el -- a kubectl exec. Sense ell, kubectl interpreta les banderes de la teva ordre com a seves i falla de manera confusa.
• Fer servir kubectl edit com a mètode de desplegament. El canvi no queda enlloc i es perd en el següent apply. Serveix per investigar, no per operar.
• Creure que kubectl delete pod elimina l'aplicació. Si hi ha un controlador al darrere, el pod torna. Cal esborrar el Deployment, o millor, el manifest amb kubectl delete -f.
• Ignorar kubectl explain. És documentació exacta de la teva versió, sense connexió a internet i sense canviar de finestra. Acostuma't a fer-lo servir abans que a buscar al web.
• Consell: memoritza aquest trio de diagnòstic i aplica'l sempre en aquest ordre — kubectl get (existeix i en quin estat?), kubectl describe (què ha intentat el clúster i què diuen els esdeveniments?), kubectl logs (què diu l'aplicació?). Resol la gran majoria de les incidències.

Sobre el teu clúster rutas-norte:

1. Mostra el context actiu i comprova que és el correcte.
2. Crea el namespace rutas-norte-dev i fixa'l com a namespace per defecte del context.
3. Llista tots els pods del clúster, de tots els namespaces, mostrant el node i la IP.
4. Esbrina, sense sortir del terminal i sense buscar a internet, què significa el camp spec.restartPolicy d'un pod i quins valors admet.
5. Mostra els pods de kube-system ordenats per antiguitat, del més antic al més recent.

L'equip de seguretat de Rutas Norte demana un inventari. Escriu les ordres que responen a:

1. Totes les imatges en ús al clúster, amb el pod i el namespace al qual pertanyen, en format de taula.
2. Els pods de tot el clúster ordenats per nombre de reinicis, per localitzar els inestables.
3. Només els noms dels pods que tinguin l'etiqueta app.kubernetes.io/part-of=rutas-norte, en format apte per encadenar amb una altra ordre.
4. Tots els recursos del clúster que no viuen en un namespace.

Sense crear res al clúster, genera el manifest YAML d'un pod anomenat botiga-web amb la imatge registry.rutasnorte.example/botiga-web:1.8.0, desa'l a k8s/base/botiga-web-pod.yaml, i després explica quina diferència hi ha entre executar aquella ordre amb --dry-run=client i sense. Com a comprovació addicional, esbrina amb kubectl si el recurs Pod pertany al grup d'API core o a apps.

Solució 1

Solució 2

El punt 3 retorna línies del tipus pod/api-reserves-6c8d7f9b45-2xk9p, que es poden passar directament a kubectl delete o kubectl describe. El punt 4 llista nodes, namespaces, persistentvolumes, storageclasses, clusterroles, entre d'altres: els recursos d'àmbit de clúster que vam veure a la lliçó de conceptes.

Solució 3

Diferència: amb --dry-run=client, kubectl construeix l'objecte localment i l'imprimeix, sense enviar res al servidor; no es crea cap pod i ni tan sols cal que el clúster estigui arrencat. Sense aquesta bandera, la petició s'envia a l'apiserver, passa autenticació, autorització i admissió, s'escriu a etcd i el pod es crea de debò. Existeix a més --dry-run=server, que sí que envia la petició però indica al servidor que no la persisteixi: valida contra els webhooks d'admissió reals sense crear res. Ho veurem a la lliçó següent.

Per al grup d'API:

La columna APIVERSION mostra v1 a seques, sense barra ni prefix de grup: això significa que Pod pertany al grup core (o "legacy"), a diferència de Deployment, que apareix com a apps/v1.

kubectl és un client HTTP amb una gramàtica molt regular: verb, tipus, nom i banderes. Dominar-lo consisteix a interioritzar aquesta gramàtica, saber sempre en quin context i namespace estàs treballant, manejar amb desimboltura el trio de diagnòstic get → describe → logs, i aprofitar els formats de sortida i la selecció per etiquetes per convertir la CLI en una eina de consulta real. Amb kubectl explain tens a més documentació exacta del teu propi clúster sense sortir del terminal, i amb els àlies i l'autocompletat la feina diària deixa de ser teclejar.

En aquesta lliçó hem fet servir apply sense explicar del tot què fa per dins, i hem vist manifests YAML sense desmenuçar-ne l'estructura. Aquest deute el salda la lliçó següent, Objectes, Manifests YAML i el Model Declaratiu: anatomia camp a camp d'un objecte, grups i versions de l'API, el YAML que cal saber, la diferència real entre apply, create i replace, les eines de validació prèvia i com organitzar els manifests de Rutas Norte al directori k8s/.