Solucionar 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 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 identidad y acceso necesarios. Pide al administrador de gestión de identidades y accesos de tu proyecto que te conceda uno o ambos de los siguientes roles:
    • Lector de Cloud NAT (cloud-nat-viewer): este rol proporciona 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 puedan crear, leer, actualizar y eliminar objetos de Cloud NAT en los proyectos que tengan asignados. Este rol te permite aplicar 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 sean accesibles.

Comando:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

Haz los cambios siguientes:

  • GATEWAY_NAME: el nombre del recurso CloudNatGateway.
  • PROJECT_NAMESPACE: el 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 general.
  • 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 alguno de estos campos es False, consulta los campos reason y message en el resultado del estado y consulta las tablas de las secciones siguientes.

Referencia y solución de códigos de error

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

Errores de subred (SubnetsReady es False)

Esta condición indica que hay 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 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 de todas las pasarelas de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el workloadSelector de esta pasarela con otros.
  3. Modifica las etiquetas para que ninguna VM o Pod esté seleccionado por 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 el estado Ready.
  • La subred no es de tipo Leaf.
  1. Verifica que la subred existe: kubectl get subnet <SUBNET_NAME>
  2. Comprueba que el estado de la subred sea Ready.
  3. Asegúrate de que la subred type no sea Leaf (Cloud NAT no puede usar subredes raíz ni de bucle de retorno).
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. También puedes quitar la subred de la otra pasarela primero.
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 perimetrales.

Código de error Qué significa Pasos de resolución
NET-E0305 Conflicto de configuración. (Igual que arriba). Los selectores superpuestos impiden que el sistema calcule el grupo de enrutamiento correcto.
  1. Lista de todas las pasarelas de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el workloadSelector de esta pasarela con otros.
  3. Modifica las etiquetas para que ninguna VM o Pod esté seleccionado por 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 correcto. Normalmente, esto significa que la subred se ha quedado sin IPs o que los nodos de la pasarela no funcionan.
  1. Consulta tu uso de [subredes](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/subnets-overview). ¿Está lleno?
  2. Si la subred tiene IPs libres y es Ready, esto indica un fallo en la infraestructura del lado de la plataforma (por ejemplo, no hay nodos de puerta de enlace en buen estado disponibles). Acción: póngase en contacto con el administrador de la plataforma.
NET-E0001 Error del sistema. Error de comunicación del mando. Acción: póngase 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 arriba).
  1. Lista de todas las pasarelas de Cloud NAT de tu proyecto: kubectl get cloudnatgateway
  2. Compara el workloadSelector de esta pasarela con otros.
  3. Modifica las etiquetas para que ninguna VM o Pod esté seleccionado por más de una pasarela.
NET-E0304 No se ha podido programar. 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. Prueba a hacer un cambio trivial en la pasarela (por ejemplo, editar una etiqueta) para activar una conciliación.
  2. Si persiste, póngase 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, compruebe estas configuraciones incorrectas habituales:

Falta un permiso a nivel de proyecto

Tu proyecto debe tener autorización explícita para enviar tráfico.

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

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

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

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

Salida de nodos de clúster estándar

Si tienes un clúster estándar, los propios nodos necesitan permiso para salir.

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

Colisión entre NAT de salida predeterminado y Cloud NAT

Un error de configuración habitual se produce cuando una carga de trabajo está configurada para usar el mecanismo de NAT de salida predeterminado antiguo 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 se suele habilitar añadiendo una etiqueta específica. Un pod no puede tener esta etiqueta y, al mismo tiempo, ser el destino de una pasarela 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. Comprobar si hay etiquetas conflictivas:

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

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

  3. Solución: Quita la etiqueta de salida predeterminada antigua del pod (o de su Deployment o StatefulSet principal) para permitir que Cloud NAT tome el control exclusivo.

Diagnosticar 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 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 VM.

    kubectl get vmea -n <NAMESPACE>

  2. Comprobar si faltan anotaciones:

    • Selección de Cloud NAT: ¿las etiquetas de la VM coinciden con un CloudNatGateway?
    • Anotación de consentimiento expreso: consulta la VMEA de 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. Solución: añade la anotación al objeto VMEA.

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