**Ayude a mejorar esta página** 

Para contribuir a esta guía del usuario, elija el enlace **Edit this page on GitHub** que se encuentra en el panel derecho de cada página.

# Solución de problemas de puerta de enlace de Nodos híbridos de Amazon EKS
<a name="hybrid-nodes-gateway-troubleshooting"></a>

En esta página se proporcionan directrices para diagnosticar y resolver los problemas de la puerta de enlace de Nodos híbridos de Amazon EKS. En cada sección se describe un síntoma, las posibles causas, los pasos de diagnóstico y las soluciones. Para obtener información operativa, consulte [Operaciones de puerta de enlace de Nodos híbridos de Amazon EKS](hybrid-nodes-gateway-operations.md).

## No se puede acceder a los pods de los nodos híbridos desde la VPC
<a name="hybrid-nodes-gateway-ts-unreachable"></a>

No se puede obtener acceso a los pods que se ejecutan en nodos híbridos desde los recursos de la VPC, tales como las instancias de EC2, los equilibradores de carga o el plano de control de Kubernetes.

 **Causas posibles:** 
+ Faltan entradas de la tabla de enrutamiento de la VPC o apuntan a una ENI incorrecta.
+ El pod líder de la puerta de enlace no se está ejecutando o no ha completado la configuración.
+ El VTEP de Cilium no está activado ni configurado en los nodos híbridos.
+ La comprobación de origen y destino está activada en la instancia de EC2 de la puerta de enlace.

 **Pasos de diagnóstico:** 

1.  **Compruebe las entradas de la tabla de enrutamiento de la VPC.** Compruebe que existan rutas para los CIDR del pod híbrido y apunte al ENI principal de la instancia de puerta de enlace activa:

   ```
   aws ec2 describe-route-tables \
     --route-table-ids {{ROUTE_TABLE_ID}} \
     --query "RouteTables[].Routes[?DestinationCidrBlock=='POD_CIDR']"
   ```

   Si faltan rutas, compruebe los registros de la puerta de enlace para ver si hay errores en la tabla de enrutamiento. Si las rutas apuntan a un ENI incorrecto, es posible que la conmutación por error no se haya completado correctamente.

