排查 GKE 中的网络隔离问题

Autopilot Standard

---

本页介绍了如何解决 Google Kubernetes Engine (GKE) 网络隔离方面的问题。

如果您需要其他帮助，请与 Cloud Customer Care 联系。

GKE 集群未运行

删除允许入站流量从集群控制平面传输到端口 10250 上的节点的防火墙规则，或者删除通往默认互联网网关的默认路由，都会导致集群停止运行。如果您删除默认路由，则必须确保将流量路由到必要的Google Cloud 服务。如需了解详情，请参阅自定义路由。

创建集群时超时

表现

在 1.28 或更低版本中使用专用节点创建的集群需要 VPC 之间存在对等互连路由。不过，一次只能进行一项对等连接操作。如果您尝试同时创建多个具有上述特征的集群，则创建集群的操作可能会超时。

解决方法

请使用以下任一解决方案：

• 在 1.28 或更低版本中依次创建集群，以便每个后续集群都存在 VPC 对等互连路由，且没有外部端点。如果 VPC 上有操作正在运行，则尝试创建单个集群的操作也可能会超时。

• 在 1.29 或更高版本中创建集群。

VPC 网络对等互连连接意外删除

表现

如果您不小心删除了 VPC 网络对等互连连接，集群会进入修复状态，并且所有节点都显示 UNKNOWN 状态。由于无法到达控制平面，因此您将无法对集群执行任何操作。检查控制平面时，日志会显示如下所示的错误：

error checking if node NODE_NAME is shutdown: unimplemented

潜在原因

您不小心删除了 VPC 网络对等互连连接。

解决方法

请按照以下步骤操作：

1. 创建新的临时 VPC 网络对等互连集群。创建集群会使 VPC 网络对等互连重新创建，旧集群会恢复为正常运行。

2. 在旧集群恢复为正常运行后，删除临时创建的 VPC 网络对等互连集群。

不小心删除了 Private Service Connect 端点和转发规则

表现

如果您不小心删除了 Private Service Connect 端点或转发规则，集群会进入修复状态，并且所有节点都显示 UNKNOWN 状态。由于无法访问控制平面，因此您将无法对集群执行任何操作。检查控制平面时，日志会显示如下所示的错误：

error checking if node NODE_NAME is shutdown: unimplemented

潜在原因

您不小心删除了 Private Service Connect 端点或转发规则。这两项资源都名为 gke-[cluster-name]-[cluster-hash:8]-[uuid:8]-pe，允许控制平面和节点以私密方式连接。

解决方法

轮替控制平面 IP 地址。

集群与活动对等互连重叠

表现

如果尝试创建不含外部端点的集群，则会返回类似于以下内容的错误：

Google Compute Engine: An IP range in the peer network overlaps with an IP
range in an active peer of the local network.

潜在原因

您选择了重叠的控制平面 CIDR。

解决方法

请使用以下任一解决方案：

• 删除集群，然后使用其他控制平面 CIDR 重新创建集群。
• 在 1.29 版中重新创建集群，并添加 --enable-private-nodes 标志。

无法访问没有外部端点的集群的控制平面

通过实现任一集群端点访问配置，提高集群控制平面的可达性。如需了解详情，请参阅集群端点访问权限。

表现

创建没有外部端点的集群后，如果尝试针对集群运行 kubectl 命令，则系统会返回类似于以下内容之一的错误：

Unable to connect to the server: dial tcp [IP_ADDRESS]: connect: connection
timed out.

Unable to connect to the server: dial tcp [IP_ADDRESS]: i/o timeout.

潜在原因

kubectl 无法与集群控制平面通信。

解决方法

请使用以下任一解决方案：

• 启用 DNS 访问权限，以便以简化的方式安全地访问集群。如需了解详情，请参阅基于 DNS 的端点。

• 验证是否已为 kubeconfig 生成集群的凭据或已激活正确的上下文。如需详细了解如何设置集群凭据，请参阅生成 kubeconfig 条目。

