**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.

# Comece a usar o gateway do EKS Hybrid Nodes
<a name="hybrid-nodes-gateway-getting-started"></a>

Esta página orienta você pelos pré-requisitos, pela preparação do ambiente, pela instalação, pela verificação e pela remoção do gateway do Amazon EKS Hybrid Nodes. Para obter uma introdução ao gateway e à sua arquitetura, consulte [Gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-overview.md).

## Pré-requisitos
<a name="hybrid-nodes-gateway-prerequisites"></a>

Antes de realizar a instalação do gateway do Hybrid Nodes, verifique se o ambiente preenche os seguintes requisitos:
+  **Cluster EKS compatível com a CNI e com o componente VTEP do Cilium**: o cluster do EKS deve usar a versão do Cilium para EKS como a CNI nos nós híbridos, e o Cilium VTEP deve estar habilitado. Para obter mais informações, consulte [Configuração da CNI para o gateway do Hybrid Nodes](hybrid-nodes-gateway-cni.md).
+  **CNI da AWS VPC em nós na nuvem**: os nós de gateway e outros nós na nuvem no cluster devem usar a CNI da AWS VPC. O gateway depende do roteamento nativo da VPC para encaminhar o tráfego entre a VPC e o túnel VXLAN.
+  **Conectividade híbrida**: é necessária uma conexão privada entre a VPC e o ambiente on-premises. Você pode usar o AWS Direct Connect, o AWS Site-to-Site VPN ou sua própria solução de VPN. Para obter mais informações, consulte [Preparar a rede para nós híbridos](hybrid-nodes-networking.md).
+  **Tráfego VXLAN permitido**: os grupos de segurança associados às instâncias do EC2 do gateway devem permitir tráfego UDP de entrada e de saída na porta 8472. No lado do nó híbrido, as regras do firewall on-premises também devem permitir o tráfego UDP na porta 8472 de e para os endereços IP do nó de gateway.
+  **Permissões do IAM para o gerenciamento da tabela de rotas**: o gateway requer as seguintes ações do EC2 para gerenciar tabelas de rotas da VPC:
  +  `ec2:DescribeRouteTables` 
  +  `ec2:CreateRoute` 
  +  `ec2:ReplaceRoute` 
  +  `ec2:DescribeInstances` 

    Você pode conceder essas permissões usando uma das seguintes abordagens:

------
#### [ EKS Pod Identity (recommended) ]

    Use a [Identidade de Pods do EKS](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html) para conceder permissões somente à conta de serviço do pod de gateway.

    1. Instale o complemento do Agente de Identidade de Pods do EKS no cluster, caso ainda não esteja instalado:

       ```
       aws eks create-addon \
         --cluster-name {{CLUSTER_NAME}} \
         --addon-name eks-pod-identity-agent
       ```

    1. Crie um perfil do IAM com as permissões do EC2 necessárias e uma política de confiança para a Identidade de Pods do EKS:

       ```
       cat > gateway-trust-policy.json << 'EOF'
       {
         "Version": "2012-10-17" 		 	 	 ,
         "Statement": [
           {
             "Effect": "Allow",
             "Principal": { "Service": "pods.eks.amazonaws.com" },
             "Action": ["sts:AssumeRole", "sts:TagSession"]
           }
         ]
       }
       EOF
       
       aws iam create-role \
         --role-name EKSHybridNodesGatewayRole \
         --assume-role-policy-document file://gateway-trust-policy.json
       
       aws iam put-role-policy \
         --role-name EKSHybridNodesGatewayRole \
         --policy-name HybridNodesGatewayRouteTable \
         --policy-document '{
           "Version": "2012-10-17" 		 	 	 ,
           "Statement": [{
             "Effect": "Allow",
             "Action": [
               "ec2:DescribeRouteTables",
               "ec2:CreateRoute",
               "ec2:ReplaceRoute",
               "ec2:DescribeInstances"
             ],
             "Resource": "*"
           }]
         }'
       ```

    1. Crie uma associação de identidade de pods vinculando o perfil do IAM à conta de serviço do gateway:

       ```
       aws eks create-pod-identity-association \
         --cluster-name {{CLUSTER_NAME}} \
         --namespace eks-hybrid-nodes-gateway \
         --service-account eks-hybrid-nodes-gateway \
         --role-arn {{arn:aws:iam::ACCOUNT_ID:role/EKSHybridNodesGatewayRole}}
       ```

------
#### [ Node IAM role ]

    Anexe uma política em linha ou gerenciada com as permissões necessárias ao perfil do IAM associado ao perfil de instância dos nós de gateway:

    ```
    aws iam put-role-policy \
      --role-name {{NODE_ROLE_NAME}} \
      --policy-name HybridNodesGatewayRouteTable \
      --policy-document '{
        "Version": "2012-10-17" 		 	 	 ,
        "Statement": [{
          "Effect": "Allow",
          "Action": [
            "ec2:DescribeRouteTables",
            "ec2:CreateRoute",
            "ec2:ReplaceRoute",
            "ec2:DescribeInstances"
          ],
          "Resource": "*"
        }]
      }'
    ```

    Todos os pods presentes nos nós de gateway terão essas permissões.

