**帮助改进此页面** 要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。 # 开始使用 EKS 混合节点功能的网关本页将引导您完成 Amazon EKS 混合节点功能网关的先决条件、环境准备、安装、验证和移除。有关网关及其架构简介，请参阅 [Amazon EKS 混合节点功能网关](hybrid-nodes-gateway-overview.md)。 ## 先决条件在安装混合节点网关之前，请确保环境满足以下要求： + **支持 Cilium CNI 和 VTEP 的 EKS 集群**：EKS 集群必须在混合节点上使用 EKS 版本的 Cilium 作为 CNI，并且必须启用 Cilium VTEP。有关更多信息，请参阅 [为混合节点网关配置 CNI](hybrid-nodes-gateway-cni.md)。 + **云端节点上的 AWS VPC CNI**：网关节点和集群中的其他云端节点必须使用 AWS VPC CNI。网关依赖 VPC 原生路由在 VPC 与 VXLAN 隧道之间转发流量。 + **混合连接**：需要 VPC 与本地环境之间的私有连接。您可以使用 AWS Direct Connect、AWS Site-to-Site VPN 或您自己的 VPN 解决方案。有关更多信息，请参阅 [准备混合节点的联网](hybrid-nodes-networking.md)。 + **允许 VXLAN 流量**：附加到网关 EC2 实例的安全组必须允许端口 8472 上的入站和出站 UDP 流量。在混合节点端，本地防火墙规则还必须允许进出网关节点 IP 地址的 UDP 端口 8472 流量。 + **路由表管理的 IAM 权限**：网关需要以下 EC2 操作来管理 VPC 路由表： + `ec2:DescribeRouteTables` + `ec2:CreateRoute` + `ec2:ReplaceRoute` + `ec2:DescribeInstances` 您可以使用以下方法之一授予这些权限： ------ #### [ EKS Pod Identity (recommended) ] 使用 [EKS 容器组身份](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html)仅向网关容器组（pod）的服务账户授予权限。 1. 如果尚未安装，请在集群上安装 EKS 容器组身份代理附加组件： ``` aws eks create-addon \ --cluster-name {{CLUSTER_NAME}} \ --addon-name eks-pod-identity-agent ``` 1. 创建一个 IAM 角色，该角色具有所需的 EC2 权限，并附加适用于 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. 创建容器组身份关联，将 IAM 角色链接到网关服务账户： ``` 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 ] 将包含所需权限的内联策略或托管策略附加到与网关节点实例配置文件关联的 IAM 角色： ``` 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": "*" }] }' ``` 网关节点上的所有容器组（pod）都将具有这些权限。 ------ + **EKS 自动模式（如果对网关节点使用自动模式）**：如果计划使用 EKS 自动模式来预置网关节点，则必须在 EKS 集群上启用自动模式。有关更多信息，请参阅[启用 EKS 自动模式](https://docs.aws.amazon.com/eks/latest/userguide/migrate-auto.html)。 ## 准备网关节点网关至少需要两个 EC2 节点，才能实现高可用性。网关支持两种节点配置选项： + [EKS 自动模式（推荐）](#hybrid-nodes-gateway-auto-mode-nodes)：使用 `NodePool` 和 `NodeClass` 自动预置节点。源/目标检查、标签和污点均以声明方式配置。 + [托管节点组](#hybrid-nodes-gateway-mng-nodes)：您可以使用托管节点组或自行管理的节点预置节点。标签可以通过托管节点组 API 进行配置，源/目标检查可以通过包含用户数据的自定义启动模板禁用。 ### EKS 自动模式（推荐）使用 EKS 自动模式时，必须先创建 `NodePool` 和 `NodeClass`，然后再安装 Helm 图表。NodePool 会使用正确的标签、污点和源/目标检查配置来预置 EC2 实例。无需手动预置或配置节点。将以下资源应用到集群，并替换占位符值： + {{YOUR\_NODE\_ROLE}}：EKS 自动模式用于预置节点的节点 IAM 角色名称。这是您在集群上启用自动模式时配置的角色（或 EKS 创建的角色）。有关更多信息，请参阅[为 EKS 自动模式创建节点 IAM 角色](https://docs.aws.amazon.com/eks/latest/userguide/auto-create-node-role.html)。 + {{YOUR\_CLUSTER\_NAME}}：EKS 集群名称。 + {{SUBNET\_ID\_1}}、{{SUBNET\_ID\_2}}：将在其中预置网关节点的不同可用区中的子网 ID。 ``` 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 ``` 此配置中的关键字段： + `advancedNetworking.sourceDestCheck: DisabledPrimaryENI`：禁用节点主 ENI 上的 EC2 源/目标检查，以便网关可以转发非发往自身地址的流量。 + `taints`：`hybrid-gateway-node: NoSchedule` 污点可确保仅将容忍度相匹配的网关容器组（pod）调度到这些节点上。 + `labels`：`hybrid-gateway-node: "true"` 标签可用于 Helm 图表的节点选择器，以将网关容器组（pod）定向到这些节点。 + `nodeClassRef`：将 NodePool 链接到具有源/目标检查配置的 NodeClass。 ### 托管节点组使用托管节点组时，请为网关创建一个专用节点组，并包含所需的标签、污点以及在启动时禁用源/目标检查的自定义启动模板。 #### 步骤 1：创建启动模板创建一个包含用户数据的启动模板，以便在实例启动时禁用主 ENI 上的源/目标检查： ``` # 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}}" ``` **注意** 节点的 IAM 角色必须具有 `ec2:ModifyNetworkInterfaceAttribute` 权限才能让用户数据脚本成功执行。MIME 多部分格式可确保用户数据与 EKS 引导脚本一起运行。 #### 步骤 2：创建托管节点组创建一个专用托管节点组，其中包含网关标签、污点以及步骤 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" ``` 这将创建一个双节点的托管节点组，其中： + `--labels` 设置 `hybrid-gateway-node=true`，以便 Helm 图表的节点选择器定向到这些节点。 + `--taints` 添加 `NoSchedule` 污点，确保仅将容忍度相匹配的网关容器组（pod）调度到这些节点上。 + `--launch-template` 附加了在启动时禁用源/目标检查的启动模板。在不同可用区中使用子网以提供高可用性。 ## 使用 Helm 安装 ### EKS 自动模式运行以下命令，以使用 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}} ``` ### 托管节点组或自行管理的节点对于托管节点组或自行管理的节点，请设置 `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}} ``` ### 必需的 Helm 值以下值对于所有安装都是必需的： | 值 | 说明 | | --- | --- | | `vpcCIDR` | EKS 集群 VPC 的 CIDR 数据块（例如 `10.0.0.0/16`）。用于 Cilium VTEP 配置，以便混合节点将发往 VPC 的流量通过网关进行路由。 | | `podCIDRs` | 混合节点上 Cilium 使用的容器组（pod）CIDR 列表（以逗号分隔，例如 `10.100.0.0/16,10.101.0.0/16`）。网关会为这些 CIDR 创建 VPC 路由表条目和 VXLAN 路由。 | | `routeTableIDs` | 需要进行编程的 VPC 路由表 ID 列表（以逗号分隔，例如 `rtb-0abc1234def567890,rtb-0fed9876cba543210`）。网关会在这些路由表中创建路由，使混合容器组（pod）CIDR 的路由指向活动网关实例。 | 有关可配置值的完整列表，请参阅 [Amazon EKS 混合节点功能网关配置参考](hybrid-nodes-gateway-configuration.md)。 ## 验证安装安装网关后，请验证其是否正在运行且运行状况良好。 ### 检查容器组（pod）状态确认两个网关容器组（pod）正在运行： ``` kubectl get pods -n eks-hybrid-nodes-gateway ``` 您应该可以看到类似于以下的输出内容： ``` 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 ``` ### 检查主节点选举验证其中一个容器组（pod）是否已获取主节点选举租约： ``` kubectl get lease -n eks-hybrid-nodes-gateway ``` 输出会在 `HOLDER` 列中显示当前主节点： ``` NAME HOLDER AGE hybrid-gateway-leader eks-hybrid-nodes-gateway-5d4f6a7b8c-abc12 2m ``` ### 检查运行状况端点使用端口转发验证主节点容器组（pod）上的运行状况端点是否响应： ``` kubectl port-forward -n eks-hybrid-nodes-gateway {{LEADER_POD_NAME}} 8088:8088 & curl -s http://localhost:8088/healthz ``` 运行状况良好的网关会返回 HTTP 200 响应。 ### 检查 VPC 路由表条目通过 Amazon VPC 控制台或使用 AWS CLI，确认 VPC 路由表中包含指向主节点网关实例 ENI 的混合容器组（pod）CIDR 条目： ``` aws ec2 describe-route-tables \ --route-table-ids {{ROUTE_TABLE_ID}} \ --query "RouteTables[].Routes[?DestinationCidrBlock=='[.replaceable]`POD_CIDR`']" ``` 每个混合容器组（pod）CIDR 都应有一条路由，其中 `NetworkInterfaceId` 设置为主节点实例的主 ENI。 ## 卸载要移除混合节点网关，请运行： ``` helm uninstall eks-hybrid-nodes-gateway --namespace eks-hybrid-nodes-gateway ``` **注意** 卸载 Helm 图表不会自动移除网关创建的 VPC 路由表条目。卸载后，从 VPC 路由表中手动删除混合容器组（pod）CIDR 的路由，以避免将流量路由到不再运行网关的实例。您可以使用 AWS CLI 移除路由： ``` aws ec2 delete-route \ --route-table-id {{ROUTE_TABLE_ID}} \ --destination-cidr-block {{POD_CIDR}} ``` ## 后续步骤 + [Amazon EKS 混合节点功能网关配置参考](hybrid-nodes-gateway-configuration.md)：自定义 Helm 值、CLI 标志和主节点选举参数。 + [Amazon EKS 混合节点功能网关操作](hybrid-nodes-gateway-operations.md)：监控网关，了解失效转移行为并规划扩展。 + [Amazon EKS 混合节点功能网关问题排查](hybrid-nodes-gateway-troubleshooting.md)：诊断和解决常见问题。