Java su Kubernetes

Sezione · Informatica

Java su Kubernetes

Portare una REST API Java o Spring Boot su Kubernetes non è solo “mettere il jar in un’immagine”. La JVM legge i limiti del container, dimensiona heap e garbage collector, parte con calma e va spenta senza tagliare le richieste in corso. Questa guida mette in fila le decisioni che contano: versione, memoria, GC, probe e diagnostica.

Versioni documentate: Java 25 LTS come scelta consigliata per le nuove applicazioni REST, con Java 21 LTS ancora ottimo e Java 17 LTS in manutenzione. Java 27 (15 settembre 2026) è la release più recente ma non è LTS. Lato framework: Spring Boot 4.1.2 (22 ottobre 2026), compatibile da Java 17 a Java 27. Contesto Kubernetes: versione 1.37, come nella guida Kubernetes.

In evidenza

Il modello mentale in quattro numeri

Per una REST API Spring Boot di dimensioni normali, il punto di partenza ragionevole è: 1–2 CPU e 1–2 GiB per Pod, heap al 70–75% del limite, requests uguali ai limits. Da lì si misura, non si indovina.

Perché Java su Kubernetes è diverso

Su una macchina virtuale la JVM è spesso l’unico inquilino: vede tutta la RAM, usa tutti i core e nessuno la uccide se il processo cresce. In un container le regole cambiano. Il kernel applica un limite di memoria al processo completo, non al solo heap. La CPU è una quota, non un numero di core fisici. Il file system può essere di sola lettura. Il Pod nasce, riceve traffico e muore molte volte, mentre la JVM vorrebbe scaldarsi con calma.

La JVM moderna sa leggere i limiti del container, ma solo se i limiti esistono e se la versione è abbastanza recente. Da lì in poi tutte le scelte si tengono: la percentuale di heap, il garbage collector, il numero di thread, le probe e il tempo di spegnimento. Un valore sbagliato non rompe la compilazione: si manifesta in produzione come OOMKilled, latenza a singhiozzo o un rollout che restituisce 503.

Questa guida parla di applicazioni REST: processi che restano in piedi, servono richieste brevi e devono rispondere con latenza prevedibile. I batch hanno esigenze diverse — throughput, checkpoint, esecuzioni lunghe — e meritano una trattazione separata.

Cosa cambia rispetto a una VM

AspettoMacchina virtualePod KubernetesConseguenza per la JVM
MemoriaRAM della VM, spesso tutta disponibileresources.limits.memory per containerL’heap deve lasciare spazio a metaspace, stack, code cache e buffer.
CPUCore fisici o vCPUQuota e periodo cgroup, con throttlingIl numero di processori effettivi cambia il parallelism del GC e dei pool.
DiscoRootfs scrivibile e persistenteLayer immutabile, spesso read-onlyLog su stdout, dump e file temporanei su un volume scrivibile.
ReteIP e hostname stabiliIP del Pod effimero, DNS del ServiceLe dipendenze si raggiungono per nome, non per indirizzo.
VitaMesi, con manutenzione pianificataRollout, eviction, riavviiStartup e shutdown fanno parte del contratto, non sono casi limite.
LogFile locali, rotazione a cura del sistemastdout/stderr raccolti dal runtimeIl GC log va su stdout, non in un file dentro il container.
ConfigurazioneFile e variabili d’ambienteConfigMap, Secret, volumiLe modifiche non sono sempre live: spesso serve un restart.

Il confine è il cgroup

La JVM non legge “la memoria del Pod”: legge il limite del cgroup a cui appartiene il processo. Se il limite c’è, usa quello per calcolare l’heap massimo; se manca, vede la memoria del nodo. Su un nodo da 64 GiB un container senza limiti può ricevere una JVM che pianifica un heap enorme, e il kernel la uccide alla prima crescita seria. Il flag -XX:+UseContainerSupport è attivo per default sulle versioni moderne: non va aggiunto, e soprattutto non va disattivato.

Il default di -XX:MaxRAMPercentage è 25%. È un valore prudente per la JVM, ma quasi mai quello che vuole un’applicazione Spring Boot, che di solito può usare il 70–75% del limite lasciando il resto al non-heap. La percentuale si applica al limite del cgroup, non alle requests: le requests servono a Kubernetes per schedulare e a te per capire quanto margine hai, non alla JVM per dimensionarsi.