------
+  **Modo Automático do EKS (se estiver usando o Modo Automático para nós de gateway)**: se você planeja usar o Modo Automático do EKS para provisionar nós de gateway, o Modo Automático deve estar habilitado no cluster do EKS. Para obter mais informações, consulte [Habilitar o Modo Automático do EKS](https://docs.aws.amazon.com/eks/latest/userguide/migrate-auto.html).

## Preparação dos nós de gateway
<a name="hybrid-nodes-gateway-prepare-nodes"></a>

O gateway requer pelo menos dois nós do EC2 para o fornecimento de alta disponibilidade. Existem duas opções de configuração de nós compatíveis com o gateway:
+  [Modo Automático do EKS (recomendado)](#hybrid-nodes-gateway-auto-mode-nodes): os nós são provisionados automaticamente usando um `NodePool` e uma `NodeClass`. A verificação de origem e de destino, os rótulos e os taints são configurados declarativamente.
+  [Grupos de nós gerenciados](#hybrid-nodes-gateway-mng-nodes): você provisiona nós usando um grupo de nós gerenciado ou nós autogerenciados. Os rótulos podem ser configurados por meio da API do grupo de nós gerenciado e a verificação de origem e de destino pode ser desabilitada usando um modelo de inicialização personalizado com dados do usuário.

### Modo Automático do EKS (recomendado)
<a name="hybrid-nodes-gateway-auto-mode-nodes"></a>

Ao usar o Modo Automático do EKS, você deve criar um `NodePool` e uma `NodeClass` antes de instalar o chart do Helm. O NodePool provisiona instâncias do EC2 com rótulos adequados, taints e configuração de verificação destinada à origem e ao destino. Você não precisa provisionar ou configurar nós manualmente.

Aplique os seguintes recursos ao cluster, substituindo os valores com espaço reservado:
+  {{YOUR\_NODE\_ROLE}}: o nome do perfil do IAM do nó usado pelo Modo Automático do EKS para provisionar nós. Este é o perfil que você configurou, ou que o EKS criou, ao habilitar o Modo Automático no cluster. Para obter mais informações, consulte [Criar um perfil do IAM de nó para o Modo Automático do EKS](https://docs.aws.amazon.com/eks/latest/userguide/auto-create-node-role.html).
+  {{YOUR\_CLUSTER\_NAME}}: o nome do cluster do EKS.
+  {{SUBNET\_ID\_1}} e {{SUBNET\_ID\_2}}: IDs de sub-rede em diferentes zonas de disponibilidade em que os nós de gateway serão provisionados.

```
apiVersion: eks.amazonaws.com/v1
kind: NodeClass
metadata:
  name: hybrid-gateway
spec:
  advancedNetworking:
    sourceDestCheck: DisabledPrimaryENI
  role: {{YOUR_NODE_ROLE}}
  securityGroupSelectorTerms:
    - tags:
        aws:eks:cluster-name: {{YOUR_CLUSTER_NAME}}
  subnetSelectorTerms:
    - id: {{SUBNET_ID_1}}
    - id: {{SUBNET_ID_2}}
---
apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: hybrid-gateway
spec:
  template:
    metadata:
      labels:
        hybrid-gateway-node: "true"
    spec:
      expireAfter: 336h
      nodeClassRef:
        group: eks.amazonaws.com
        kind: NodeClass
        name: hybrid-gateway
      requirements:
        - key: karpenter.sh/capacity-type
          operator: In
          values:
            - on-demand
        - key: eks.amazonaws.com/instance-category
          operator: In
          values:
            - c
            - m
            - r
        - key: eks.amazonaws.com/instance-generation
          operator: Gt
          values:
            - "4"
        - key: kubernetes.io/arch
          operator: In
          values:
            - amd64
        - key: kubernetes.io/os
          operator: In
          values:
            - linux
      taints:
        - key: hybrid-gateway-node
          effect: NoSchedule
      terminationGracePeriod: 24h0m0s
  disruption:
    budgets:
      - nodes: 10%
    consolidateAfter: 30s
    consolidationPolicy: WhenEmptyOrUnderutilized
```

Campos principais nesta configuração:
+  `advancedNetworking.sourceDestCheck: DisabledPrimaryENI`: desativa a verificação de origem e de destino do EC2 na ENI primária do nó, permitindo que o gateway encaminhe tráfego que não seja endereçado a si mesmo.
+  `taints`: o taint `hybrid-gateway-node: NoSchedule` garante que apenas pods de gateway com uma programação de tolerância correspondente sejam executados nesses nós.
+  `labels`: o rótulo `hybrid-gateway-node: "true"` é usado pelo seletor de nós do chart do Helm para direcionar pods de gateway para esses nós.
+  `nodeClassRef`: vincula o NodePool à NodeClass com a configuração de verificação de origem e de destino.

### Grupos de nós gerenciados
<a name="hybrid-nodes-gateway-mng-nodes"></a>

Ao usar grupos de nós gerenciados, crie um grupo de nós dedicado ao gateway com os rótulos, taints e um modelo de inicialização personalizado necessários que desabilite a verificação de origem e de destino na inicialização.

#### Etapa 1: Criar um modelo de execução
<a name="_step_1_create_a_launch_template"></a>

Crie um modelo de inicialização com dados do usuário que desabilite a verificação de origem e de destino na ENI primária quando a instância for inicializada:

```
# Create the launch template with user data to disable source/dest check
USERDATA=$(cat <<'SCRIPT' | base64 -w 0
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==BOUNDARY=="

--==BOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"

#!/bin/bash
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 60")
MAC=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/mac)
ENI_ID=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  "http://169.254.169.254/latest/meta-data/network/interfaces/macs/${MAC}/interface-id")
REGION=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/placement/region)

aws ec2 modify-network-interface-attribute \
  --network-interface-id "$ENI_ID" \
  --no-source-dest-check \
  --region "$REGION"

--==BOUNDARY==--
SCRIPT
)

aws ec2 create-launch-template \
  --launch-template-name {{YOUR_CLUSTER_NAME}}-gateway-lt \
  --launch-template-data "{\"UserData\":\"${USERDATA}\",\"MetadataOptions\":{\"HttpTokens\":\"required\",\"HttpPutResponseHopLimit\":2}}"
```

**nota**  
O perfil do IAM do nó deve ter a permissão `ec2:ModifyNetworkInterfaceAttribute` para que o script de dados do usuário seja executado com sucesso. O formato MIME multipart garante que os dados do usuário sejam executados em conjunto com o script de inicialização do EKS.

#### Etapa 2: criar o grupo de nós gerenciados
<a name="_step_2_create_the_managed_node_group"></a>

Crie um grupo de nós gerenciados dedicado com o rótulo do gateway, o taint e o modelo de inicialização da Etapa 1:

```
aws eks create-nodegroup \
  --cluster-name {{YOUR_CLUSTER_NAME}} \
  --nodegroup-name {{YOUR_CLUSTER_NAME}}-gateway-nodes \
  --subnets {{SUBNET_ID_1 SUBNET_ID_2}} \
  --node-role {{YOUR_NODE_ROLE_ARN}} \
  --instance-types {{INSTANCE_TYPE}} \
  --ami-type AL2023_x86_64_STANDARD \
  --scaling-config desiredSize=2,maxSize=2,minSize=2 \
  --labels hybrid-gateway-node=true \
  --taints "key=hybrid-gateway-node,effect=NO_SCHEDULE" \
  --launch-template "name={{YOUR_CLUSTER_NAME}}-gateway-lt,version=1"
```

Isso cria um grupo de nós gerenciados de dois nós em que:
+  `--labels` define `hybrid-gateway-node=true` para que o seletor de nós do chart do Helm direcione esses nós.
+  `--taints` adiciona um taint `NoSchedule` para que apenas os pods de gateway com uma programação de tolerância correspondente sejam executados nesses nós.
+  `--launch-template` anexa o modelo de inicialização que desabilita a verificação de origem e de destino na inicialização.

Use sub-redes em diferentes zonas de disponibilidade para obter alta disponibilidade.

## Instalação usando o Helm
<a name="hybrid-nodes-gateway-install"></a>

### Modo Automático do EKS
<a name="hybrid-nodes-gateway-install-auto"></a>

Execute o seguinte comando para instalar o gateway com o Modo Automático do EKS:

```
helm install eks-hybrid-nodes-gateway \
  oci://public.ecr.aws/eks/eks-hybrid-nodes-gateway \
  --version 1.0.0 \
  --namespace eks-hybrid-nodes-gateway \
  --create-namespace \
  --set vpcCIDR={{VPC_CIDR}} \
  --set podCIDRs={{POD_CIDRS}} \
  --set routeTableIDs={{ROUTE_TABLE_IDS}}
```

### Grupos de nós gerenciados ou nós autogerenciados
<a name="hybrid-nodes-gateway-install-mng"></a>

Para grupos de nós gerenciados ou nós autogerenciados, defina `autoMode.enabled=false`:

```
helm install eks-hybrid-nodes-gateway \
  oci://public.ecr.aws/eks/eks-hybrid-nodes-gateway \
  --version 1.0.0 \
  --namespace eks-hybrid-nodes-gateway \
  --create-namespace \
  --set autoMode.enabled=false \
  --set vpcCIDR={{VPC_CIDR}} \
  --set podCIDRs={{POD_CIDRS}} \
  --set routeTableIDs={{ROUTE_TABLE_IDS}}
```

### Valores obrigatórios para o Helm
<a name="hybrid-nodes-gateway-required-values"></a>

Os seguintes valores são obrigatórios para todas as instalações:


| Valor | Descrição | 
| --- | --- | 
|  `vpcCIDR`  | O bloco CIDR da VPC do cluster do EKS (por exemplo, `10.0.0.0/16`). Usado para a configuração do Cilium VTEP, para que os nós híbridos encaminhem o tráfego destinado à VPC por meio do gateway. | 
|  `podCIDRs`  | Lista separada por vírgulas de CIDRs de pods usados ​​pelo Cilium nos nós híbridos (por exemplo, `10.100.0.0/16,10.101.0.0/16`). O gateway cria entradas na tabela de rotas da VPC e rotas VXLAN para esses CIDRs. | 
|  `routeTableIDs`  | Lista separada por vírgulas dos IDs da tabela de rotas da VPC a serem programados (por exemplo, `rtb-0abc1234def567890,rtb-0fed9876cba543210`). O gateway cria rotas nessas tabelas, direcionando os CIDRs dos pods híbridos para a instância de gateway ativa. | 

Para obter uma lista completa dos valores configuráveis, consulte [Referência de configuração para o gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-configuration.md).

## Verificar a instalação
<a name="hybrid-nodes-gateway-verify"></a>

Após instalar o gateway, verifique se ele está funcionando corretamente e sem problemas.

### Verificação do status do pod
<a name="hybrid-nodes-gateway-verify-pods"></a>

Confirme se dois pods de gateway estão em execução:

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

O resultado exibido deve ser semelhante a:

```
NAME                                        READY   STATUS    RESTARTS   AGE
eks-hybrid-nodes-gateway-5d4f6a7b8c-abc12   1/1     Running   0          2m
eks-hybrid-nodes-gateway-5d4f6a7b8c-def34   1/1     Running   0          2m
```

### Verificação da eleição de líder
<a name="hybrid-nodes-gateway-verify-leader"></a>

Confirme se um pod adquiriu o lease de eleição de líder:

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

O resultado mostra o líder atual na coluna `HOLDER`:

```
NAME                     HOLDER                                      AGE
hybrid-gateway-leader    eks-hybrid-nodes-gateway-5d4f6a7b8c-abc12   2m
```

### Verificação do endpoint de integridade
<a name="hybrid-nodes-gateway-verify-health"></a>

Verifique se o endpoint de integridade está respondendo no pod líder usando o encaminhamento de portas:

```
kubectl port-forward -n eks-hybrid-nodes-gateway {{LEADER_POD_NAME}} 8088:8088 &
curl -s http://localhost:8088/healthz
```

Se o gateway estiver íntegro, ele retornará uma resposta HTTP 200.

### Verificação das entradas da tabela de rotas da VPC
<a name="hybrid-nodes-gateway-verify-routes"></a>

No console da Amazon VPC ou usando a AWS CLI, confirme se as tabelas de rotas da VPC contêm entradas para os CIDRs dos pods híbridos com direcionamento para a ENI da instância do gateway líder:

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

Cada CIDR dos pods híbridos deve ter uma rota em que o campo `NetworkInterfaceId` esteja configurado para a ENI primária da instância líder.

## Desinstalar
<a name="hybrid-nodes-gateway-uninstall"></a>

Para remover o gateway do Hybrid Nodes, execute:

```
helm uninstall eks-hybrid-nodes-gateway --namespace eks-hybrid-nodes-gateway
```

**nota**  
A desinstalação do chart do Helm não remove automaticamente as entradas da tabela de rotas da VPC criadas pelo gateway. Após a desinstalação, exclua manualmente as rotas dos CIDRs dos pods híbridos nas tabelas de rotas da VPC para evitar o roteamento de tráfego para instâncias que não estão mais executando o gateway. É possível remover as rotas usando a AWS CLI:  

```
aws ec2 delete-route \
  --route-table-id {{ROUTE_TABLE_ID}} \
  --destination-cidr-block {{POD_CIDR}}
```

## Próximas etapas
<a name="hybrid-nodes-gateway-getting-started-next"></a>
+  [Referência de configuração para o gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-configuration.md): personalize valores do Helm, sinalizadores da CLI e parâmetros de eleição de líder.
+  [Operações de gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-operations.md): monitore o gateway, compreenda o comportamento de failover e planeje o ajuste de escala.
+  [Solução de problemas do gateway do Amazon EKS Hybrid Nodes](hybrid-nodes-gateway-troubleshooting.md): diagnostique e resolva problemas comuns.