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 roles siguientes:
- 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.
- Visualizador de Cloud NAT (
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 recursoCloudNatGateway.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 de 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. |
|
CloudNATSubnetRefsFieldInvalidCode |
La subred no es válida. No se puede usar la subred especificada en
|
|
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. |
|
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. |
|
NET-E0301 |
Agotamiento de recursos o falla del 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. |
|
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). |
|
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.
|
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 permitir la salida de tráfico.
- 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ónegress.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
Clustertiene la etiquetacluster.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 determinístico.
Diagnostica colisiones de Pods
En el caso de 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.
Identifica el Pod de destino: Obtén las etiquetas del Pod que tiene problemas de conectividad.
kubectl get pod <POD_NAME> -n <NAMESPACE> --show-labelsVerifica si hay etiquetas en conflicto:
- Selección de Cloud NAT: ¿Las etiquetas del Pod coinciden con el
workloadSelectorde cualquierCloudNatGatewayen 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.
- Selección de Cloud NAT: ¿Las etiquetas del Pod coinciden con el
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
Para 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.
Identifica el VMEA: Busca el objeto
VirtualMachineExternalAccessasociado a la VM.kubectl get vmea -n <NAMESPACE>Verifica si falta alguna anotación:
- Selección de Cloud NAT: ¿Las etiquetas de la VM coinciden con un
CloudNatGateway? - Anotación de habilitación: Consulta el VMEA para ver 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.
- Selección de Cloud NAT: ¿Las etiquetas de la VM coinciden con un
Resolución: Agrega la anotación al objeto VMEA.
kubectl annotate vmea <VMEA_NAME> -n <NAMESPACE> egress.networking.gke.io/use-cloud-nat="true"