Soluciona problemas de Cloud NAT

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

Antes de comenzar

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

  • Los roles de identidad y acceso necesarios. Pídele al administrador de IAM del proyecto que te otorgue 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 permite comenzar 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 borren (CRUD) objetos de Cloud NAT dentro de sus proyectos asignados. 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 profundizar en los códigos de error, asegúrate de que los recursos básicos estén presentes y sean accesibles.

Comando:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

Reemplaza lo siguiente:

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

Verifica las condiciones de estado: Una puerta de enlace en buen estado debe tener todas las siguientes condiciones establecidas en True:

  • Ready: Es el estado de salud global.
  • SubnetsReady: La configuración del grupo de IP es válida.
  • PerimeterConfigurationReady: Se configuró la infraestructura de red ascendente.
  • EgressRoutesReady: Las políticas de enrutamiento de tus Pods están activas.

Si alguno de estos es False, verifica los campos reason y message en el resultado del estado y consulta las tablas en las siguientes secciones.

Referencia y corrección de códigos de error

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

Errores de subred (SubnetsReady es falso)

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

Código de error Qué significa Pasos para soluciones
CloudNATSelectorFieldOverlapsCode Conflicto de configuración. El workloadSelector de esta puerta de enlace coincide con las mismas cargas de trabajo que otra puerta de enlace de tu proyecto. El tráfico no se puede enrutar de forma determinística.
  1. Enumera todas las puertas de enlace de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el workloadSelector de esta puerta de enlace con otras.
  3. Modifica las etiquetas para que ninguna puerta de enlace seleccione más de un Pod o VM.
CloudNATSubnetRefsFieldInvalidCode

La subred no es válida. No se puede usar la subred especificada en subnetRefs. Estos son algunos de los motivos comunes:

  • La subred no existe.
  • La subred no está en el estado Ready.
  • La subred no es del tipo Leaf.
  1. Verifica que exista la subred: kubectl get subnet <SUBNET_NAME>
  2. Verifica que el estado de la subred sea Ready.
  3. Asegúrate de que la subred type sea Leaf (Cloud NAT no puede usar subredes raíz ni de bucle invertido).
CloudNATSubnetAlreadyInUseCode Conflicto de subred. La subred que solicitaste ya "pertenece" a otra puerta de enlace de Cloud NAT. Una subred solo se puede conectar a una puerta de enlace a la vez.
  1. Elige otra subred para esta puerta de enlace.
  2. O bien, quita primero la subred de la otra puerta de enlace.
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 el problema persiste, comunícate con el administrador de la plataforma.

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

Esta condición refleja el estado de las puertas de enlace perimetrales.

Código de error Qué significa Pasos para soluciones
NET-E0305 Conflicto de configuración. (Igual que en el caso anterior). Los selectores superpuestos impiden que el sistema calcule el grupo de enrutamiento correcto.
  1. Enumera todas las puertas de enlace de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el workloadSelector de esta puerta de enlace con otras.
  3. Modifica las etiquetas para que ninguna puerta de enlace seleccione más de un Pod o VM.
NET-E0301 Agotamiento de recursos o falla de nodo. El sistema creó la configuración, pero no pudo asignar tus IPs de salida a un nodo físico en buen estado. Por lo general, esto significa que la subred se quedó sin IPs o que los nodos de puerta de enlace están inactivos.
  1. Verifica el uso de tu [subred](/distributed-cloud/hosted/docs/1.16/gdcag/platform/pa-user/subnets-overview). ¿Está lleno?
  2. Si la subred tiene IPs libres y está en estado Ready, esto indica una falla de infraestructura del lado de la plataforma (p.ej., no hay nodos de puerta de enlace en buen estado disponibles). Acción: Comunícate con el administrador de la plataforma.
NET-E0001 Error del sistema. Falla de comunicación del controlador. Acción: Comunícate con el administrador de la plataforma.

Errores de ruta de salida (EgressRoutesReady es falso)

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

Código de error Qué significa Pasos para soluciones
NET-E0305 Conflicto de configuración. (Igual que en el caso anterior).
  1. Enumera todas las puertas de enlace de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el workloadSelector de esta puerta de enlace con otras.
  3. Modifica las etiquetas para que ninguna puerta de enlace seleccione más de un Pod o VM.
