Resolver problemas do Cloud NAT

Este guia ajuda a diagnosticar por que as cargas de trabalho (pods ou VMs) não conseguem acessar redes externas usando o Cloud NAT. Como desenvolvedor, você interage principalmente com o recurso CloudNatGateway. O status desse recurso é sua principal fonte de verdade para depuração.

Antes de começar

Para resolver problemas de uma configuração do Cloud NAT, é necessário ter o seguinte:

  • Os papéis de identidade e acesso necessários. Peça ao administrador do IAM do projeto para conceder a você um ou ambos os papéis a seguir:
    • Leitor do Cloud NAT (cloud-nat-viewer): esse papel oferece acesso somente leitura aos recursos do Cloud NAT. Esse papel ajuda você a começar a diagnosticar o problema.
    • Desenvolvedor do Cloud NAT (cloud-nat-developer): esse papel fornece as permissões necessárias para que os operadores de aplicativos criem, leiam, atualizem e excluam (CRUD) objetos do Cloud NAT nos projetos atribuídos. Esse papel permite que você realize muitas das correções descritas nesta página.
    • Talvez sejam necessários outros papéis para algumas medidas e correções de diagnóstico específicas.

Diagnóstico inicial

Antes de analisar os códigos do erro, verifique se os recursos básicos estão presentes e acessíveis.

Comando:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

Substitua:

  • GATEWAY_NAME: o nome do recurso CloudNatGateway.
  • PROJECT_NAMESPACE: o namespace do projeto.

Verifique as condições de status:um gateway íntegro precisa ter todas as seguintes condições definidas como True:

  • Ready: status de integridade global.
  • SubnetsReady: a configuração do pool de IPs é válida.
  • PerimeterConfigurationReady: a infraestrutura de rede upstream está configurada.
  • EgressRoutesReady: as políticas de roteamento dos pods estão ativas.

Se algum deles for False, verifique os campos reason e message na saída de status e consulte as tabelas nas seções a seguir.

Referência e correção de códigos de erro

Os códigos de erro retornados por kubectl get cloudnatgateway se dividem em três categorias principais.

Erros de sub-rede (SubnetsReady é falso)

Essa condição indica problemas com o pool de endereços IP atribuído ao gateway.

Código do erro O que isso significa Etapas de correção
CloudNATSelectorFieldOverlapsCode Conflito de configuração. O workloadSelector deste gateway corresponde às mesmas cargas de trabalho de outro gateway no seu projeto. Não é possível rotear o tráfego de forma determinística.
  1. Liste todos os gateways do Cloud NAT no seu projeto: kubectl get cloudnatgateway
  2. Compare o workloadSelector deste gateway com outros.
  3. Modifique os rótulos para que nenhum pod/VM seja selecionado por mais de um gateway.
CloudNATSubnetRefsFieldInvalidCode

Sub-rede inválida. A sub-rede especificada em subnetRefs não pode ser usada. Motivos comuns:

  • A sub-rede não existe.
  • A sub-rede não está no estado Ready.
  • A sub-rede não é do tipo Leaf.
  1. Verifique se a sub-rede existe: kubectl get subnet <SUBNET_NAME>
  2. Verifique se o status da sub-rede é Ready.
  3. Verifique se a sub-rede type é Leaf (o Cloud NAT não pode usar sub-redes raiz ou de loopback).
CloudNATSubnetAlreadyInUseCode Conflito de sub-rede. A sub-rede solicitada já é de "propriedade" de outro gateway do Cloud NAT. Uma sub-rede só pode ser anexada a um gateway por vez.
  1. Escolha outra sub-rede para esse gateway.
  2. Ou remova a sub-rede do outro gateway primeiro.
UNETAPIServerErrorCode Erro do sistema. O controlador não consegue se comunicar com o servidor de API para validar sub-redes. Ação:é provável que seja um problema temporário da plataforma. Se o problema persistir, entre em contato com o administrador da plataforma.

Erros de configuração do perímetro (PerimeterConfigurationReady é falso)

Essa condição reflete o status dos gateways de perímetro.

Código do erro O que isso significa Etapas de correção
NET-E0305 Conflito de configuração. (Igual ao anterior). Os seletores sobrepostos impedem que o sistema calcule o grupo de roteamento correto.
  1. Liste todos os gateways do Cloud NAT no seu projeto: kubectl get cloudnatgateway
  2. Compare o workloadSelector deste gateway com outros.
  3. Modifique os rótulos para que nenhum pod/VM seja selecionado por mais de um gateway.
NET-E0301 Esgotamento de recursos / falha no nó. O sistema criou a configuração, mas não conseguiu atribuir seus IPs de saída a um nó físico íntegro. Isso geralmente significa que a sub-rede está sem IPs ou que os nós do gateway estão inativos.
  1. Verifique o uso da [sub-rede](/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/subnets-overview). Há informações sobre conteúdo cheio?
  2. Se a sub-rede tiver IPs livres e estiver Ready, isso indica uma falha na infraestrutura da plataforma (por exemplo, nenhum nó de gateway íntegro disponível). Ação: entre em contato com o administrador da plataforma.