1.  **Compruebe el estado del pod de puerta de enlace y la elección del líder.** Confirme que hay dos pods de puerta de enlace en funcionamiento y que uno tiene la concesión de líder:

   ```
   kubectl get pods -n eks-hybrid-nodes-gateway
   kubectl get lease -n eks-hybrid-nodes-gateway
   ```

   Si ningún pod tiene la concesión, consulte [Cuestiones de elección de líderes](#hybrid-nodes-gateway-ts-leader).

1.  **Compruebe la configuración del VTEP de Cilium en los nodos híbridos.** Compruebe que el recurso `CiliumVTEPConfig` existe y contiene la IP del nodo del líder:

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

   `spec.endpoints[0].tunnelEndpoint` debe coincidir con la dirección IP del nodo de puerta de enlace del líder. Si falta el recurso o tiene una IP obsoleta, es posible que la puerta de enlace no haya completado la configuración del líder.

1.  **Compruebe la comprobación de origen/destino.** Verifique que la comprobación de origen y destino esté desactivada en las instancias de EC2 de la puerta de enlace.

   ```
   aws ec2 describe-instance-attribute \
     --instance-id {{GATEWAY_INSTANCE_ID}} \
     --attribute sourceDestCheck
   ```

   Si `sourceDestCheck` es `true`, desactívelo. Consulte [Introducción a la puerta de enlace de nodos híbridos de EKS](hybrid-nodes-gateway-getting-started.md).

## Las llamadas de webhook a nodos híbridos fallan
<a name="hybrid-nodes-gateway-ts-webhooks"></a>

El servidor de API de Kubernetes no puede acceder a los puntos de enlace de los webhook que se ejecutan en nodos híbridos. Las solicitudes de admisión de webhook agotan el tiempo de espera o devuelven errores de conexión.

 **Causas posibles:** 
+ La puerta de enlace no enruta el tráfico desde el plano de control a los pods híbridos.
+ Falta el recurso `CiliumVTEPConfig` o tiene una IP de punto de conexión obsoleta.

 **Pasos de diagnóstico:** 

1.  **Compruebe que el plano de control pueda alcanzar la IP del nodo de puerta de enlace.** El plano de control envía el tráfico a la tabla de enrutamiento de la VPC, que lo reenvía al ENI de la puerta de enlace. Confirme que las entradas de la tabla de enrutamiento de la VPC sean correctas siguiendo los pasos que se indican en [No se puede acceder a los pods de los nodos híbridos desde la VPC](#hybrid-nodes-gateway-ts-unreachable).

1.  **Compruebe el recurso CiliumVTEPConfig.** Compruebe que el recurso existe y que `tunnelEndpoint` coincide con la IP del nodo líder actual:

   ```
   kubectl get ciliumvtepconfig hybrid-gateway -o yaml
   ```

   Si el punto de conexión del túnel está obsoleto (apunta a un líder anterior), es posible que la puerta de enlace no haya completado la secuencia de configuración del líder. Compruebe los registros de la puerta de enlace para ver si hay errores durante el upsert `CiliumVTEPConfig`.

## Error al actualizar la tabla de enrutamiento de la VPC
<a name="hybrid-nodes-gateway-ts-routes"></a>

Los registros de la puerta de enlace muestran errores relacionados con las operaciones de la tabla de enrutamiento de la VPC y las rutas de los CIDR de los pods híbridos no se crean ni actualizan.

 **Causas posibles:** 
+ El rol de IAM de la puerta de enlace no tiene los permisos de EC2 necesarios.
+ Los ID de la tabla de enrutamiento de la configuración son incorrectos o las tablas de enrutamiento no existen.
+ La puerta de enlace no puede llegar al punto de conexión de la API de EC2.

 **Pasos de diagnóstico:** 

1.  **Verifique los permisos de IAM.** La puerta de enlace requiere las siguientes acciones de IAM:
   +  `ec2:DescribeRouteTables` 
   +  `ec2:CreateRoute` 
   +  `ec2:ReplaceRoute` 
   +  `ec2:DescribeInstances` 

     Compruebe el rol de IAM asociado al perfil de instancia o a la configuración de Pod Identity del nodo de puerta de enlace.

1.  **Compruebe los ID de la tabla de enrutamiento en la configuración.** Compruebe que la variable de entorno `ROUTE_TABLE_IDS` contenga ID de tabla de enrutamiento válidos en la implementación de la puerta de enlace:

   ```
   kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].env}' | jq .
   ```

   Confirme que los ID de la tabla de enrutamiento existan en su VPC:

   ```
   aws ec2 describe-route-tables --route-table-ids {{ROUTE_TABLE_ID}}
   ```

1.  **Compruebe los registros de la puerta de enlace para ver si hay errores en la tabla de enrutamiento.** Busque los mensajes de error relacionados con las operaciones de la tabla de enrutamiento:

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}} | grep -i "route table"
   ```

   Entre los mensajes de error comunes se incluyen los siguientes:
   +  `Failed to verify route table access`: la puerta de enlace no puede describir la tabla de enrutamiento. Compruebe los permisos de IAM y los ID de la tabla de enrutamiento.
   +  `Failed to update route tables`: la puerta de enlace no puede crear ni reemplazar rutas. Compruebe los permisos de IAM.
   +  `failed to access route table`: es posible que el ID de la tabla de enrutamiento sea incorrecto o que falte `ec2:DescribeRouteTables` en el rol de IAM.

## Los pods de puerta de enlace no se pueden iniciar o están en mal estado
<a name="hybrid-nodes-gateway-ts-pods"></a>

Los pods de puerta de enlace están en estado `CrashLoopBackOff`, `Error` o `Pending`, o bien el punto de conexión de estado devuelve un error.

 **Causas posibles:** 
+ Compruebe que no se hayan configurado las variables de entorno obligatorias (`VPC_CIDR`, `POD_CIDRS`, `ROUTE_TABLE_IDS`).
+ El reenvío de IP no está activado en el nodo de puerta de enlace.
+ Las restricciones de antiafinidad o de etiqueta de nodo impiden la programación.

 **Pasos de diagnóstico:** 

1.  **Compruebe los registros del pod**. Consulte los registros del pod que ha fallado para identificar el error:

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

1.  **Compruebe las variables de entorno obligatorias.** La puerta de enlace requiere `NODE_IP`, `VPC_CIDR` y `POD_CIDRS`. Si falta alguno de estos valores, la puerta de enlace se cierra inmediatamente. Compruebe las especificaciones del pod:

   ```
   kubectl get pod -n eks-hybrid-nodes-gateway {{LEADER_POD}} -o jsonpath='{.spec.containers[0].env}' | jq .
   ```
   +  `NODE_IP` se establece automáticamente a partir de `status.hostIP` en las especificaciones del pod. Si está vacío, es posible que el pod aún no esté programado en un nodo.
   +  `VPC_CIDR` y `POD_CIDRS` provienen de los valores de Helm. Compruebe que estén configurados correctamente.

1.  **Compruebe el reenvío de IP.** La puerta de enlace comprueba que el reenvío de IP esté activado al inicio y se cierra si no lo está. Busque el mensaje de error `IP forwarding is not enabled` en los registros del pod. Active el reenvío de IP en el nodo:

   ```
   # Check current setting
   cat /proc/sys/net/ipv4/ip_forward
   
   # Enable if not set
   sudo sysctl -w net.ipv4.ip_forward=1
   ```

   Para una configuración persistente, configure el reenvío de IP a través del kubelet o agregue `net.ipv4.ip_forward=1` a `/etc/sysctl.d/`.

1.  **Compruebe la etiqueta del nodo y las restricciones de programación.** Los pods de puerta de enlace requieren nodos con la etiqueta `hybrid-gateway-node=true`. La antiafinidad de los pods garantiza que cada pod se ejecute en un nodo independiente. Si los pods lo están `Pending`, compruebe si hay problemas de programación:

   ```
   kubectl describe pod -n eks-hybrid-nodes-gateway {{LEADER_POD}}
   ```

   Busque eventos que indiquen nodos insuficientes, etiquetas faltantes o conflictos de antiafinidad.

## Cuestiones de elección de líderes
<a name="hybrid-nodes-gateway-ts-leader"></a>

Los pods de puerta de enlace están en funcionamiento, pero ningún pod adquiere la concesión de líder o las transiciones de liderazgo se producen con frecuencia.

 **Causas posibles:** 
+ Faltan los permisos RBAC para los objetos de concesión.
+ La conectividad de red entre los pods de puerta de enlace y el servidor de API de Kubernetes no es fiable.
+ Los parámetros de elección del líder están mal configurados.

 **Pasos de diagnóstico:** 

1.  **Compruebe el objeto de concesión.** Compruebe que la concesión existe e inspeccione el titular actual:

   ```
   kubectl get lease -n eks-hybrid-nodes-gateway hybrid-gateway-leader -o yaml
   ```

   El campo `spec.holderIdentity` muestra el líder actual. `spec.renewTime` muestra cuándo se renovó la concesión por última vez. Si `renewTime` está obsoleto, es posible que el líder haya perdido la conectividad con el servidor de API.

1.  **Compruebe los permisos de RBAC.** La cuenta de servicio de puerta de enlace necesita permisos para obtener, crear y actualizar los objetos de concesión en el espacio de nombres de la puerta de enlace. Compruebe el rol y RoleBinding:

   ```
   kubectl get role -n eks-hybrid-nodes-gateway
   kubectl get rolebinding -n eks-hybrid-nodes-gateway
   ```

   El rol debe incluir los verbos `get`, `create` y `update` del recurso `leases` del grupo de API `coordination.k8s.io`.

1.  **Compruebe los registros de los pods para ver si hay errores de concesión.** Busque errores en la elección del líder en los registros del pod:

   ```
   kubectl logs -n eks-hybrid-nodes-gateway {{LEADER_POD}} | grep -i "leader\|lease"
   ```

   Entre los problemas más frecuentes se incluyen:
   +  `Failed to acquire lease`: el pod no puede crear ni actualizar el objeto de concesión. Compruebe los permisos de RBAC.
   + `Leadership ended` frecuentes seguidos de mensajes `Leader setup complete`: el líder pierde la concesión y la vuelve a adquirir. Esto puede indicar una inestabilidad de la red entre el pod y el servidor de API. Considere la posibilidad de aumentar `--leader-election-lease-duration`.

1.  **Compruebe los parámetros de elección de líderes.** Compruebe los valores configurados:

   ```
   kubectl get deployment eks-hybrid-nodes-gateway -n eks-hybrid-nodes-gateway -o jsonpath='{.spec.template.spec.containers[0].args}'
   ```

   Asegúrese de que `--leader-election-renew-deadline` sea menor que `--leader-election-lease-duration`. Si la fecha límite de renovación supera la duración de la concesión, el líder pierde la concesión antes de poder renovarla. Para obtener más información, consulte [Ajuste de elección de líderes](hybrid-nodes-gateway-configuration.md#hybrid-nodes-gateway-leader-tuning).

## Mensajes de error comunes
<a name="hybrid-nodes-gateway-ts-errors"></a>

En la siguiente tabla se enumeran los mensajes de error que pueden aparecer en los registros de los pods de la puerta de enlace y sus soluciones.


| Mensaje de error | Causa | Resolución | 
| --- | --- | --- | 
|  `IP forwarding is not enabled`  | El parámetro del kernel `net.ipv4.ip_forward` no está configurado en `1` en el nodo de puerta de enlace. | Active el reenvío de IP a través de la configuración de kubelet o ejecutando `sysctl -w net.ipv4.ip_forward=1`. | 
|  `Failed to setup VXLAN`  | La puerta de enlace no puede crear la interfaz de red VXLAN. Esto suele ocurrir cuando el pod carece de la capacidad `NET_ADMIN`. | Compruebe si las especificaciones de implementación incluyen `NET_ADMIN` en `securityContext.capabilities.add`. Compruebe que el gráfico de Helm esté implementado correctamente. | 
|  `Failed to verify route table access`  | La puerta de enlace no puede describir una o más tablas de enrutamiento de la VPC al inicio. | Compruebe que el rol de IAM tenga el permiso `ec2:DescribeRouteTables` y que los ID de la tabla de enrutamiento de la configuración sean correctos. | 
|  `Failed to update route tables`  | La puerta de enlace no puede crear ni reemplazar rutas en las tablas de enrutamiento de la VPC. | Compruebe que el rol de IAM tiene permisos `ec2:CreateRoute` y `ec2:ReplaceRoute`. | 
|  `Failed to create route table manager`  | La puerta de enlace no puede inicializar el cliente de AWS EC2 ni recuperar el ENI principal de la instancia. | Compruebe que el rol de IAM tiene el permiso `ec2:DescribeInstances` y que se puede obtener acceso al servicio de metadatos de instancias (IMDS). | 
|  `NODE_IP is required`  | La variable de entorno `NODE_IP` o el indicador `--node-ip` no están configurados. | Compruebe que la especificación del pod establece `NODE_IP` a partir de `status.hostIP` mediante `fieldRef`. Compruebe que el gráfico de Helm esté implementado correctamente. | 
|  `Invalid NODE_IP`  | El valor proporcionado para `NODE_IP` no es una dirección IP válida. | Compruebe el valor de la variable de entorno `NODE_IP` en la especificación del pod. | 
|  `pod-cidrs and vpc-cidr are required`  | La variable de entorno `POD_CIDRS` o `VPC_CIDR` está vacía. | Establezca los valores `podCIDRs` y `vpcCIDR` de Helm durante la instalación. | 
|  `No valid route table IDs provided`  | El valor `ROUTE_TABLE_IDS` se estableció, pero no contiene ningún ID de tabla de enrutamiento válido después del análisis. | Compruebe el valor `routeTableIDs` de Helm para ver si hay errores de formato. Los ID de las tablas de enrutamiento deben estar separados por comas (por ejemplo, `rtb-abc123,rtb-def456`). | 
|  `Failed to auto-detect AWS region`  | La puerta de enlace no puede recuperar la región de AWS de los metadatos de la instancia de EC2. | Compruebe que se puede acceder al servicio de metadatos de instancias (IMDS). Como alternativa, defina el indicador `--aws-region` o la variable de entorno `AWS_REGION` de forma explícita. | 
|  `Failed to auto-detect AWS instance ID`  | La puerta de enlace no puede recuperar el ID de instancia de los metadatos de la instancia de EC2. | Compruebe que se puede acceder al servicio de metadatos de instancias (IMDS). Como alternativa, defina el indicador `--aws-instance-id` o la variable de entorno `AWS_INSTANCE_ID` de forma explícita. | 
|  `CiliumNode has no internal IP`  | El objeto `CiliumNode` de un nodo híbrido no tiene una dirección IP interna en sus especificaciones. | Compruebe que el nodo híbrido esté registrado correctamente y que el agente Cilium esté en ejecución. Compruebe el recurso `CiliumNode` del nodo. | 
|  `CiliumNode <name> has no pod CIDRs allocated`  | El objeto `CiliumNode` de un nodo híbrido no tiene los CIDR de pod asignados por IPAM de Cilium. | Compruebe que el IPAM de Cilium esté configurado correctamente en el nodo híbrido. Compruebe el recurso `CiliumNode` para ver el estado de IPAM del nodo. | 
|  `Failed to upsert CiliumVTEPConfig`  | La puerta de enlace no puede crear ni actualizar el recurso `CiliumVTEPConfig` personalizado. | Compruebe que el CRD esté instalado en el clúster y que la cuenta de servicio de puerta de enlace tenga permisos para administrar recursos `CiliumVTEPConfig`. | 
|  `Unable to create manager`  | No se pudo inicializar el administrador de tiempo de ejecución del controlador. | Compruebe los registros de pod para obtener un contexto adicional. Entre las causas más comunes se incluyen una configuración de kubeconfig no válida o la imposibilidad de acceder al servidor de API de Kubernetes. | 
|  `Failed to add gateway setup`  | El ejecutable elegido por el líder no se pudo registrar en el administrador del controlador. | Por lo general, se trata de un error interno. Compruebe los registros completos del pod para obtener más contexto e informe del problema en el [repositorio de GitHub](https://github.com/aws/eks-hybrid-nodes-gateway). | 
|  `Unable to create Node controller`  | No se pudo registrar el conciliador de CiliumNode en el administrador del controlador. | Compruebe los registros de pod para obtener un contexto adicional. Compruebe que el CRD de CiliumNode esté instalado en el clúster. | 
|  `Problem running manager`  | El administrador de controladores se cerró inesperadamente. | Compruebe los registros del pod para ver si hay un error subyacente. Entre las causas más comunes se incluyen la pérdida de conectividad con el servidor de API de Kubernetes o un conflicto de puertos en las direcciones de enlace de las métricas o de las sondas de estado. | 
|  `failed to access route table <id>`  | La puerta de enlace no puede describir una tabla de enrutamiento de la VPC específica durante la comprobación de inicio. | Compruebe que el rol de IAM tenga el permiso `ec2:DescribeRouteTables` y que el ID de la tabla de enrutamiento sea correcto. La tabla de enrutamiento debe existir en la misma región que la instancia de la puerta de enlace. | 

## Temas relacionados
<a name="hybrid-nodes-gateway-ts-related"></a>
+  [Puerta de enlace de Nodos híbridos de Amazon EKS](hybrid-nodes-gateway-overview.md): descripción general de la arquitectura de la puerta de enlace y de los casos de uso.
+  [Introducción a la puerta de enlace de nodos híbridos de EKS](hybrid-nodes-gateway-getting-started.md): requisitos previos e instrucciones de instalación.
+  [Referencia de configuración de la puerta de enlace de Nodos híbridos de Amazon EKS](hybrid-nodes-gateway-configuration.md): referencia completa de los valores de Helm, los indicadores de CLI y las variables de entorno.
+  [Operaciones de puerta de enlace de Nodos híbridos de Amazon EKS](hybrid-nodes-gateway-operations.md): guía de supervisión, comportamiento de conmutación por error y escalado.