本指南可帮助您诊断工作负载(Pod 或虚拟机)无法使用 Cloud NAT 访问外部网络的原因。作为开发者,您主要与 CloudNatGateway 资源进行交互。此资源的状态是您进行调试的主要可信来源。
准备工作
如需排查 Cloud NAT 配置问题,您必须具备以下条件:
- 必要的身份和访问角色。请让您的 IAM 项目管理员为您授予以下一个或两个角色:
- Cloud NAT Viewer (
cloud-nat-viewer):此角色提供对 Cloud NAT 资源的只读权限。此角色可帮助您开始诊断问题。 - Cloud NAT Developer (
cloud-nat-developer):此角色为应用运维人员提供在分配的项目中创建、读取、更新和删除 (CRUD) Cloud NAT 对象所需的权限。此角色可让您执行本页面中所述的许多修复操作。 - 对于某些特定的诊断措施和修复,可能需要其他角色。
- Cloud NAT Viewer (
初始诊断
在深入了解错误代码之前,请确保基本资源存在且可访问。
命令:
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 与您项目中的另一个网关匹配相同的工作负载。无法确定性地路由流量。 |
|
CloudNATSubnetRefsFieldInvalidCode |
子网无效。
|
|
CloudNATSubnetAlreadyInUseCode |
子网冲突。您请求的子网已由另一个 Cloud NAT 网关“拥有”。一个子网一次只能连接到一个网关。 |
|
UNETAPIServerErrorCode |
系统错误。控制器无法与 API 服务器通信以验证子网。 | 操作:这可能是暂时性的平台问题。如果问题仍然存在,请与您的平台管理员联系。 |
边界配置错误(PerimeterConfigurationReady 为 False)
此条件反映了边界网关的状态。
| 错误代码 | 具体含义 | 补救步骤 |
|---|---|---|
NET-E0305 |
配置冲突。(同上)。重叠的选择器会导致系统无法计算正确的路由组。 |
|
NET-E0301 |
资源耗尽/节点故障。系统已创建配置,但无法将您的出站 IP 分配给运行状况良好的物理节点。这通常意味着子网 IP 地址已用尽或网关节点已关闭。 |
|
NET-E0001 |
系统错误。控制器通信失败。 | 操作:请与平台管理员联系。 |
出站路由错误(EgressRoutesReady 为 False)
此条件反映了集群内路由政策的状态。
| 错误代码 | 具体含义 | 补救步骤 |
|---|---|---|
NET-E0305 |
配置冲突。(同上)。 |
|
NET-E0304 |
编程失败。系统未能为您的特定网关 IP 编程路由规则 (BPF)。 | 操作:这是内部编程错误或状态不一致。
|
其他常见问题
如果 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 网关的目标。
确定目标 Pod:获取遇到连接问题的 Pod 的标签。
kubectl get pod <POD_NAME> -n <NAMESPACE> --show-labels检查是否存在冲突的标签:
- Cloud NAT 选择:Pod 的标签是否与命名空间中任何
CloudNatGateway的workloadSelector匹配? - 默认出站流量标签:Pod 是否具有标签
egress.networking.gke.io/enabled: "true"?
条件:如果两者都为 true,则表示存在冲突。
- Cloud NAT 选择:Pod 的标签是否与命名空间中任何
解决方法:从 Pod(或其父级 Deployment/StatefulSet)中移除旧版默认出站流量标签,以允许 Cloud NAT 接管独占控制权。
诊断虚拟机冲突
对于虚拟机,机制有所不同。具有 VirtualMachineExternalAccess (VMEA) 对象的虚拟机通常配置为默认访问权限。如需使用 Cloud NAT,他们必须通过添加注解来停用默认路径并启用 Cloud NAT 路径,从而明确选择启用。
识别 VMEA:找到与虚拟机相关联的
VirtualMachineExternalAccess对象。kubectl get vmea -n <NAMESPACE>检查是否缺少注释:
- Cloud NAT 选择:虚拟机的标签是否与
CloudNatGateway匹配? - 选择启用注解:检查 VMEA 是否有注解
egress.networking.gke.io/use-cloud-nat: "true"。
条件:如果虚拟机与网关匹配,但缺少此注解,则流量将与默认出站流量系统发生冲突。
- Cloud NAT 选择:虚拟机的标签是否与
解决方法:将注解添加到 VMEA 对象。
kubectl annotate vmea <VMEA_NAME> -n <NAMESPACE> egress.networking.gke.io/use-cloud-nat="true"