Solucionar problemas de Cloud NAT

Esta guía te ayuda a diagnosticar por qué tus cargas de trabajo (pods o máquinas virtuales) no pueden acceder a redes externas mediante Cloud NAT. Como desarrollador, interactúas principalmente con el recurso CloudNatGateway. El estado de este recurso es tu principal fuente de información para depurar.

Antes de empezar

Para solucionar problemas de configuración de Cloud NAT, debes tener lo siguiente:

  • Los roles de gestión de identidades y accesos necesarios. Pídele a tu administrador de gestión de identidades y accesos de proyectos que te asigne uno o ambos de los siguientes roles:
    • Visualizador de Cloud NAT (cloud-nat-viewer): este rol ofrece acceso de solo lectura a los recursos de Cloud NAT. Este rol te ayuda a empezar a diagnosticar el problema.
    • Desarrollador de Cloud NAT (cloud-nat-developer): este rol proporciona los permisos necesarios para que los operadores de aplicaciones creen, lean, actualicen y eliminen objetos de Cloud NAT en los proyectos que se les hayan asignado. Este rol te permite realizar muchas de las correcciones que se describen en esta página.
    • Es posible que se necesiten roles adicionales para algunas medidas de diagnóstico y correcciones específicas.

Diagnóstico inicial

Antes de analizar los códigos de error, asegúrate de que los recursos básicos estén presentes y accesibles.

Comando:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

Haz los cambios siguientes:

  • GATEWAY_NAME: nombre del recurso CloudNatGateway.
  • PROJECT_NAMESPACE: espacio de nombres de tu proyecto.

Comprueba las condiciones de estado: una pasarela en buen estado debe tener todas las condiciones siguientes definidas como True:

  • Ready: estado de salud global.
  • SubnetsReady: la configuración del grupo de IPs es válida.
  • PerimeterConfigurationReady: la infraestructura de red ascendente está configurada.
  • EgressRoutesReady: las políticas de enrutamiento de tus pods están activas.

Si alguna de estas condiciones es False, comprueba los campos reason y message en la salida de estado y consulta las tablas de las secciones siguientes.

Referencia y resolución de códigos de error

Los códigos de error que devuelve kubectl get cloudnatgateway se dividen en tres categorías principales.

Errores de subred (SubnetsReady es False)

Esta condición indica problemas con el grupo de direcciones IP asignado a la pasarela.

Código de error Qué significa Pasos de resolución
CloudNATSelectorFieldOverlapsCode Conflicto de configuración. El valor de workloadSelector de esta pasarela coincide con las mismas cargas de trabajo que otra pasarela de tu proyecto. El tráfico no se puede enrutar de forma determinista.
  1. Lista todas las pasarelas de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el valor de workloadSelector de esta pasarela con el de otras.
  3. Modifica las etiquetas para que ningún pod ni máquina virtual se seleccione en más de una pasarela.
CloudNATSubnetRefsFieldInvalidCode

Subred no válida. La subred especificada en subnetRefs no se puede usar. Motivos habituales:

  • La subred no existe.
  • La subred no está en estado Ready.
  • La subred no es de tipo Leaf.
  1. Verifica que la subred exista: kubectl get subnet <SUBNET_NAME>
  2. Comprueba que el estado de la subred sea Ready.
  3. Asegúrate de que el type de la subred sea Leaf (Cloud NAT no puede usar subredes raíz ni de bucle invertido).
CloudNATSubnetAlreadyInUseCode Conflicto de subred. La subred que has solicitado ya es "propiedad" de otra pasarela de Cloud NAT. Una subred solo se puede asociar a una pasarela a la vez.
  1. Elige otra subred para esta pasarela.
  2. O bien, quita primero la subred de la otra pasarela.
UNETAPIServerErrorCode Error del sistema. El controlador no puede comunicarse con el servidor de la API para validar las subredes. Acción: es probable que se trate de un problema temporal de la plataforma. Si persiste, ponte en contacto con tu administrador de la plataforma.

Errores de configuración del perímetro (PerimeterConfigurationReady es False)

Esta condición refleja el estado de las pasarelas de perímetro.

Código de error Qué significa Pasos de resolución
NET-E0305 Conflicto de configuración. (Igual que el atributo anterior). Los selectores superpuestos impiden que el sistema calcule el grupo de enrutamiento correcto.
  1. Lista todas las pasarelas de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el valor de workloadSelector de esta pasarela con el de otras.
  3. Modifica las etiquetas para que ningún pod ni máquina virtual se seleccione en más de una pasarela.
NET-E0301 Agotamiento de recursos o fallo de nodo. El sistema ha creado la configuración, pero no ha podido asignar tus IPs de salida a un nodo físico en buen estado. Normalmente, esto significa que la subred se ha quedado sin IPs o que los nodos de la pasarela no funcionan.
  1. Comprueba el uso de la [subred](/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/subnets-overview). ¿Está llena?
  2. Si la subred tiene IPs libres y está en estado Ready, esto indica un fallo de infraestructura en el lado de la plataforma (por ejemplo, no hay nodos de pasarela en buen estado disponibles). Acción: ponte en contacto con el administrador de la plataforma.