• 验证是否允许使用控制平面的外部 IP 地址对其进行访问。停用对集群控制平面的外部访问权限会将集群与互联网隔离开来。使用此配置时，只有已获授权的内部网络 CIDR 范围或预留的网络有权访问控制平面。

  1. 验证来源 IP 地址是否已获授权访问控制平面：

       gcloud container clusters describe CLUSTER_NAME \
           --format="value(controlPlaneEndpointsConfig.ipEndpointsConfig.authorizedNetworksConfig)"\
           --location=COMPUTE_LOCATION
     

     替换以下内容：

     • CLUSTER_NAME：您的集群的名称。
     • COMPUTE_LOCATION：集群的 Compute Engine 位置。

     如果来源 IP 地址未获得授权，则输出可能会返回空结果（只有大括号）或不包含来源 IP 地址的 CIDR 范围

     cidrBlocks:
       cidrBlock: 10.XXX.X.XX/32
       displayName: jumphost
       cidrBlock: 35.XXX.XXX.XX/32
       displayName: cloud shell
     enabled: true
     

  2. 添加已获授权的网络以访问控制平面。

• 如果您从本地环境或与集群位置不同的区域运行 kubectl 命令，请确保已启用控制平面专用端点全球访问权限。如需了解详情，请参阅使用控制平面的内部 IP 地址从任何区域访问。

  1. 描述集群以查看主服务器访问配置响应：

     gcloud container clusters describe CLUSTER_NAME \
         --location=COMPUTE_LOCATION \
         --flatten "controlPlaneEndpointsConfig.ipEndpointsConfig.globalAccess"
     

     替换以下内容：

     • CLUSTER_NAME：您的集群的名称。
     • COMPUTE_LOCATION：集群的 Compute Engine 位置。

     成功的输出内容类似如下：

       enabled: true
     

  2. 如果返回 null，请启用使用控制平面的内部 IP 地址从任何区域访问。

由于 IPv4 CIDR 块重叠而无法创建集群

表现

gcloud container clusters create 会返回如下所示的错误：

The given master_ipv4_cidr 10.128.0.0/28 overlaps with an existing network
10.128.0.0/20.

潜在原因

您指定了一个与 VPC 中现有子网重叠的控制平面 CIDR 地址块。

解决方法

为 --master-ipv4-cidr 指定一个与现有子网不重叠的 CIDR 块。

由于服务范围已被其他集群使用，因此无法创建集群

表现

尝试创建集群时，系统会返回类似于以下内容的错误：

Services range [ALIAS_IP_RANGE] in network [VPC_NETWORK], subnetwork
[SUBNET_NAME] is already used by another cluster.

潜在原因

以下配置可能会导致此错误：

• 您选择的服务范围正在被其他集群使用，或者该集群并未删除。
• 某个集群正在使用这个已删除的服务范围，但备用范围元数据未正确清理。GKE 集群的备用范围保存在 Compute Engine 元数据中，应该在删除集群后移除。即使集群已成功删除，元数据也可能未被移除。

解决方法

请按照以下步骤操作：

1. 检查现有集群是否正在使用该服务范围。您可以将 gcloud container clusters list 命令与 filter 标志结合使用以搜索集群。如果存在正在使用该服务范围的现有集群，则必须删除该集群或创建新的服务范围。
2. 如果现有集群未使用该服务范围，请手动移除与您要使用的服务范围匹配的元数据条目。

无法创建子网

表现

当您尝试使用自动子网创建集群或创建自定义子网时，可能会遇到以下任一错误：

An IP range in the peer network overlaps
with an IP range in one of the active peers of the local network.

Error: Error waiting for creating GKE cluster: Invalid value for field
PrivateClusterConfig.MasterIpv4CidrBlock: x.x.x.x/28 conflicts with an
existing subnet in one of the peered VPCs.

潜在原因

您指定的控制平面 CIDR 范围与集群中的其他 IP 范围重叠。如果您尝试重复使用最近删除的集群中使用的 master-ipv4-cidr CIDR，也可能会发生此子网创建错误。

解决方法

尝试使用其他 CIDR 范围。

无法从公共 Docker Hub 中拉取映像

表现

集群中运行的 Pod 在 kubectl describe 中显示警告：

Failed to pull image: rpc error: code = Unknown desc = Error response
from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled
while waiting for connection (Client.Timeout exceeded while awaiting
headers)

