排查 Cloud NAT 问题

本指南可帮助您诊断工作负载(Pod 或虚拟机)无法使用 Cloud NAT 访问外部网络的原因。作为开发者,您主要与 CloudNatGateway 资源进行交互。此资源的状态是您进行调试的主要可信来源。

准备工作

如需排查 Cloud NAT 配置问题,您必须具备以下条件:

  • 必要的身份和访问角色。请让您的 IAM 项目管理员为您授予以下一个或两个角色:
    • Cloud NAT Viewer (cloud-nat-viewer):此角色提供对 Cloud NAT 资源的只读权限。此角色可帮助您开始诊断问题。
    • Cloud NAT Developer (cloud-nat-developer):此角色为应用运维人员提供在分配的项目中创建、读取、更新和删除 (CRUD) Cloud NAT 对象所需的权限。此角色可让您执行本页面中所述的许多修复操作。
    • 对于某些特定的诊断措施和修复,可能需要其他角色。

初始诊断

在深入了解错误代码之前,请确保基本资源存在且可访问。

命令:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

替换以下内容:

  • GATEWAY_NAME:CloudNatGateway 资源的名称。
  • PROJECT_NAMESPACE:项目的命名空间。

检查状态条件:健康的网关必须将以下所有条件设置为 True:

  • Ready:全局健康状态。
  • SubnetsReady:IP 池配置有效。
  • PerimeterConfigurationReady:上游网络基础架构已配置。
  • EgressRoutesReady:Pod 的路由政策处于有效状态。

如果其中任何一个为 False,请检查状态输出中的 reason 和 message 字段,并参阅以下部分中的表格。

错误代码参考和修复

kubectl get cloudnatgateway 返回的错误代码分为三大类。

子网错误(SubnetsReady 为 False)

此情况表示分配给网关的 IP 地址池存在问题。

错误代码 具体含义 补救步骤
CloudNATSelectorFieldOverlapsCode 配置冲突。此网关的 workloadSelector 与您项目中的另一个网关匹配相同的工作负载。无法确定性地路由流量。
  1. 列出项目中的所有 Cloud NAT 网关:kubectl get cloudnatgateway
  2. 将此网关的 workloadSelector 与其他网关进行比较。
  3. 修改标签,确保每个 Pod/虚拟机仅被一个网关选中。
CloudNATSubnetRefsFieldInvalidCode

子网无效。subnetRefs 中指定的子网无法使用。常见原因:

  • 子网不存在。
  • 子网不处于 Ready 状态。
  • 子网不是“Leaf”类型。
  1. 验证子网是否存在:kubectl get subnet <SUBNET_NAME>
  2. 检查子网状态是否为 Ready。
  3. 确保子网 type 为 Leaf(Cloud NAT 无法使用根子网或环回子网)。
CloudNATSubnetAlreadyInUseCode 子网冲突。您请求的子网已由另一个 Cloud NAT 网关“拥有”。一个子网一次只能连接到一个网关。
  1. 为此网关选择其他子网。
  2. 或者,先从其他网关中移除该子网。
UNETAPIServerErrorCode 系统错误。控制器无法与 API 服务器通信以验证子网。 操作:这可能是暂时性的平台问题。如果问题仍然存在,请与您的平台管理员联系。

边界配置错误(PerimeterConfigurationReady 为 False)

此条件反映了边界网关的状态。

错误代码 具体含义 补救步骤
NET-E0305 配置冲突。(同上)。重叠的选择器会导致系统无法计算正确的路由组。
  1. 列出项目中的所有 Cloud NAT 网关:kubectl get cloudnatgateway
  2. 将此网关的 workloadSelector 与其他网关进行比较。
  3. 修改标签,确保每个 Pod/虚拟机仅被一个网关选中。
NET-E0301 资源耗尽/节点故障。系统已创建配置,但无法将您的出站 IP 分配给运行状况良好的物理节点。这通常意味着子网 IP 地址已用尽或网关节点已关闭。
  1. 检查您的 [子网](/distributed-cloud/hosted/docs/1.16/gdcag/platform/pa-user/subnets-overview)用量。是否已满?
  2. 如果子网有空闲 IP 且处于 Ready 状态,则表示平台端基础设施出现故障(例如,没有可用的健康网关节点)。操作:请与平台管理员联系。
