AKS non può scaricare l’immagine da un registry privato dietro la tua VPN
Il kubelet scarica attraverso la rete del node, non attraverso la VPN del pod. Decidi in base alle route del node, al DNS del node, a ogni endpoint toccato dallo scaricamento, poi TLS e identità.
Il tuo portatile scarica l’immagine senza problemi, ma il pod resta in ImagePullBackOff e qualcuno propone di eseguire il client VPN aziendale come sidecar. Non aiuterà: lo scaricamento avviene prima che il container esista. Il kubelet chiede al runtime sul node di recuperare l’immagine, e il runtime usa il namespace di rete del node. Una VPN dentro il workload non ha route da offrire a quel percorso, e la sua immagine ausiliaria va scaricata prima.
L’ordine delle operazioni decide il livello
Prima viene la risoluzione del nome, poi connessione, autenticazione, download dei layer e solo dopo l’avvio del container. Tutto ciò che il pod fa con la VPN avviene dopo quella sequenza, quindi un tunnel che funziona nel cluster non è prova sullo scaricamento.
Per questo un’immagine in cache è una bugia così convincente. Un node che ha scaricato l’immagine settimane fa continua a servirla, il deployment sembra sano, e il guasto compare solo quando lo scheduler colloca una replica su un node più recente. Se la cronologia include scale-up, sostituzione di node o upgrade del pool, trattali come innesco, non come causa.
Tre condizioni decidono la riparazione
La raggiungibilità di un registry privato si riduce a instradamento, risoluzione dei nomi e insieme di endpoint. Se la subnet del node non può instradare verso la rete del registry, nessuna credenziale aiuta. Se instrada ma non risolve il nome tramite il percorso DNS del node, la connessione non parte. Se entrambi funzionano per il manifest ma non per il blob a cui il registry reindirizza, lo scaricamento fallisce a metà.
| Condition | Typical symptom | Where to look |
|---|---|---|
| Node subnet has no route to the registry network | Timeout, no connection | Effective routes on the node NIC, gateway transit, return path on-premises |
| Node resolver cannot see the private zone | Name resolution failure in events | VNet DNS settings and the resolver the node actually uses |
| Only the manifest endpoint is reachable | Auth succeeds, layer download fails | Every hostname the registry hands out during the pull |
| TLS or identity is wrong | Certificate error, 401 or 403 | Server certificate name and trust, scoped pull identity |
Il solo peering VNet non dà ogni combinazione di gateway transit, e una route che esiste in una direzione non è una route che funziona. Il node ha bisogno di un percorso supportato tramite il gateway VPN previsto, e il lato registry di una route di ritorno alla subnet del node.
Leggi il guasto prima di scegliere la correzione
Parti dagli eventi del pod e dal node su cui è atterrato, con i tuoi nomi reali: kubectl describe pod app-example -n team-example e kubectl get pod app-example -n team-example -o wide. Il testo dell’evento distingue un hostname non risolto da un timeout, un rifiuto di certificato da un’immagine mancante, e un errore di autorizzazione da tutto il resto.
L’autenticazione è la leva più sopravvalutata. imagePullSecret fornisce al runtime le credenziali del registry; non installa route, non cambia il resolver del node e non rende valido un certificato non fidato. Se l’evento dice che lo scaricamento non era autorizzato, guarda l’ambito dell’identità; se dice che la connessione è scaduta, le credenziali sono irrilevanti.
La documentazione Kubernetes sulle immagini è il riferimento per il comportamento di scaricamento e le credenziali dei registry privati, e vale una lettura prima di cambiare la rete, perché rende esplicito il confine tra autenticazione e trasporto.
Costruisci il percorso sotto il pod
Lavora in questo ordine. Instrada prima la rete del node: conferma che la subnet ha un percorso supportato verso la rete del registry, controlla le route effettive sul node, le regole di sicurezza ai due estremi e la route di ritorno lato registry.
Poi risolvi il nome dal contesto del node. Il resolver del node non è la configurazione DNS del pod, e il successo dentro un pod non è prova sul runtime host. Usa DNS privato gestito invece di una voce hosts permanente; la voce sopravvive fino alla sostituzione del node e poi sparisce in silenzio.
Poi dimostra ogni endpoint. Un registry può dare al client un servizio di autenticazione separato e uno storage blob separato. Raggiungere il manifest non dimostra quasi nulla sui layer. Infine completa TLS e autorizzazione: un certificato valido per il nome del registry e fidato tramite configurazione node supportata, più un’identità di scaricamento limitata alla lettura di quel repository.
Verificalo su un node che non hai riparato a mano
Il test che conta è uno scaricamento nuovo e un download completo di tutti i layer su un node idoneo, idealmente creato da scale-up o sostituzione. Copre tutti i pool che potrebbero collocare il workload, inclusi quelli dimenticati. Una riparazione manuale su un node non è un modello di distribuzione, e il prossimo evento di autoscaling troverà il buco.
Ricreare il cluster in un’altra VNet può cambiare il percorso, ma è l’ultima risorsa e non il primo passo diagnostico. Confronta la rete dei node esistente con la route privata necessaria e con i controlli di rete AKS supportati prima di proporre una migrazione, e tieni la connettività dell’applicazione dopo l’avvio come verifica separata: il pod che parla col suo backend è un controllo diverso dal node che scarica l’immagine.