O AKS não consegue puxar a imagem de um registry privado atrás da VPN
O kubelet puxa pela rede do node, não pela VPN do pod. Decida pelas rotas do node, pelo DNS do node, por cada endpoint que o pull toca, e depois por TLS e identidade.
Seu notebook puxa a imagem sem problema, mas o pod fica em ImagePullBackOff e alguém sugere rodar o cliente VPN corporativo como sidecar. Isso não ajuda, porque o pull ocorre antes de o contêiner existir: o kubelet pede ao container runtime no node que busque a imagem, e o runtime usa o namespace de rede do node.
A ordem das operações decide a camada
Primeiro a resolução do nome, depois conexão, autenticação, download das camadas e só então o contêiner inicia. Tudo o que o pod faz com VPN acontece depois disso, então um túnel funcionando no cluster não é prova sobre o pull.
Por isso uma imagem em cache é uma mentira tão convincente: um node que puxou a imagem semanas atrás continua servindo, o deployment parece saudável, e a falha só aparece quando o escalonador coloca uma réplica em um node mais novo. scale-up ou troca de node é o gatilho, não a causa.
Três condições decidem a correção
A acessibilidade depende de roteamento, resolução de nomes e do conjunto de endpoints. Se a sub-rede do node não roteia para a rede do registry, nenhuma credencial ajuda. Se o nome não resolve pelo caminho de DNS do node, a conexão não começa. Se só o manifest responde e o blob não, o pull falha no meio.
| 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 |
Só o peering de VNet não dá todas as combinações de gateway transit, e uma rota em um sentido não é uma rota que funciona. O node precisa de um caminho suportado pelo gateway VPN previsto, e o lado do registry de uma rota de volta à sub-rede do node.
Leia a falha antes de escolher a correção
Comece pelos eventos do pod e pelo node onde ele caiu, com seus 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 um hostname não resolvido de um timeout, uma rejeição de certificado de uma imagem ausente e uma falha de autorização de tudo isso.
A autenticação é a alavanca mais superestimada. imagePullSecret entrega ao runtime as credenciais do registry; não instala rota, não muda o resolver do node e não torna válido um certificado não confiável. Se o evento diz que o pull não foi autorizado, olhe o escopo da identidade; se diz que a conexão expirou, as credenciais são irrelevantes.
A documentação de imagens do Kubernetes é a referência para o comportamento de pull e credenciais de registries privados, e vale uma leitura antes de mudar a rede, porque deixa explícita a fronteira entre autenticação e transporte.
Construa o caminho abaixo do pod
Trabalhe nesta ordem. Primeiro roteie a rede do node: confirme que a sub-rede tem um caminho suportado até a rede do registry, verifique as rotas efetivas no node, as regras de segurança nas duas pontas e a rota de retorno no lado do registry.
Depois resolva o nome a partir do contexto do node. O resolver do node não é a configuração de DNS do pod, e o sucesso dentro do pod não é prova sobre o runtime do host. Use DNS privado gerenciado em vez de uma entrada permanente em hosts; a entrada sobrevive até a troca do node e depois desaparece em silêncio.
Depois prove cada endpoint. Um registry pode dar ao cliente um serviço de autenticação separado e um armazenamento de blob separado. Alcançar o manifest quase não prova nada sobre as camadas. Por fim, conclua TLS e autorização: um certificado válido para o nome do registry e confiável por configuração de node suportada, além de uma identidade de pull limitada a ler esse repositório.
Verifique em um node que você não corrigiu à mão
O teste que conta é um pull novo e o download completo de todas as camadas em um node elegível, de preferência criado por escala ou substituição. Isso cobre todos os pools que poderiam agendar o workload, inclusive os esquecidos. Uma correção manual em um node não é modelo de implantação, e o próximo evento de autoscale vai encontrar a lacuna.
Recriar o cluster em outra VNet pode mudar o caminho, mas é o último recurso e não o primeiro passo de diagnóstico. Compare a rede de nodes existente com a rota privada necessária e com os controles de rede do AKS suportados antes de propor uma migração, e mantenha a conectividade da aplicação após o start como verificação separada: o pod falando com o backend é uma checagem diferente do node baixando a imagem.