NET-E0001 Erro do sistema. Falha na comunicação do controlador. Ação:entre em contato com o administrador da plataforma.

Erros de rota de saída (EgressRoutesReady é falso)

Essa condição reflete o status das políticas de roteamento dentro do cluster.

Código do erro O que isso significa Etapas de correção
NET-E0305 Conflito de configuração. (Igual ao anterior).
  1. Liste todos os gateways do Cloud NAT no seu projeto: kubectl get cloudnatgateway
  2. Compare o workloadSelector deste gateway com outros.
  3. Modifique os rótulos para que nenhum pod/VM seja selecionado por mais de um gateway.
NET-E0304 Falha de programação. O sistema não conseguiu programar as regras de rota (BPF) para os IPs de gateway específicos.

Ação:esse é um erro de programação interna ou inconsistência de estado.

  1. Tente fazer uma atualização simples no gateway (por exemplo, editar um rótulo) para acionar uma reconciliação.
  2. Se o problema persistir, entre em contato com o administrador da plataforma.

Outros problemas comuns

Se o status do gateway for Ready: True, mas o tráfego ainda estiver falhando, verifique estas configurações incorretas comuns:

Permissão ausente para envolvidos no projeto

Seu projeto precisa ser explicitamente autorizado a enviar tráfego de saída.

  • Verifique:o recurso do projeto tem o rótulo networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true"?
  • Correção:peça ao administrador do projeto para aplicar esse rótulo.

Anotação de VM ausente (somente máquinas virtuais)

As VMs ignoram o caminho de saída padrão do pod e precisam de instruções explícitas para usar o Cloud NAT.

  • Verificação:o objeto VirtualMachineExternalAccess (VMEA) da VM tem a anotação egress.networking.gke.io/use-cloud-nat: "true"?
  • Correção:adicione a anotação ao objeto VMEA.

Saída de nó de cluster padrão

Se você estiver executando um cluster padrão, os próprios nós precisarão de permissão para saída.

  • Verificação:o objeto Cluster tem o rótulo cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true"?
  • Correção:peça ao administrador da plataforma para rotular o objeto Cluster.

Colisão entre NAT de saída padrão e Cloud NAT

Um erro de configuração comum ocorre quando uma carga de trabalho é configurada para usar o mecanismo legado de NAT de saída padrão e, ao mesmo tempo, é selecionada por um gateway do Cloud NAT. Essa combinação resulta em uma colisão em que o plano de dados recebe instruções de roteamento conflitantes, levando à perda de pacotes ou a um comportamento de roteamento não determinístico.

Diagnosticar colisões de pods

Para pods, a NAT de saída padrão geralmente é ativada adicionando um rótulo específico. Um pod não pode ter esse rótulo e, ao mesmo tempo, ser segmentado por um gateway do Cloud NAT.

  1. Identifique o pod de destino:consiga os rótulos do pod com problemas de conectividade.

    kubectl get pod <POD_NAME> -n <NAMESPACE> --show-labels

  2. Verifique se há rótulos conflitantes:

    • Seleção do Cloud NAT:os rótulos do pod correspondem ao workloadSelector de qualquer CloudNatGateway no namespace?
    • Rótulo de saída padrão:o pod tem o rótulo egress.networking.gke.io/enabled: "true"?

    Condição:se AMBOS forem verdadeiros, há uma colisão.

  3. Resolução:remova o rótulo de saída padrão legado do pod (ou da implantação/StatefulSet pai) para permitir que o Cloud NAT assuma o controle exclusivo.

Diagnosticar colisões de VM

Para máquinas virtuais, o mecanismo é diferente. As VMs com objetos VirtualMachineExternalAccess (VMEA) geralmente são configuradas para acesso padrão. Para usar o Cloud NAT, eles precisam ativar explicitamente adicionando uma anotação para desativar o caminho padrão e ativar o caminho do Cloud NAT.

  1. Identifique o VMEA:encontre o objeto VirtualMachineExternalAccess associado à VM.

    kubectl get vmea -n <NAMESPACE>

  2. Verificar se há anotações ausentes:

    • Seleção do Cloud NAT:os rótulos da VM correspondem a um CloudNatGateway?
    • Anotação de ativação:verifique se o VMEA tem a anotação egress.networking.gke.io/use-cloud-nat: "true".

    Condição:se a VM corresponder a um gateway, mas NÃO TIVER essa anotação, o tráfego vai colidir com o sistema de saída padrão.

  3. Resolução:adicione a anotação ao objeto VMEA.

    kubectl annotate vmea <VMEA_NAME> -n <NAMESPACE> egress.networking.gke.io/use-cloud-nat="true"