潜在原因

具有专用 IP 地址的节点只需进行额外配置即可满足互联网访问要求。但是，如果您已启用专用 Google 访问通道并满足其网络要求，则节点可以访问 Google Cloud API 和服务（包括 Artifact Registry）。

解决方法

请使用以下任一解决方案：

• 将您集群中的映像从 Docker Hub 复制到 Artifact Registry。如需了解详情，请参阅从第三方注册表迁移容器。

• GKE 会自动检查 mirror.gcr.io 中是否存在经常访问的 Docker Hub 映像的已缓存副本。

• 如果必须从 Docker Hub 或其他公共代码库拉取映像，请使用 Cloud NAT 或基于实例的代理（即静态 0.0.0.0/0 路由的目标）。

触发准入网络钩子超时的 API 请求

表现

如果准入网络钩子配置为使用具有 443 以外的 targetPort 的 Service，触发该准入网络钩子的 API 请求超时，导致请求失败：

Error from server (Timeout): request did not complete within requested timeout 30s

潜在原因

默认情况下，除端口 443 (HTTPS) 和 10250 (kubelet) 外，防火墙不允许与节点的 TCP 连接。如果没有允许流量的自定义防火墙规则，尝试在端口 443 以外的端口上与 pod 通信的准入网络钩子会失败。

解决方法

为特定用例添加防火墙规则。

由于健康检查失败，因此无法创建集群

表现

创建包含专用节点池的标准集群后，集群会卡在健康检查步骤，并报告类似于以下内容的错误：

All cluster resources were brought up, but only 0 of 2 have registered.

All cluster resources were brought up, but: 3 nodes out of 4 are unhealthy

潜在原因

以下配置可能会导致此错误：

• 集群节点无法从 Cloud Storage API (storage.googleapis.com) 下载所需的二进制文件。
• 限制出站流量的防火墙规则。
• 共享 VPC IAM 权限不正确。
• 专用 Google 访问通道要求您为 *.gcr.io 配置 DNS。

解决方法

请使用以下任一解决方案：

• 在子网上启用专用 Google 访问通道以允许节点网络访问 storage.googleapis.com，或者启用 Cloud NAT 以允许节点与 storage.googleapis.com 端点通信。

• 对于 storage.googleapis.com 的节点读取访问权限，请确认分配给集群节点的服务账号具有存储读取访问权限。

• 确保您拥有允许所有出站流量的Google Cloud 防火墙规则，或配置防火墙规则以允许节点到集群控制平面和 *.googleapis.com 的出站流量。

• 为 *.gcr.io 创建 DNS 配置。

• 如果您设置了非默认防火墙或路由，请配置专用 Google 访问通道。

• 如果您使用 VPC Service Controls，请为 GKE 集群设置 Container Registry 或 Artifact Registry。

• 确保尚未删除或修改 Ingress 的自动创建的防火墙规则。

• 如果使用共享 VPC，请确保已配置所需的 IAM 权限。

kubelet 无法创建 pod 沙盒

表现

创建包含专用节点的集群后，它会报告类似于以下内容的某项错误：

Warning  FailedCreatePodSandBox  12s (x9 over 4m)      kubelet  Failed to create pod sandbox: rpc error: code = Unknown desc = Error response from daemon: Get https://registry.k8s.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

NetworkReady=false reason:NetworkPluginNotReady message:docker: network plugin is not ready: cni config uninitialized

潜在原因

calico-node 或 netd Pod 无法访问 *.gcr.io。

解决方法

确保您已完成所需的 Container Registry 或 Artifact Registry 设置。

已创建专用节点，但未加入集群

对于仅使用具有专用 IP 地址的节点的集群，通常在 VPC 上使用自定义路由和第三方网络设备时，默认路由 (0.0.0.0/0) 会重定向到设备，而不是默认互联网网关。除了控制平面连接外，您还需要确保可以到达以下目的地：

• *.googleapis.com
• *.gcr.io
• gcr.io

为所有三个网域配置专用 Google 访问通道。利用此最佳做法，新节点可以启动并加入集群，同时使互联网出站流量受到限制。

GKE 集群上的工作负载无法访问互联网

