排查 GKE 中的专用集群问题

本页面介绍了如何解决 Google Kubernetes Engine (GKE) 专用集群的问题。

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

专用集群未在运行

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

创建专用集群时超时

每个专用集群都要求 VPC 之间存在对等互连路由，但一次只能执行一项对等互连操作。如果您尝试同时创建多个专用集群，则创建集群的操作可能会超时。为避免这种情况，请依次创建新的专用集群，以便每个后续专用集群都存在 VPC 对等互连路由。如果 VPC 上有操作正在运行，则尝试创建单个专用集群的操作也可能会超时。

专用集群上的 VPC 网络对等互连连接意外删除

表现

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

error checking if node NODE_NAME is shutdown: unimplemented
潜在原因

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

解决方法

请按照以下步骤操作：

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

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

集群与活动对等互连重叠

表现

如果尝试创建专用集群，则系统会返回类似于以下内容的错误：

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 重新创建集群。

无法访问专用集群的控制平面

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

表现

创建专用集群后，如果尝试针对集群运行 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 无法与集群控制平面通信。

解决方法

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

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

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

      gcloud container clusters describe CLUSTER_NAME \
      --format="value(masterAuthorizedNetworksConfig)"\
      --location=COMPUTE_LOCATION

    替换以下内容：

    如果来源 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 命令，请确保已启用控制平面专用端点全球访问权限。如需了解详情，请参阅在全球范围内访问控制平面的专用端点。

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

    gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --flatten "privateClusterConfig.masterGlobalAccessConfig"

    替换以下内容：

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

      enabled: true

  2. 如果返回 null，请启用对控制平面的全球访问权限。

由于 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 元数据中，应该在删除集群后移除。即使集群已成功删除，元数据也可能未被移除。
解决方法

请按照以下步骤操作：

无法创建子网

表现

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

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

您指定的控制平面 CIDR 范围与集群中的其他 IP 地址范围重叠。如果您最近删除了某个专用集群并且尝试使用相同的控制层面 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 以外的 servicePort 的 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。
解决方法

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

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。

解决方法

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

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

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

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

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

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

专用 GKE 集群中的 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 范围。