NET-E0001 系统错误。控制器通信失败。 操作:请与平台管理员联系。

出站路由错误(EgressRoutesReady 为 False)

此条件反映了集群内路由政策的状态。

错误代码 具体含义 补救步骤
NET-E0305 配置冲突。(同上)。
  1. 列出项目中的所有 Cloud NAT 网关:kubectl get cloudnatgateway
  2. 将此网关的 workloadSelector 与其他网关进行比较。
  3. 修改标签,确保每个 Pod/虚拟机仅被一个网关选中。
NET-E0304 编程失败。系统未能为您的特定网关 IP 编程路由规则 (BPF)。

操作:这是内部编程错误或状态不一致。

  1. 尝试对网关进行细微更新(例如修改标签)以触发协调。
  2. 如果问题仍然存在,请与平台管理员联系。

其他常见问题

如果 Gateway 状态为 Ready: True,但流量仍然失败,请检查以下常见错误配置:

缺少项目级权限

您的项目必须获得明确授权才能流出流量。

  • 检查:您的 Project 资源是否具有标签 networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true"?
  • 解决方法:请让您的项目管理员应用此标签。

缺少虚拟机注解(仅限虚拟机)

虚拟机绕过标准 Pod 出站流量路径,需要明确指令才能使用 Cloud NAT。

  • 检查:虚拟机的 VirtualMachineExternalAccess (VMEA) 对象是否具有注解 egress.networking.gke.io/use-cloud-nat: "true"?
  • 修复方法:将注解添加到 VMEA 对象。

标准集群节点出站流量

如果您运行的是 Standard 集群,则节点本身需要出站权限。

  • 检查:Cluster 对象是否具有标签 cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true"?
  • 解决方法:请让您的平台管理员为 Cluster 对象添加标签。

默认出站流量 NAT 与 Cloud NAT 冲突

如果工作负载配置为使用旧版默认出站 NAT 机制,同时又被 Cloud NAT 网关选中,则会出现常见的配置错误。这种组合会导致冲突,即数据平面收到冲突的路由指令,从而导致丟包或不确定的路由行为。

诊断 Pod 冲突

对于 Pod,通常通过添加特定标签来启用默认出站流量 NAT。Pod 不能同时具有此标签和 Cloud NAT 网关的目标。

  1. 确定目标 Pod:获取遇到连接问题的 Pod 的标签。

    kubectl get pod <POD_NAME> -n <NAMESPACE> --show-labels
    
  2. 检查是否存在冲突的标签:

    • Cloud NAT 选择:Pod 的标签是否与命名空间中任何 CloudNatGateway 的 workloadSelector 匹配?
    • 默认出站流量标签:Pod 是否具有标签 egress.networking.gke.io/enabled: "true"?

    条件:如果两者都为 true,则表示存在冲突。

  3. 解决方法:从 Pod(或其父级 Deployment/StatefulSet)中移除旧版默认出站流量标签,以允许 Cloud NAT 接管独占控制权。

诊断虚拟机冲突

对于虚拟机,机制有所不同。具有 VirtualMachineExternalAccess (VMEA) 对象的虚拟机通常配置为默认访问权限。如需使用 Cloud NAT,他们必须通过添加注解来停用默认路径并启用 Cloud NAT 路径,从而明确选择启用。

  1. 识别 VMEA:找到与虚拟机相关联的 VirtualMachineExternalAccess 对象。

    kubectl get vmea -n <NAMESPACE>
    
  2. 检查是否缺少注释:

    • Cloud NAT 选择:虚拟机的标签是否与 CloudNatGateway 匹配?
    • 选择启用注解:检查 VMEA 是否有注解 egress.networking.gke.io/use-cloud-nat: "true"。

    条件:如果虚拟机与网关匹配,但缺少此注解,则流量将与默认出站流量系统发生冲突。

  3. 解决方法:将注解添加到 VMEA 对象。

    kubectl annotate vmea <VMEA_NAME> -n <NAMESPACE> egress.networking.gke.io/use-cloud-nat="true"