在具有专用 IP 地址的节点中运行的 Pod 无法访问互联网。例如，从 Pod exec shell 运行 apt update 命令后，它会报告类似于以下内容的错误：

0% [Connecting to deb.debian.org (199.232.98.132)] [Connecting to security.debian.org (151.101.130.132)]

如果未在 Cloud NAT 网关上配置集群中用于 Pod 的子网次要 IP 地址范围，则 Pod 无法连接到互联网，因为它们没有为 Cloud NAT 网关配置外部 IP 地址。

请务必将 Cloud NAT 网关配置为至少对集群使用的子网应用以下子网 IP 地址范围：

• 子网主要 IP 地址范围（由节点使用）
• 集群中用于 Pod 的子网次要 IP 地址范围
• 集群中用于 Service 的子网次要 IP 地址范围

如需了解详情，请参阅如何添加用于 Pod 的次要子网 IP 范围。

无法为公共集群停用直接 IP 访问

表现

停用 IP 地址端点后，您会看到类似于以下内容的错误消息：

Direct IP access can't be disabled for public clusters

潜在原因

您的集群使用的是旧版网络。

解决方法

将集群迁移到 Private Service Connect。如需详细了解迁移状态，请 与支持团队联系 。

在 PSC 迁移期间，无法为集群停用直接 IP 访问

表现

停用 IP 地址端点后，您会看到类似于以下内容的错误消息：

Direct IP access can't be disabled for public clusters

潜在原因

您的集群使用的是旧版网络。

解决方法

请使用以下任一解决方案：

• 手动使用其他版本重新创建所有节点池。
• 等待 GKE 在维护事件期间自动升级节点池。

无法启用控制平面内部端点

表现

尝试启用集群控制平面的内部端点时，您会看到与以下内容类似的错误消息：

private_endpoint_enforcement_enabled can't be enabled when envoy is disabled

private_endpoint_enforcement_enabled is unsupported. Please upgrade to the minimum support version

潜在原因

您的集群需要轮替 IP 地址或进行版本更新。

解决方法

请使用以下任一解决方案：

• 轮替控制平面 IP 地址以启用 Envoy。
• 将集群升级到 1.28.10-gke.1058000 或更高版本。

定义组织政策后，集群创建失败

表现

尝试创建集群时，您会看到类似于以下内容的错误消息：

compute.disablePrivateServiceConnectCreationForConsumers violated for projects

潜在原因

集群端点或后端被使用方组织政策阻止。

解决方法

完成使用方组织政策中的步骤，允许实例创建具有 compute.restrictPrivateServiceConnectProducer 限制条件的端点。

Private Service Connect 端点可能会在集群删除期间泄露

表现

创建集群后，您可能会遇到以下某种症状：

• 您无法在基于 Private Service Connect 的集群中看到 Private Service Connect 下已连接的端点。

• 您无法删除为使用 Private Service Connect 的集群中的内部端点分配的子网或 VPC 网络。系统会显示类似于以下内容的错误消息：

  projects/<PROJECT_ID>/regions/<REGION>/subnetworks/<SUBNET_NAME> is already being used by projects/<PROJECT_ID>/regions/<REGION>/addresses/gk3-<ID>
  

潜在原因

在使用 Private Service Connect 的 GKE 集群上，GKE 会使用转发规则部署 Private Service Connect 端点，该转发规则会分配一个内部 IP 地址，以便在控制平面的网络中访问集群的控制平面。为了通过使用 Private Service Connect 保护控制平面与节点之间的通信，GKE 会使该端点不可见，您无法在Google Cloud 控制台或 gcloud CLI 中看到该端点。

解决方法

为防止在集群删除之前泄露 Private Service Connect 端点，请完成以下步骤：

1. 将 Kubernetes Engine Service Agent role 分配给 GKE 服务账号。
2. 确保 GKE 服务账号未明确拒绝 compute.forwardingRules.* 和 compute.addresses.* 权限。

如果您看到 Private Service Connect 端点泄露，请 与支持团队联系 。

无法解析集群的已获授权的网络

表现

您无法在 1.29 版或更高版本中创建集群。系统会显示类似于以下内容的错误消息：

Unable to parse cluster.master_ipv4_cidr "" into a valid IP address and mask