Schema della memoria di una JVM dentro un Pod Kubernetes: limite di 1 GiB, heap al 75 per cento, spazio non-heap per metaspace, code cache, stack dei thread e buffer diretti. Se l'heap occupa tutto il limite, il container viene terminato con OOMKilled.
Il limite del container vale per tutto il processo. L’heap è solo la parte più visibile: metaspace, code cache, stack dei thread, buffer diretti e strutture del GC vivono nello stesso budget. Illustrazione Adripedia, concetti dalla documentazione HotSpot e Kubernetes.

La trappola classica: heap uguale al limite

È l’errore più comune, ed è comprensibile: si imposta -Xmx1g perché il Pod ha limits.memory: 1Gi. Sembra coerente. In realtà l’heap può arrivare a 1 GiB, ma il processo usa anche tutto il resto: a un certo punto il kernel non ha più memoria da dare e termina il container con SIGKILL. Kubernetes lo mostra come OOMKilled, exit code 137. Non c’è heap dump, non c’è un’eccezione Java, spesso non c’è nemmeno un log: il processo non ha avuto il tempo di scriverlo.

# Da non fare: l'heap occupa tutto il container
resources:
  limits:
    memory: 1Gi
env:
  - name: JAVA_TOOL_OPTIONS
    value: "-Xmx1g"

# Meglio: percentuale sul limite, con margine per il non-heap
env:
  - name: JAVA_TOOL_OPTIONS
    value: "-XX:MaxRAMPercentage=70.0 -XX:+ExitOnOutOfMemoryError"

-XX:+ExitOnOutOfMemoryError non evita l’errore, ma cambia il modo in cui lo si scopre: quando la JVM lancia un OutOfMemoryError che lei stessa ha generato, esce con codice 3 e lascia un messaggio Terminating due to java.lang.OutOfMemoryError. È molto meglio di un processo mezzo vivo che risponde 200 alle probe e 500 alle richieste. Non copre però tutti i casi: un esaurimento di memoria diretta o l’impossibilità di creare un thread nativo possono non passare da quel percorso.

Quanto dare a un Pod Java

Non esiste un numero universale, ma esistono ordini di grandezza utili. Una REST API Spring Boot con Tomcat, Jackson, Hibernate e un pool JDBC ha bisogno di più memoria di un “hello world”. Sotto 1 GiB si entra nella zona in cui il non-heap mangia il margine e i sintomi diventano difficili da distinguere da un memory leak.

ProfiloCPU (request = limit)MemoriaHeap indicativoQuando ha senso
Minimo di laboratorio500m512Mi~350MiSolo demo o servizi minuscoli, senza Hibernate e con pochi thread.
REST piccola11Gi~700MiUn’API con poche dipendenze, traffico modesto, 2–3 repliche.
REST standard22Gi~1.5GiSpring Boot con JPA, cache locale, pool JDBC e carichi variabili.
Servizio esigente44–8Gi3–6GiMolte classi, molti thread, payload grandi o latenza stretta.

La CPU conta quanto la memoria. Con un limite di 500m la JVM vede meno di un core effettivo, il GC ha pochi thread e lo startup si allunga. Un Pod Java con 1 CPU è accettabile per un servizio piccolo; per un’applicazione Spring Boot completa, 2 CPU rendono la vita più prevedibile. Se il limite CPU è troppo basso, il container viene throttled e ogni picco di GC si trasforma in latenza.

Mappa della guida

TabCosa risolveDa leggere se…
Versioni e JVMJava 8, 17, 21, 25 e 27; Spring Boot; immagini e vendor.Devi scegliere la combinazione da mettere in produzione o migrare un’app esistente.
Memoria e GCHeap, non-heap, G1, ZGC, virtual threads e flag di osservabilità.Hai già un Pod e vuoi evitare OOMKilled o pause imprevedibili.
Kubernetes e Spring BootDockerfile, Deployment, probe, graceful shutdown, sicurezza e scalabilità.Devi scrivere o rivedere i manifest.
Comandi e diagnosticaComandi JVM e kubectl, tabelle sintomo/causa, FAQ.Qualcosa non funziona e serve una pista concreta.
Una nota di metodo: i numeri di questa guida sono punti di partenza, non dogmi. La sequenza giusta è sempre la stessa: misura il consumo reale con NMT e le metriche, confronta heap e RSS, poi regola. Un flag copiato senza misurare è solo una supposizione con la sintassi giusta.