La bifurcación de entrada

The entry fork

Il bivio d'ingresso

READY no es STATUS

READY is not STATUS

READY non è STATUS

Un pod puede estar Running y 1/2: está corriendo, pero un container no pasa su readinessProbe. Para el Service, ese pod no existe (M6: no entra al EndpointSlice). Es el caso que más se confunde con "problema de red" sin serlo.

A pod can be Running and 1/2: it is running, but one container fails its readinessProbe. To the Service, that pod does not exist (M6: it never enters the EndpointSlice). It is the case most often mistaken for a "network problem" without being one.

Un pod può essere Running e 1/2: gira, ma un container non supera la sua readinessProbe. Per il Service, quel pod non esiste (M6: non entra nell'EndpointSlice). È il caso più spesso scambiato per un "problema di rete" senza esserlo.

Exit codes que hay que reconocer

Exit codes you must recognise

Exit code da riconoscere

De dónde salen los logs

Where logs come from

Da dove vengono i log

kubectl logs devuelve el stdout/stderr del proceso principal del container, tal como lo capturó el runtime. Si tu app escribe a un archivo dentro del container, ahí no aparece nada — y esa ausencia de logs es en sí misma un dato.

kubectl logs returns the container's main process stdout/stderr, exactly as the runtime captured it. If your app writes to a file inside the container, nothing shows up there — and that absence of logs is itself a data point.

kubectl logs restituisce lo stdout/stderr del processo principale del container, così come l'ha catturato il runtime. Se la tua app scrive su un file dentro il container, lì non compare nulla — e quell'assenza di log è essa stessa un dato.

Tabla de decisión

Decision table

Tabella decisionale

Las fases oficiales

The official phases

Le fasi ufficiali

Solo hay cinco: Pending, Running, Succeeded, Failed, Unknown. Todo lo demás que ves en la columna STATUS — CrashLoopBackOff, ImagePullBackOff, Init:0/2 — sale del estado de los containers, no de la fase. Saberlo evita buscar "la fase CrashLoopBackOff" en la doc.

There are only five: Pending, Running, Succeeded, Failed, Unknown. Everything else you see in the STATUS column — CrashLoopBackOff, ImagePullBackOff, Init:0/2 — comes from the containers' state, not the phase. Knowing that saves you searching the docs for "the CrashLoopBackOff phase".

Ce ne sono solo cinque: Pending, Running, Succeeded, Failed, Unknown. Tutto il resto che vedi nella colonna STATUS — CrashLoopBackOff, ImagePullBackOff, Init:0/2 — viene dallo stato dei container, non dalla fase. Saperlo evita di cercare "la fase CrashLoopBackOff" nella documentazione.

Init containers

Init:0/2 o Init:Error significa que el pod ni empezó: los init containers corren en orden y hasta completarse antes que los principales. Se depuran igual, apuntando al container: k logs app -c init-db.

Init:0/2 or Init:Error means the pod has not even begun: init containers run in order and to completion before the main ones. You debug them the same way, pointing at the container: k logs app -c init-db.

Init:0/2 o Init:Error significa che il pod non è nemmeno iniziato: gli init container girano in ordine e fino al completamento prima di quelli principali. Si debuggano allo stesso modo, puntando al container: k logs app -c init-db.

Terminating eterno

Eternal Terminating

Terminating eterno

Dos causas típicas: un finalizer que nadie resuelve, o el nodo desapareció y el kubelet no puede confirmar el borrado. El --force --grace-period=0 existe, pero borra el objeto de la API sin garantizar que el proceso murió: último recurso.

Two typical causes: a finalizer nobody resolves, or the node vanished and the kubelet cannot confirm the deletion. --force --grace-period=0 exists, but it removes the object from the API without guaranteeing the process died: last resort.

Due cause tipiche: un finalizer che nessuno risolve, o il nodo è sparito e il kubelet non può confermare la cancellazione. --force --grace-period=0 esiste, ma toglie l'oggetto dall'API senza garantire che il processo sia morto: ultima risorsa.

Consecuencias distintas

Different consequences

Conseguenze diverse

Los parámetros que importan

The parameters that matter

I parametri che contano

• initialDelaySeconds — cuánto espera antes del primer chequeo (default 0).
• periodSeconds — cada cuánto reintenta (default 10).
• failureThreshold — cuántos fallos seguidos hacen falta (default 3).
• timeoutSeconds — cuánto espera cada chequeo (default 1, cortito).

• initialDelaySeconds — how long it waits before the first check (default 0).
• periodSeconds — how often it retries (default 10).
• failureThreshold — how many consecutive failures are needed (default 3).
• timeoutSeconds — how long each check waits (default 1, very short).

• initialDelaySeconds — quanto aspetta prima del primo controllo (default 0).
• periodSeconds — ogni quanto riprova (default 10).
• failureThreshold — quanti fallimenti consecutivi servono (default 3).
• timeoutSeconds — quanto aspetta ogni controllo (default 1, cortissimo).

El primer chequeo sale a los initialDelaySeconds y de ahí en más cada periodSeconds. Como hace falta que fallen failureThreshold chequeos seguidos, el container se reinicia en el chequeo número failureThreshold, o sea alrededor de initialDelay + (failureThreshold − 1) × periodSeconds. Con esa cuenta explicás casi cualquier reinicio raro — y un solo éxito resetea el contador de fallos.

The first check fires at initialDelaySeconds and every periodSeconds thereafter. Since failureThreshold consecutive checks must fail, the container restarts on check number failureThreshold, i.e. around initialDelay + (failureThreshold − 1) × periodSeconds. That arithmetic explains almost any odd restart — and a single success resets the failure counter.

Il primo controllo parte a initialDelaySeconds e poi ogni periodSeconds. Poiché devono fallire failureThreshold controlli consecutivi, il container si riavvia al controllo numero failureThreshold, cioè intorno a initialDelay + (failureThreshold − 1) × periodSeconds. Con quel conto spieghi quasi ogni riavvio strano — e un solo successo azzera il contatore dei fallimenti.

startupProbe: para qué se inventó

startupProbe: why it was invented

startupProbe: perché è stata inventata

Apps que tardan mucho en levantar forzaban un initialDelaySeconds enorme en liveness — y entonces, ya en régimen, un cuelgue tardaba muchísimo en detectarse. La startupProbe separa los dos momentos: mientras corre, liveness y readiness quedan suspendidas; cuando pasa una vez, no vuelve a ejecutarse nunca y las otras dos entran con sus tiempos agresivos.

Apps that take long to come up forced a huge initialDelaySeconds on liveness — and then, in steady state, a hang took forever to be detected. The startupProbe separates the two moments: while it runs, liveness and readiness are suspended; once it passes a single time it never runs again and the other two kick in with their aggressive timings intact.

Le app lente ad avviarsi imponevano un initialDelaySeconds enorme sulla liveness — e poi, a regime, un blocco ci metteva un'eternità a essere rilevato. La startupProbe separa i due momenti: mentre gira, liveness e readiness restano sospese; quando passa una volta sola non viene più eseguita e le altre due entrano coi loro tempi aggressivi intatti.

Los cuatro errores clásicos

The four classic mistakes

I quattro errori classici

• Puerto de la probe ≠ puerto en el que escucha la app.
• Path que devuelve 404 (cualquier código fuera de 2xx/3xx es fallo).
• initialDelaySeconds corto → loop de reinicios en el arranque.
• Liveness que consulta una dependencia externa: si se cae la base, te reinicia toda la flota sin motivo.

• Probe port ≠ the port the app listens on.
• A path returning 404 (any code outside 2xx/3xx is a failure).
• A short initialDelaySeconds → a restart loop at start-up.
• A liveness probe that checks an external dependency: if the database goes down, it restarts your whole fleet for nothing.

• Porta della probe ≠ porta su cui ascolta l'app.
• Un path che restituisce 404 (qualsiasi codice fuori da 2xx/3xx è un fallimento).
• initialDelaySeconds corto → loop di riavvii all'avvio.
• Una liveness che interroga una dipendenza esterna: se cade il database, ti riavvia l'intera flotta per nulla.

El problema que resuelve

The problem it solves

Il problema che risolve

Las imágenes modernas son distroless: no traen shell, ni curl, ni ps. Con eso, kubectl exec deja de servir. Y los pods son inmutables: no podés agregarle un container a uno que ya corre… salvo por esta vía.

Modern images are distroless: no shell, no curl, no ps. With that, kubectl exec stops being useful. And pods are immutable: you cannot add a container to one that is already running… except this way.

Le immagini moderne sono distroless: niente shell, niente curl, niente ps. Con questo, kubectl exec smette di servire. E i pod sono immutabili: non puoi aggiungere un container a uno già in esecuzione… tranne per questa via.

Ephemeral containers

Un subrecurso especial del pod (ephemeralcontainers) que sí admite agregar containers en caliente. Comparten el network namespace del pod — misma IP, mismo localhost — y, con --target, también el espacio de procesos del container elegido. No admiten probes ni puertos, no se reinician, y desaparecen con el pod.

A special pod subresource (ephemeralcontainers) that does allow adding containers live. They share the pod's network namespace — same IP, same localhost — and, with --target, the process namespace of the chosen container too. They allow no probes or ports, never restart, and disappear with the pod.

Una sottorisorsa speciale del pod (ephemeralcontainers) che permette di aggiungere container a caldo. Condividono il network namespace del pod — stesso IP, stesso localhost — e, con --target, anche lo spazio dei processi del container scelto. Non ammettono probe né porte, non si riavviano, e spariscono col pod.

Los tres modos, en una tabla

The three modes, in one table

Le tre modalità, in una tabella

Por qué la copia

Why the copy

Perché la copia

Un container efímero no te salva de un CrashLoop: el pod original sigue reiniciándose. La copia te deja reemplazar el comando por un sh o un sleep, con las mismas imágenes, volúmenes y variables — y ahí sí entrás a mirar por qué el arranque falla. Ojo: es un pod suelto, no lo gestiona ningún controller, y lo tenés que borrar vos.

An ephemeral container does not save you from a CrashLoop: the original pod keeps restarting. The copy lets you replace the command with an sh or a sleep, keeping the same images, volumes and variables — and there you can finally look at why start-up fails. Careful: it is a loose pod, no controller manages it, and you must delete it yourself.

Un container effimero non ti salva da un CrashLoop: il pod originale continua a riavviarsi. La copia ti lascia sostituire il comando con un sh o uno sleep, con le stesse immagini, volumi e variabili — e lì puoi finalmente vedere perché l'avvio fallisce. Attenzione: è un pod sciolto, nessun controller lo gestisce, e devi cancellarlo tu.

Dos muertes distintas

Two different deaths

Due morti diverse

QoS: la clase que decide quién muere

QoS: the class that decides who dies

QoS: la classe che decide chi muore

Cuando un nodo se queda sin recursos, el kubelet tiene que matar pods para salvarse. No elige al azar ni por antigüedad: elige por clase de QoS, una etiqueta que Kubernetes le calcula a cada pod a partir de sus requests y limits (M5). Vos nunca la escribís; la deduce el sistema y la publica en status.qosClass.

When a node runs out of resources, the kubelet must kill pods to save itself. It does not choose at random or by age: it chooses by QoS class, a label Kubernetes computes for each pod from its requests and limits (M5). You never write it; the system deduces it and publishes it in status.qosClass.

Quando un nodo resta senza risorse, il kubelet deve uccidere pod per salvarsi. Non sceglie a caso né per anzianità: sceglie per classe QoS, un'etichetta che Kubernetes calcola per ogni pod a partire dalle sue requests e limits (M5). Tu non la scrivi mai; il sistema la deduce e la pubblica in status.qosClass.

Cómo se asigna, en tres reglas

How it is assigned, in three rules

Come si assegna, in tre regole

Se evalúa a nivel pod, no de container: un solo container sin resources arrastra a todo el pod a Burstable, y un solo campo desigual lo baja de Guaranteed a Burstable.

It is evaluated at the pod level, not the container level: a single container without resources drags the whole pod to Burstable, and a single unequal field drops it from Guaranteed to Burstable.

Si valuta a livello di pod, non di container: un solo container senza resources trascina l'intero pod a Burstable, e un solo campo diseguale lo fa scendere da Guaranteed a Burstable.

El orden del sacrificio

The order of sacrifice

L'ordine del sacrificio

Bajo presión el kubelet desaloja BestEffort → Burstable → Guaranteed. Dentro de Burstable hay un desempate que vale la pena saber: caen antes los pods que están consumiendo más por encima de su request. O sea que el request no es solo una reserva para el scheduler: también es la línea que define cuánto te "merecés" quedarte.

Under pressure the kubelet evicts BestEffort → Burstable → Guaranteed. Within Burstable there is a tiebreaker worth knowing: pods consuming furthest above their request fall first. So the request is not just a reservation for the scheduler: it is also the line defining how much you "deserve" to stay.

Sotto pressione il kubelet espelle BestEffort → Burstable → Guaranteed. Dentro Burstable c'è uno spareggio che vale la pena sapere: cadono prima i pod che consumano più sopra la loro request. Quindi la request non è solo una prenotazione per lo scheduler: è anche la linea che definisce quanto "meriti" di restare.

Por eso poner requests no es burocracia. Un pod BestEffort corre igual de bien que cualquier otro… hasta el primer apretón de memoria, y ahí es el primero en desaparecer.

That is why setting requests is not bureaucracy. A BestEffort pod runs just as well as any other… until the first memory squeeze, and then it is the first to vanish.

Per questo mettere le requests non è burocrazia. Un pod BestEffort gira bene come qualsiasi altro… fino alla prima stretta di memoria, e lì è il primo a sparire.

QoS y OOMKilled no son lo mismo

QoS and OOMKilled are not the same

QoS e OOMKilled non sono la stessa cosa

El eviction por QoS lo decide el kubelet, mirando el nodo entero, y se lleva pods completos. El OOMKilled lo decide el kernel cuando un container pasa su propio limit de memoria, sin importar qué clase tenga: un pod Guaranteed que se excede muere igual. Distinta causa, distinto ejecutor, distinto síntoma.

A QoS eviction is decided by the kubelet, looking at the whole node, and it takes entire pods. OOMKilled is decided by the kernel when a container passes its own memory limit, regardless of class: a Guaranteed pod that overshoots dies just the same. Different cause, different executioner, different symptom.

L'eviction per QoS la decide il kubelet, guardando l'intero nodo, e si porta via pod interi. L'OOMKilled lo decide il kernel quando un container supera il proprio limit di memoria, indipendentemente dalla classe: un pod Guaranteed che eccede muore lo stesso. Causa diversa, esecutore diverso, sintomo diverso.

metrics-server no viene incluido

metrics-server is not included

metrics-server non è incluso

kubectl top consulta la Metrics API, que sirve un addon aparte. Si no está instalado, el comando falla — y eso no significa que el cluster esté roto. Sin él te quedan los describe, que muestran requests/limits pero no consumo real.

kubectl top queries the Metrics API, served by a separate addon. If it is not installed, the command fails — and that does not mean the cluster is broken. Without it you still have describe, which shows requests/limits but not real usage.

kubectl top interroga la Metrics API, servita da un addon a parte. Se non è installato, il comando fallisce — e non significa che il cluster sia rotto. Senza di esso ti restano i describe, che mostrano requests/limits ma non il consumo reale.

Las 7 ideas que no se negocian

The 7 non-negotiable ideas

Le 7 idee non negoziabili

• ¿Arrancó o no arrancó? No arrancó → Events. Arrancó y murió → logs --previous. Todo el método cuelga de esa pregunta.
• describe siempre primero, y los Events se leen de abajo hacia arriba. Expiran en una hora.
• CrashLoopBackOff es el síntoma, no la causa: la causa está en Last State + Exit Code + logs previos.
• READY 0/1 con STATUS Running = readinessProbe, y por lo tanto Service sin endpoints. No es la red.
• RESTARTS que sube sin errores en los logs = livenessProbe matándolo.
• kubectl debug para imágenes sin shell: efímero si el pod vive, --copy-to si crashea.
• La clase de QoS no se declara, se deduce de requests y limits — y define el orden de eviction: BestEffort cae primero.

• Did it start or not? It did not → Events. It started and died → logs --previous. The whole method hangs off that question.
• describe first, always, and Events are read bottom-up. They expire within an hour.
• CrashLoopBackOff is the symptom, not the cause: the cause is in Last State + Exit Code + previous logs.
• READY 0/1 with STATUS Running = readinessProbe, and therefore a Service with no endpoints. It is not the network.
• RESTARTS climbing with no errors in the logs = a livenessProbe killing it.
• kubectl debug for shell-less images: ephemeral if the pod lives, --copy-to if it crashes.
• The QoS class is not declared, it is deduced from requests and limits — and it sets the eviction order: BestEffort falls first.

• È partito o no? Non è partito → Events. È partito ed è morto → logs --previous. Tutto il metodo pende da quella domanda.
• describe sempre per primo, e gli Events si leggono dal basso verso l'alto. Scadono entro un'ora.
• CrashLoopBackOff è il sintomo, non la causa: la causa è in Last State + Exit Code + log precedenti.
• READY 0/1 con STATUS Running = readinessProbe, e quindi Service senza endpoint. Non è la rete.
• RESTARTS che sale senza errori nei log = una livenessProbe che lo uccide.
• kubectl debug per immagini senza shell: effimero se il pod vive, --copy-to se crasha.
• La classe QoS non si dichiara, si deduce da requests e limits — e stabilisce l'ordine di eviction: BestEffort cade per primo.