潜在原因

您的 Google Cloud 项目使用基于专用 IP 的 webhook。因此，您无法使用 Private Service Connect 创建集群。而是使用 VPC 网络对等互连，该功能会解析 master-ipv4-cidr 标志。

解决方法

请使用以下任一解决方案：

• 继续创建 VPC 网络对等互连集群，并添加 master-ipv4-cidr 以定义有效的 CIDR。此解决方案存在以下限制：

  • master-ipv4-cidr 标志已在 Google Cloud 控制台中废弃。如需更新此标志，您只能使用 Google Cloud CLI 或 Terraform。
  • VPC 网络对等互连已在 GKE 1.29 版或更高版本中废弃。

• 请完成Private Service Connect 限制中的步骤，以迁移基于专用 IP 的 webhook。然后， 与支持团队联系 ，选择启用集群与 Private Service Connect 搭配使用。

无法在包含公共节点的集群中定义内部 IP 地址范围

表现

您无法使用 --master-ipv4-cidr 标志定义内部 IP 地址范围。系统会显示类似以下内容的错误消息：

ERROR: (gcloud.container.clusters.create) Cannot specify --master-ipv4-cidr
  without --enable-private-nodes

潜在原因

您在未启用 enable-private-nodes 标志的集群中使用 master-ipv4-cidr 标志为控制平面定义内部 IP 地址范围。如需创建已定义 master-ipv4-cidr 的集群，您必须使用 enable-private-nodes 标志将集群配置为使用内部 IP 地址预配节点（专用节点）。

解决方法

请使用以下任一解决方案：

• 使用以下命令创建集群：

  gcloud container clusters create-auto CLUSTER_NAME \
      --enable-private-nodes \
      --master-ipv4-cidr CP_IP_RANGE
  

  替换以下内容：

  • CLUSTER_NAME：您的集群的名称。
  • CLUSTER_NAME：控制平面的内部 IP 地址范围。

• 更新集群，以仅使用 IP 地址预配节点。如需了解详情，请参阅配置集群。

无法在 Autopilot 集群上安排公开工作负载

表现

在 Autopilot 集群中，如果您的集群仅使用专用节点，则您无法使用 cloud.google.com/private-node=false nodeSelector 在公共 Pod 中调度工作负载。

潜在原因

在 Pod 的 nodeSelector 中将 private-node 标志设置为 false 的配置仅适用于版本 1.30.3 或更高版本的集群。

解决方法

将集群升级到 1.30 或更高版本。

基于 DNS 的端点的访问权限已停用

表现

如果尝试针对集群运行 kubectl 命令，则系统会返回类似于以下内容的错误：

couldn't get current server API group list:
control_plane_endpoints_config.dns_endpoint_config.allow_external_traffic is
disabled

潜在原因

您的集群已停用基于 DNS 的访问权限。

解决方法

使用基于 DNS 的控制平面端点启用对控制平面的访问。如需了解详情，请参阅修改控制平面访问权限。

节点在伸缩期间无法分配 IP 地址

表现

尝试将子网的主要 IP 地址范围扩展到已获授权的网络列表会返回类似以下的错误：

 authorized networks fields cannot be mutated if direct IP access is disabled

潜在原因

您已停用集群基于 IP 的端点。

解决方法

使用 enable-ip-access 标志停用和启用集群基于 IP 的端点。

CIDR 地址块太多

在尝试创建或更新具有超过 50 个 CIDR 地址块的集群时，gcloud 将返回以下错误：

ERROR: (gcloud.container.clusters.update) argument --master-authorized-networks: too many args

如需解决此问题，请尝试执行以下操作：

• 如果您的集群不使用 Private Service Connect 或 VPC 网络对等互连，请确保您指定的 CIDR 块数量不超过 50 个。
• 如果您的集群使用 Private Service Connect 或 VPC 网络对等互连，则指定的 CIDR 块数量不超过 100 个。

无法连接到服务器

由于 CIDR 地址块配置错误，kubectl 命令超时：

Unable to connect to the server: dial tcp MASTER_IP: getsockopt: connection timed out

创建或更新集群时，请确保指定了正确的 CIDR 块。