**Ajudar a melhorar esta página** 

Para contribuir com este guia de usuário, escolha o link **Editar esta página no GitHub**, disponível no painel direito de cada página.

# Solução de problemas do gateway do Amazon EKS Hybrid Nodes
<a name="hybrid-nodes-gateway-troubleshooting"></a>

Esta página fornece orientações para diagnosticar e resolver problemas comuns com o gateway do Amazon EKS Hybrid Nodes. Cada seção descreve um sintoma, causas possíveis, etapas de diagnóstico e resoluções. Para obter detalhes operacionais, consulte [Operações de gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-operations.md).

## Pods em nós híbridos inacessíveis por meio da VPC
<a name="hybrid-nodes-gateway-ts-unreachable"></a>

Os pods executados em nós híbridos não estão acessíveis por meio de recursos na VPC, como as instâncias do EC2, os balanceadores de carga ou o ambiente de gerenciamento do Kubernetes.

 **Causas possíveis:** 
+ As entradas da tabela de rotas da VPC estão ausentes ou direcionam para a ENI incorreta.
+ O pod líder do gateway não está em execução ou não concluiu a configuração.
+ O Cilium VTEP não está habilitado ou configurado nos nós híbridos.
+ A verificação de origem e de destino está habilitada na instância EC2 do gateway.

 **Etapas de diagnóstico:** 

1.  **Verifique as entradas da tabela de rotas da VPC.** Verifique se as rotas para os CIDRs dos pods híbridos existem e direcionam para a ENI primária da instância de gateway ativa:

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

   Se as rotas estiverem ausentes, verifique os logs do gateway em busca de erros na tabela de rotas. Se as rotas direcionarem para a ENI incorreta, é possível que um failover não tenha sido concluído com êxito.