NET-E0001 Error del sistema. Error de comunicación del controlador. Acción: ponte en contacto con el administrador de la plataforma.

Errores de ruta de salida (EgressRoutesReady es False)

Esta condición refleja el estado de las políticas de enrutamiento dentro del clúster.

Código de error Qué significa Pasos de resolución
NET-E0305 Conflicto de configuración. (Igual que el atributo anterior).
  1. Lista todas las pasarelas de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el valor de workloadSelector de esta pasarela con el de otras.
  3. Modifica las etiquetas para que ningún pod ni máquina virtual se seleccione en más de una pasarela.
NET-E0304 Error de programación. El sistema no ha podido programar las reglas de enrutamiento (BPF) para las IPs de tu pasarela específica.

Acción: se trata de un error de programación interno o de una incoherencia de estado.

  1. Intenta hacer una actualización trivial en la pasarela (por ejemplo, editar una etiqueta) para activar una conciliación.
  2. Si persiste, ponte en contacto con el administrador de la plataforma.

Otros problemas habituales

Si el estado de la pasarela es Ready: True, pero el tráfico sigue fallando, comprueba estas configuraciones incorrectas habituales:

Falta un permiso a nivel de proyecto

Tu proyecto debe estar autorizado explícitamente para el tráfico de salida.

  • Comprobación: ¿tiene tu recurso de proyecto la etiqueta networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true"?
  • Solución: pide a tu administrador de proyectos que aplique esta etiqueta.

Falta una anotación de máquina virtual (solo máquinas virtuales)

Las máquinas virtuales omiten la ruta de salida de pods estándar y necesitan instrucciones explícitas para usar Cloud NAT.

  • Comprobación: ¿tiene el objeto VirtualMachineExternalAccess (VMEA) de tu máquina virtual la anotación egress.networking.gke.io/use-cloud-nat: "true"?
  • Solución: añade la anotación al objeto VMEA.

Salida de nodos de clústeres estándar

Si ejecutas un clúster estándar, los nodos deben tener permiso para la salida.

  • Comprobación: ¿tiene el objeto Cluster la etiqueta cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true"?
  • Solución: pide a tu administrador de la plataforma que etiquete el objeto `Cluster`.

Colisión entre la NAT de salida predeterminada y Cloud NAT

Se produce un error de configuración habitual cuando una carga de trabajo está configurada para usar el mecanismo de NAT de salida predeterminado heredado y, al mismo tiempo, se selecciona mediante una pasarela de Cloud NAT. Esta combinación provoca una colisión en la que el plano de datos recibe instrucciones de enrutamiento contradictorias, lo que provoca la pérdida de paquetes o un comportamiento de enrutamiento no determinista.

Diagnosticar colisiones de pods

En el caso de los pods, la NAT de salida predeterminada suele habilitarse añadiendo una etiqueta específica. Un pod no puede tener esta etiqueta si también está orientado a una pasarela de Cloud NAT.

  1. Identifica el pod de destino: obtén las etiquetas del pod que tiene problemas de conectividad.

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

  2. Comprueba si hay etiquetas en conflicto:

    • Selección de Cloud NAT: ¿coinciden las etiquetas del pod con el valor de workloadSelector de alguna CloudNatGateway del espacio de nombres?
    • Etiqueta de salida predeterminada: ¿tiene el pod la etiqueta egress.networking.gke.io/enabled: "true"?

    Condición: si AMBAS son verdaderas, hay una colisión.

  3. Resolución: quita la etiqueta de salida predeterminada heredada del pod (o de su despliegue o StatefulSet principal) para que Cloud NAT pueda tomar el control exclusivo.

Diagnosticar colisiones de máquinas virtuales

En el caso de las máquinas virtuales, el mecanismo es diferente. Las máquinas virtuales con objetos VirtualMachineExternalAccess (VMEA) suelen configurarse para el acceso predeterminado. Para usar Cloud NAT, deben habilitarlo explícitamente añadiendo una anotación para inhabilitar la ruta predeterminada y habilitar la ruta de Cloud NAT.

  1. Identifica el VMEA: busca el objeto VirtualMachineExternalAccess asociado a la máquina virtual.

    kubectl get vmea -n <NAMESPACE>

  2. Comprueba si falta una anotación:

    • Selección de Cloud NAT: ¿coinciden las etiquetas de la máquina virtual con una CloudNatGateway?
    • Anotación de habilitación: comprueba si el VMEA tiene la anotación egress.networking.gke.io/use-cloud-nat: "true".

    Condición: si la máquina virtual coincide con una pasarela, pero NO TIENE esta anotación, el tráfico entrará en conflicto con el sistema de salida predeterminado.

  3. Resolución: añade la anotación al objeto VMEA.

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