AKS non pode descargar a imaxe dun rexistro privado detrás da túa VPN
O kubelet descarga pola rede do nodo, non pola VPN do pod. Decide por rutas do nodo, DNS do nodo, cada endpoint que toca a descarga, e despois TLS e identidade.
O teu portátil descarga a imaxe sen problema, pero o pod queda en ImagePullBackOff e alguén propón executar o cliente VPN corporativo como sidecar. Non axudará: a descarga ocorre antes de que exista o teu contedor. O kubelet pide ao runtime do nodo que traia a imaxe, e o runtime usa o espazo de nomes de rede do nodo. Unha VPN dentro do workload non ten ruta que ofrecer a ese camiño, e a súa propia imaxe auxiliar ten que descargarse primeiro.
A orde das operacións decide a capa
Primeiro vén a resolución do nome. O kubelet, mediante o runtime, resolve o nome do rexistro, conecta, autentica, descarga as capas e só entón inicia o contedor. Todo o que o pod fai cunha VPN ocorre despois desa secuencia, así que un túnel que funciona no clúster non é proba sobre a descarga.
Por iso unha imaxe en caché é unha mentira tan convincente. Un nodo que descargou a imaxe hai semanas séguena servindo, o despregamento parece san e o fallo só aparece cando o planificador coloca unha réplica nun nodo máis novo. Se a liña de tempo inclúe un escalado, unha substitución de nodo ou unha actualización do pool, trátaos como o disparador, non como a causa.
Tres condicións deciden a reparación
A accesibilidade a un rexistro privado desde un pool xestionado redúcese a encamiñamento, resolución de nomes e conxunto de endpoints. Se a subrede do nodo non pode encamiñar á rede do rexistro, ningunha credencial axudará. Se encamiña pero non resolve o nome pola ruta DNS do nodo, a conexión nunca comeza. Se ambos funcionan para o endpoint de manifesto pero non para o de blob ao que o rexistro redirixe, a descarga falla a metade.
| 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 |
O peering de VNet por si só non che dá todas as combinacións de gateway transit, e unha ruta que existe nun sentido non é unha ruta que funcione. O nodo necesita un camiño admitido pola pasarela VPN prevista ou un dispositivo aprobado, e o lado do rexistro necesita unha ruta de retorno á subrede do nodo.
Le o fallo antes de escoller a solución
Comeza polos eventos do pod e o nodo onde caeu, cos teus nomes reais: kubectl describe pod app-example -n team-example e kubectl get pod app-example -n team-example -o wide. O texto do evento separa un nome de host sen resolver dun timeout, un rexeitamento de certificado dunha imaxe ausente e un fallo de autorización de todos eles. Eses catro teñen catro donos distintos.
A autenticación é a panca máis sobrevalorada. imagePullSecret dálle ao runtime as credenciais do rexistro; non instala unha ruta, non cambia o resolutor do nodo nin fai válido un certificado non fiable. Se o evento di que a descarga non estaba autorizada, mira o alcance da identidade. Se di que a conexión expirou, as credenciais son irrelevantes.
A documentación de imaxes de Kubernetes é a referencia sobre o comportamento de descarga e as credenciais de rexistros privados, e paga a pena lela unha vez antes de cambiar a rede, porque fai explícita a fronteira entre autenticación e transporte.
Constrúe o camiño por baixo do pod
Traballa nesta orde, porque cada paso carece de sentido ata que se cumpra o anterior. Encamiña primeiro a rede do nodo: confirma que a subrede ten un camiño admitido á rede do rexistro, revisa as rutas efectivas no nodo, as regras de seguridade nos dous extremos e a ruta de retorno no lado do rexistro.
Despois resolve o nome desde o contexto do nodo. O resolutor do nodo non é a configuración DNS do pod, e o éxito dentro dun pod non é proba sobre o runtime do host. Usa DNS privado xestionado en lugar dunha entrada permanente en hosts; a entrada sobrevive ata que o nodo se substitúe e logo desaparece en silencio.
Logo demostra cada endpoint. Un rexistro pode dar ao cliente un servizo de autenticación separado e unha localización de blob separada. Chegar ao endpoint de manifesto non demostra case nada sobre as capas. Por último completa TLS e autorización: un certificado válido para o nome do rexistro e confiado mediante configuración de nodo admitida, máis unha identidade de descarga limitada a ler ese repositorio.
Verifícao nun nodo que non reparases a man
A proba que conta é unha descarga nova e unha baixada completa de todas as capas nun nodo apto, idealmente un creado por escalado ou substitución. Iso cobre todos os pools que poderían programar o workload, incluídos os que esqueciches. Unha reparación manual nun nodo non é un modelo de despregamento, e o próximo evento de autoscalado atopará o oco.
Recrear o clúster noutra VNet pode cambiar o camiño, pero é o último recurso e non o primeiro paso de diagnóstico. Compara a rede de nodos existente coa ruta privada necesaria e cos controls de rede de AKS admitidos antes de propoñer unha migración, e mantén a conectividade da aplicación tras o arranque como verificación aparte: o pod falando co seu backend é unha comprobación distinta da do nodo descargando a imaxe.