1.  **Verifique o status do pod do gateway e a eleição de líder.** Confirme se dois pods de gateway estão em execução e se um mantém o lease de líder:

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

   Se nenhum pod detiver o lease, consulte [Questões relacionadas à eleição de líder](#hybrid-nodes-gateway-ts-leader).

1.  **Verifique a configuração do Cilium VTEP nos nós híbridos.** Confirme se o recurso `CiliumVTEPConfig` existe e contém o IP do nó líder:

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

   O `spec.endpoints[0].tunnelEndpoint` deve corresponder ao endereço IP do nó do gateway líder. Se o recurso estiver ausente ou com um IP desatualizado, o gateway pode não ter concluído a configuração do líder.

1.  **Verifique a verificação de origem e de destino.** Confirme se a verificação de origem e de destino está desabilitada nas instâncias do EC2 do gateway:

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

   Se `sourceDestCheck` for `true`, desabilite-o. Consulte [Comece a usar o gateway do EKS Hybrid Nodes](hybrid-nodes-gateway-getting-started.md).

## Chamadas de webhook para nós híbridos falham
<a name="hybrid-nodes-gateway-ts-webhooks"></a>

O servidor da API do Kubernetes não consegue acessar endpoints de webhook em execução nos nós híbridos. As solicitações de admissão de webhook expiram ou retornam erros de conexão.

 **Causas possíveis:** 
+ O gateway não está roteando o tráfego do ambiente de gerenciamento para os pods híbridos.
+ O recurso `CiliumVTEPConfig` está ausente ou tem um IP de endpoint desatualizado.

 **Etapas de diagnóstico:** 

1.  **Verifique se o ambiente de gerenciamento consegue acessar o IP do nó do gateway.** O ambiente de gerenciamento envia tráfego para a tabela de rotas da VPC, que o encaminha para a ENI do gateway. Confirme se as entradas da tabela de rotas da VPC estão corretas seguindo as etapas apresentadas em [Pods em nós híbridos inacessíveis por meio da VPC](#hybrid-nodes-gateway-ts-unreachable).

1.  **Verifique o recurso CiliumVTEPConfig.** Confirme se o recurso existe e se o `tunnelEndpoint` corresponde ao IP do nó do líder atual:

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

   Se o endpoint do túnel estiver desatualizado (direcionar para um líder anterior), o gateway pode não ter concluído a sequência de configuração do líder. Verifique os logs do gateway em busca de erros durante a atualização ou inserção do `CiliumVTEPConfig`.

## Falhas nas atualizações da tabela de rotas da VPC
<a name="hybrid-nodes-gateway-ts-routes"></a>

Os logs do gateway apresentam erros relacionados às operações da tabela de rotas da VPC, e as rotas para os CIDRs de pods híbridos não são criadas ou atualizadas.

 **Causas possíveis:** 
+ O perfil do IAM do gateway não tem as permissões do EC2 necessárias.
+ Os IDs da tabela de rotas na configuração estão incorretos ou as tabelas de rotas não existem.
+ O gateway não consegue acessar o endpoint da API do EC2.

 **Etapas de diagnóstico:** 

1.  **Verifique as permissões do IAM.** O gateway requer as seguintes ações do IAM:
   +  `ec2:DescribeRouteTables` 
   +  `ec2:CreateRoute` 
   +  `ec2:ReplaceRoute` 
   +  `ec2:DescribeInstances` 

     Verifique o perfil do IAM associado ao perfil de instância do nó do gateway ou à configuração de identidade de pods.

1.  **Verifique os IDs da tabela de rotas na configuração.** Confirme se a variável de ambiente `ROUTE_TABLE_IDS` contém IDs de tabela de rotas válidos na implantação do gateway:

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

   Confirme se os IDs da tabela de rotas existem na VPC:

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

1.  **Verifique os logs do gateway em busca de erros na tabela de rotas.** Procure mensagens de erro relacionadas às operações da tabela de rotas:

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

   As mensagens de erro mais comuns incluem:
   +  `Failed to verify route table access`: o gateway não consegue descrever a tabela de rotas. Verifique as permissões do IAM e os IDs da tabela de rotas.
   +  `Failed to update route tables`: o gateway não consegue criar ou substituir rotas. Verifique as permissões do IAM.
   +  `failed to access route table`: o ID da tabela de rotas pode estar incorreto ou o perfil do IAM não tem a permissão `ec2:DescribeRouteTables`.

## Pods do gateway falham ao iniciar ou não estão íntegros
<a name="hybrid-nodes-gateway-ts-pods"></a>

Os pods do gateway estão no estado `CrashLoopBackOff`, `Error` ou `Pending`, ou o endpoint de integridade retorna um erro.

 **Causas possíveis:** 
+ As variáveis de ambiente necessárias (`VPC_CIDR`, `POD_CIDRS` e `ROUTE_TABLE_IDS`) não estão definidas.
+ O encaminhamento de IP não está habilitado no nó do gateway.
+ As restrições de rótulo de nó ou de antiafinidade impedem o agendamento.

 **Etapas de diagnóstico:** 

1.  **Verifique os logs do pod.** Visualize os logs do pod com falha para identificar o erro:

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

1.  **Verifique as variáveis de ambiente necessárias.** O gateway requer `NODE_IP`, `VPC_CIDR` e `POD_CIDRS`. Se alguma estiver ausente, o gateway é encerrado imediatamente. Verifique a especificação do pod:

   ```
   kubectl get pod -n eks-hybrid-nodes-gateway {{LEADER_POD}} -o jsonpath='{.spec.containers[0].env}' | jq .
   ```
   +  `NODE_IP` é definido automaticamente usando `status.hostIP` na especificação do pod. Se estiver vazio, é possível que o pod ainda não tenha sido agendado em um nó.
   +  `VPC_CIDR` e `POD_CIDRS` são provenientes dos valores do Helm. Verifique se esses valores estão configurados corretamente.

1.  **Verifique o encaminhamento de IP.** O gateway verifica se o encaminhamento de IP está habilitado na inicialização e é encerrado caso contrário. Procure a mensagem de erro `IP forwarding is not enabled` nos logs do pod. Habilite o encaminhamento de IP no nó:

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

   Para uma configuração persistente, configure o encaminhamento de IP por meio do kubelet ou adicione `net.ipv4.ip_forward=1` ao `/etc/sysctl.d/`.

1.  **Verifique o rótulo do nó e as restrições de agendamento.** Os pods do gateway requerem nós com o rótulo `hybrid-gateway-node=true`. A antiafinidade de pod garante que cada pod seja executado em um nó separado. Caso os pods estejam no estado `Pending`, verifique se há problemas de agendamento:

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

   Procure eventos que indiquem nós insuficientes, rótulos ausentes ou conflitos de antiafinidade.

## Questões relacionadas à eleição de líder
<a name="hybrid-nodes-gateway-ts-leader"></a>

Os pods do gateway estão em execução, mas nenhum pod adquire o lease de líder, ou as transições de liderança ocorrem com frequência.

 **Causas possíveis:** 
+ As permissões do RBAC para objetos Lease estão ausentes.
+ A conectividade de rede entre os pods do gateway e o servidor de API do Kubernetes é instável.
+ Os parâmetros de eleição de líder estão configurados incorretamente.

 **Etapas de diagnóstico:** 

1.  **Verifique o objeto Lease.** Confirme se o Lease existe e inspecione seu detentor atual:

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

   O campo `spec.holderIdentity` apresenta o líder atual. O campo `spec.renewTime`, por sua vez, indica quando o lease foi renovado pela última vez. Caso `renewTime` esteja desatualizado, é possível que o líder tenha perdido a conectividade com o servidor de API.

1.  **Verifique as permissões do RBAC.** A conta de serviço do gateway precisa de permissões para obter, criar e atualizar objetos Lease no namespace do gateway. Verifique o Role e o RoleBinding:

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

   O Role deve incluir os verbos `get`, `create` e `update` para o recurso `leases` no grupo de API `coordination.k8s.io`.

1.  **Verifique os logs do pod em busca de erros de lease.** Procure erros de eleição de líder nos logs do pod:

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

   Os problemas comuns incluem:
   +  `Failed to acquire lease`: o pod não consegue criar ou atualizar o objeto Lease. Verifique as permissões do RBAC.
   + Mensagens frequentes de `Leadership ended` seguidas de `Leader setup complete`: o líder está perdendo e readquirindo o lease. Isso pode indicar instabilidade de rede entre o pod e o servidor de API. Considere aumentar `--leader-election-lease-duration`.

1.  **Verifique os parâmetros de eleição de líder.** Confirme os valores configurados:

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

   Certifique-se de que `--leader-election-renew-deadline` seja menor do que `--leader-election-lease-duration`. Caso o prazo de renovação ultrapasse a duração do lease, o líder perderá o lease antes de conseguir renová-lo. Para obter mais informações, consulte [Ajuste de eleição de líder](hybrid-nodes-gateway-configuration.md#hybrid-nodes-gateway-leader-tuning).

## Mensagens de erro comuns
<a name="hybrid-nodes-gateway-ts-errors"></a>

A tabela a seguir lista as mensagens de erro que podem aparecer nos logs do pod do gateway e como resolvê-las.


| A mensagem de erro | Causa | Resolução | 
| --- | --- | --- | 
|  `IP forwarding is not enabled`  | O parâmetro de kernel `net.ipv4.ip_forward` não está definido como `1` no nó do gateway. | Habilite o encaminhamento de IP por meio da configuração do kubelet ou executando `sysctl -w net.ipv4.ip_forward=1`. | 
|  `Failed to setup VXLAN`  | O gateway não consegue criar a interface de rede VXLAN. Isso ocorre normalmente quando o pod não tem a capacidade `NET_ADMIN`. | Verifique se a especificação de Deployment inclui `NET_ADMIN` em `securityContext.capabilities.add`. Confirme se o chart do Helm foi implantado corretamente. | 
|  `Failed to verify route table access`  | O gateway não consegue descrever uma ou mais tabelas de rotas da VPC na inicialização. | Verifique se o perfil do IAM tem a permissão `ec2:DescribeRouteTables` e se os IDs da tabela de rotas na configuração estão corretos. | 
|  `Failed to update route tables`  | O gateway não consegue criar ou substituir rotas nas tabelas de rotas da VPC. | Verifique se o perfil do IAM tem as permissões `ec2:CreateRoute` e `ec2:ReplaceRoute`. | 
|  `Failed to create route table manager`  | O gateway não consegue inicializar o cliente do AWS EC2 ou recuperar a ENI primária da instância. | Verifique se o perfil do IAM tem a permissão `ec2:DescribeInstances` e se o serviço de metadados de instância (IMDS) está acessível. | 
|  `NODE_IP is required`  | A variável de ambiente `NODE_IP` ou o sinalizador `--node-ip` não está definido. | Verifique se a especificação do pod define `NODE_IP` de um `status.hostIP` usando uma `fieldRef`. Confirme se o chart do Helm foi implantado corretamente. | 
|  `Invalid NODE_IP`  | O valor fornecido para `NODE_IP` não é um endereço IP válido. | Verifique o valor da variável de ambiente `NODE_IP` na especificação do pod. | 
|  `pod-cidrs and vpc-cidr are required`  | A variável de ambiente `POD_CIDRS` ou `VPC_CIDR` está vazia. | Defina os valores do Helm `podCIDRs` e `vpcCIDR` durante a instalação. | 
|  `No valid route table IDs provided`  | O valor de `ROUTE_TABLE_IDS` foi definido, mas não contém IDs de tabela de rotas válidos após a análise. | Verifique o valor do Helm `routeTableIDs` em busca de erros de formatação. Os IDs da tabela de rotas devem ser separados por vírgula (por exemplo, `rtb-abc123,rtb-def456`). | 
|  `Failed to auto-detect AWS region`  | O gateway não consegue recuperar a região da AWS usando os metadados da instância do EC2. | Verifique se o serviço de metadados de instância (IMDS) está acessível. Como alternativa, defina explicitamente o sinalizador `--aws-region` ou a variável de ambiente `AWS_REGION`. | 
|  `Failed to auto-detect AWS instance ID`  | O gateway não consegue recuperar o ID da instância usando os metadados da instância do EC2. | Verifique se o serviço de metadados de instância (IMDS) está acessível. Como alternativa, defina explicitamente o sinalizador `--aws-instance-id` ou a variável de ambiente `AWS_INSTANCE_ID`. | 
|  `CiliumNode has no internal IP`  | O objeto `CiliumNode` de um nó híbrido não tem um endereço IP interno em sua especificação. | Verifique se o nó híbrido está registrado corretamente e se o agente do Cilium está em execução. Verifique o recurso `CiliumNode` do nó. | 
|  `CiliumNode <name> has no pod CIDRs allocated`  | O objeto `CiliumNode` de um nó híbrido não tem CIDRs de pod alocados pelo IPAM do Cilium. | Verifique se o IPAM do Cilium está configurado corretamente no nó híbrido. Verifique o recurso `CiliumNode` para o status do IPAM do nó. | 
|  `Failed to upsert CiliumVTEPConfig`  | O gateway não consegue criar ou atualizar o recurso personalizado `CiliumVTEPConfig`. | Verifique se o CRD está instalado no cluster e se a conta de serviço do gateway tem permissões para gerenciar recursos `CiliumVTEPConfig`. | 
|  `Unable to create manager`  | O gerenciador do controller-runtime falhou ao inicializar. | Verifique os logs do pod para obter contexto adicional. As causas mais comuns incluem kubeconfig inválido ou impossibilidade de acessar o servidor de API do Kubernetes. | 
|  `Failed to add gateway setup`  | O executável eleito como líder não pôde ser registrado no gerenciador de controladores. | Normalmente, trata-se de um erro interno. Verifique os logs completos do pod para obter contexto adicional e relate o problema no [repositório do GitHub](https://github.com/aws/eks-hybrid-nodes-gateway). | 
|  `Unable to create Node controller`  | O reconciliador do CiliumNode não pôde ser registrado no gerenciador de controladores. | Verifique os logs do pod para obter contexto adicional. Confirme se o CRD do CiliumNode está instalado no cluster. | 
|  `Problem running manager`  | O gerenciador de controladores foi encerrado inesperadamente. | Verifique os logs do pod para identificar a causa-raiz. As causas comuns incluem a perda de conectividade com o servidor da API do Kubernetes ou um conflito de portas nos endereços de vinculação das métricas ou da sonda de integridade. | 
|  `failed to access route table <id>`  | O gateway não consegue descrever uma tabela de rotas da VPC específica durante a verificação de inicialização. | Verifique se o perfil do IAM tem a permissão `ec2:DescribeRouteTables` e se o ID da tabela de rotas está correto. A tabela de rotas precisa existir na mesma região que a instância do gateway. | 

## Tópicos relacionados
<a name="hybrid-nodes-gateway-ts-related"></a>
+  [Gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-overview.md): visão geral da arquitetura do gateway e casos de uso.
+  [Comece a usar o gateway do EKS Hybrid Nodes](hybrid-nodes-gateway-getting-started.md): pré-requisitos e instruções de instalação.
+  [Referência de configuração para o gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-configuration.md): referência completa para valores do Helm, sinalizadores da CLI e variáveis ​​de ambiente.
+  [Operações de gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-operations.md): orientações para o monitoramento, o comportamento de failover e a escalabilidade.