NET-E0304 Falla de programación. El sistema no pudo programar las reglas de enrutamiento (BPF) para tus IPs de puerta de enlace específicas.

Acción: Se trata de un error de programación interno o una inconsistencia de estado.

  1. Intenta realizar una actualización trivial en la puerta de enlace (p.ej., editar una etiqueta) para activar una conciliación.
  2. Si el problema persiste, comunícate con el administrador de la plataforma.

Otros problemas comunes

Si el estado de la puerta de enlace es Ready: True, pero el tráfico sigue fallando, verifica estos parámetros de configuración incorrectos comunes:

Falta el permiso a nivel del proyecto

Tu proyecto debe estar autorizado de forma explícita para enviar tráfico de salida.

  • Verifica: ¿Tu recurso de proyecto tiene la etiqueta networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true"?
  • Solución: Pídele al administrador del proyecto que aplique esta etiqueta.

Falta la anotación de la VM (solo para máquinas virtuales)

Las VMs omiten la ruta de salida estándar del Pod y necesitan instrucciones explícitas para usar Cloud NAT.

  • Verifica: ¿El objeto VirtualMachineExternalAccess (VMEA) de tu VM tiene la anotación egress.networking.gke.io/use-cloud-nat: "true"?
  • Solución: Agrega la anotación al objeto VMEA.

Salida de nodos de clústeres de Standard

Si ejecutas un clúster de Standard, los nodos necesitan permiso para salir.

  • Verifica: ¿El objeto Cluster tiene la etiqueta cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true"?
  • Solución: Pídele al administrador de la plataforma que etiquete el objeto Cluster.

Conflicto entre la NAT de salida predeterminada y Cloud NAT

Se produce un error de configuración común cuando una carga de trabajo se configura para usar el mecanismo de NAT de salida predeterminado heredado y, al mismo tiempo, la selecciona una puerta de enlace de Cloud NAT. Esta combinación genera una colisión en la que el plano de datos recibe instrucciones de enrutamiento en conflicto, lo que genera pérdida de paquetes o un comportamiento de enrutamiento no determinista.

Diagnostica colisiones de Pods

Para los Pods, la NAT de salida predeterminada suele habilitarse agregando una etiqueta específica. Un Pod no puede tener esta etiqueta y, al mismo tiempo, ser el destino de una puerta de enlace 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. Verifica si hay etiquetas en conflicto:

    • Selección de Cloud NAT: ¿Las etiquetas del Pod coinciden con el workloadSelector de algún CloudNatGateway en el espacio de nombres?
    • Etiqueta de salida predeterminada: ¿El Pod tiene la etiqueta egress.networking.gke.io/enabled: "true"?

    Condición: Si AMBAS son verdaderas, tienes una colisión.

  3. Resolución: Quita la etiqueta de salida predeterminada heredada del Pod (o su Deployment/StatefulSet superior) para permitir que Cloud NAT tome el control exclusivo.

Diagnostica colisiones de VMs

En el caso de las máquinas virtuales, el mecanismo es diferente. Las VMs con objetos VirtualMachineExternalAccess (VMEA) suelen configurarse para el acceso predeterminado. Para usar Cloud NAT, deben habilitarlo de forma explícita agregando una anotación que inhabilite la ruta predeterminada y habilite la ruta de Cloud NAT.

  1. Identifica el VMEA: Busca el objeto VirtualMachineExternalAccess asociado a la VM.

    kubectl get vmea -n <NAMESPACE>
    
  2. Verifica si falta alguna anotación:

    • Selección de Cloud NAT: ¿Las etiquetas de la VM coinciden con una CloudNatGateway?
    • Anotación de habilitación: Verifica el VMEA para la anotación egress.networking.gke.io/use-cloud-nat: "true".

    Condición: Si la VM coincide con una puerta de enlace, pero NO TIENE esta anotación, el tráfico colisionará con el sistema de salida predeterminado.

  3. Resolución: Agrega la anotación al objeto VMEA.

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