Google Distributed Cloud for VMware（纯软件）的已知问题

本页面列出了 Google Distributed Cloud on VMware 的所有已知问题。本页面适用于管理底层技术基础设施生命周期，并在未实现服务等级目标 (SLO) 或应用失败时对提醒和页面做出响应的 IT 管理员和运维人员。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

如需按产品版本或类别过滤已知问题，请从以下下拉菜单中选择所需的过滤条件。

选择您的 Google Distributed Cloud 版本：

选择问题类别：

或者，搜索您的问题：

类别 已识别的版本 问题和解决方法
迁移 1.29、1.30

如果曾经启用了 Secret 加密，则将用户集群迁移到 Controlplane V2 会失败

将用户集群迁移到 Controlplane V2 时，如果曾经启用了始终开启的 Secret 加密，则迁移过程无法正确处理 Secret 加密密钥。由于此问题，新的 Controlplane V2 集群无法解密 Secret。如果以下命令的输出不为空，则表示始终开启的 Secret 加密已在某个时间点启用，并且集群受到此问题的影响：

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
      get onpremusercluster USER_CLUSTER_NAME \
      -n USER_CLUSTER_NAME-gke-onprem-mgmt \
      -o jsonpath={.spec.secretsEncryption}

如果您已开始迁移，但迁移失败，请与 Google 联系以获取支持。否则，请在迁移之前停用始终开启的 Secret 加密功能并解密 Secret。

迁移 1.29.0-1.29.600、1.30.0-1.30.100

如果启用了 Secret 加密，则将管理员集群从非 HA 迁移到 HA 会失败

如果管理员集群在 1.14 或更低版本时启用了始终开启的 Secret 加密，并从旧版本一直升级到受影响的 1.29 版和 1.30 版，则在将管理员集群从非 HA 迁移到 HA 时，迁移过程无法正确处理 Secret 加密密钥，由于此问题，新的 HA 管理员集群无法解密 Secret。

如需检查集群是否可能使用旧格式的密钥，请运行以下命令：

    kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get secret -n kube-system admin-master-component-options -o jsonpath='{.data.data}' | base64 -d | grep -oP '"GeneratedKeys":\[.*?\]'

如果输出显示空密钥（如下所示），则表示集群将受到此问题的影响：

    "GeneratedKeys":[{"KeyVersion":"1","Key":""}]

如果您已开始迁移，但迁移失败，请与 Google 联系以获取支持。

否则，请在开始迁移之前轮替加密密钥。
升级 1.16、1.28、1.29、1.30

在管理员工作站升级期间，系统错误地重新生成 credential.yaml

使用 gkeadm upgrade admin-workstation 命令升级管理员工作站时，系统会错误地重新生成 credential.yaml 文件。用户名和密码字段为空。此外，privateRegistry 键包含拼写错误。

admin-cluster.yaml 文件中也存在相同的 privateRegistry 键拼写错误。
由于 credential.yaml 文件是在管理员集群升级过程中重新生成的，因此即使您之前已更正拼写错误，该错误仍会存在。

临时解决方法：

  • 更新 credential.yaml 中的私有注册表键名称，使其与 admin-cluster.yaml 中的 privateRegistry.credentials.fileRef.entry 匹配。
  • 在 credential.yaml 中更新私有注册表用户名和密码。
升级 1.16、1.28

由于升级前协调超时，用户集群升级失败

升级用户集群时，升级前协调操作可能需要的时间超出定义的超时时间，导致升级失败。错误消息如下所示：

Failed to reconcile the user cluster before upgrade: the pre-upgrade reconcile failed, error message:
failed to wait for reconcile to complete: error: timed out waiting for the condition,
message: Cluster reconcile hasn't finished yet, please fix that before
rerun the upgrade.

升级前协调操作的超时时间为 5 分钟加上用户集群中每个节点池 1 分钟。

临时解决方法：

确保 gkectl diagnose cluster 命令通过并且没有错误。
通过将 --skip-reconcile-before-preflight 标志添加到 gkectl upgrade cluster 命令来跳过升级前协调操作。例如：

gkectl upgrade cluster --skip-reconcile-before-preflight --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
--config USER_CLUSTER_CONFIG_FILE
更新 1.16、1.28.0-1.28.800、1.29.0-1.29.400、1.30.0

更新 DataplaneV2 ForwardMode 不会自动触发 anetd DaemonSet 重启

当您使用 gkectl update cluster 更新用户集群 dataplaneV2.forwardMode 字段时，更改仅在 ConfigMap 中更新，anetd DaemonSet 直到重新启动后才会获取配置更改，并且不会应用您的更改。

临时解决方法：

gkectl update cluster 命令完成后，您会看到 Done updating the user cluster 的输出。看到该消息后，运行以下命令，以重启 anetd DaemonSet 来选取配置更改：

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG rollout restart daemonset anetd

检查重启后的 DaemonSet 就绪情况：

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get daemonset anetd

在上述命令的输出中，验证 DESIRED 列中的数字与 READY 列中的数字是否匹配。
升级 1.16

在管理员集群备份阶段，集群升级期间找不到 etcdctl 命令

在 1.16 版到 1.28 版用户集群升级期间，系统会备份管理员集群。管理员集群备份进程显示错误消息“etcdctl: command not found”。用户集群升级成功，管理员集群保持健康状态。唯一的问题是，管理员集群上的元数据文件未备份。

问题原因在于 etcdctl 二进制文件是在 1.28 版中添加的，并且在 1.16 版节点上不可用。

管理员集群备份涉及多个步骤，包括截取 etcd 快照，然后为管理员集群写入元数据文件。etcd 备份仍会成功，因为在对 etcd Pod 执行 exec 后，仍然可以触发 etcdctl。但是，写入元数据文件会失败，因为它仍依赖于要安装在节点上的 etcdctl 二进制文件。但是，元数据文件备份不会阻止进行备份，因此备份过程仍会成功，用户集群升级也同样会成功。

临时解决方法：

如果您想备份元数据文件，请按照使用 gkectl 备份和恢复管理员集群中的说明，使用与管理员集群版本匹配的 gkectl 版本触发单独的管理员集群备份。
安装 1.16-1.29

使用手动负载均衡功能时用户集群创建失败

创建配置为手动负载均衡的用户集群时，发生 gkectl check-config 失败，表示 ingressHTTPNodePort 值必须至少为 30000，即使停用了捆绑式入站流量也是如此。

无论 ingressHTTPNodePort 和 ingressHTTPSNodePort 字段是设置还是留空，都会出现此问题。

临时解决方法：

如需解决此问题，请忽略 gkectl check-config 返回的结果。如需停用捆绑式入站流量，请参阅停用捆绑式入站流量。
更新 1.29.0

使用高可用性 (HA) 管理员集群时，并且在迁移后有 0 或 1 个没有角色的管理员集群节点会出现 PodDisruptionBudget (PDB) 问题。如需检查是否存在没有角色的节点对象，请运行以下命令：

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG get nodes -o wide

如果迁移后有两个或更多没有角色的节点对象，则 PDB 配置有误。

症状：

管理员集群诊断的输出包含以下信息

Checking all poddisruptionbudgets...FAILURE
  Reason: 1 pod disruption budget error(s).
  Unhealthy Resources:
  PodDisruptionBudget metrics-server: gke-managed-metrics-server/metrics-server might be configured incorrectly: the total replicas(1) should be larger than spec.MinAvailable(1).

临时解决方法：

运行以下命令以删除 PDB：

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG delete pdb metrics-server -n gke-managed-metrics-server
安装、升级和更新 1.28.0-1.28.600,1.29.0-1.29.100

在很罕见的竞态条件下，Binary Authorization webhook 和 gke-connect Pod 错误的安装顺序可能会导致用户集群创建停滞，因为节点无法达到就绪状态。在受影响的场景中，用户集群创建可能会因节点无法达到就绪状态而停滞。如果发生这种情况，系统会显示以下消息：

     Node pool is not ready: ready condition is not true: CreateOrUpdateNodePool: 2/3 replicas are ready

临时解决方法：

  1. 从配置文件中移除 Binary Authorization 配置。如需了解设置说明，请参阅 GKE on VMware 的 Binary Authorization day 2 安装指南。
  2. 如需在当前集群创建过程中取消屏蔽不健康的节点，请使用以下命令暂时移除用户集群中的 Binary Authorization webhook 配置。 
            kubectl --kubeconfig USER_KUBECONFIG delete ValidatingWebhookConfiguration binauthz-validating-webhook-configuration
    引导过程完成后，您可以重新添加以下 webhook 配置。 
    apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: binauthz-validating-webhook-configuration
webhooks:
- name: "binaryauthorization.googleapis.com"
  namespaceSelector:
    matchExpressions:
    - key: control-plane
      operator: DoesNotExist
  objectSelector:
    matchExpressions:
    - key: "image-policy.k8s.io/break-glass"
      operator: NotIn
      values: ["true"]
  rules:
  - apiGroups:
    - ""
    apiVersions:
    - v1
    operations:
    - CREATE
    - UPDATE
    resources:
    - pods
    - pods/ephemeralcontainers
  admissionReviewVersions:
  - "v1beta1"
  clientConfig:
    service:
      name: binauthz
      namespace: binauthz-system
      path: /binauthz
    # CA Bundle will be updated by the cert rotator.
    caBundle: Cg==
  timeoutSeconds: 10
  # Fail Open
  failurePolicy: "Ignore"
  sideEffects: None
升级 1.16、1.28、1.29

在用户集群升级期间，如果用户集群中的镜像机器对象包含 deletionTimestamp，升级操作可能会卡住。如果升级卡住，则会显示以下错误消息：

    machine is still in the process of being drained and subsequently removed

如果您之前尝试通过对用户集群中的镜像机器运行 gkectl delete machine 来修复用户控制平面节点，则可能会出现此问题。

临时解决方法：

  1. 获取镜像机器对象并将其保存到本地文件以进行备份。
  2. 运行以下命令，从镜像机器中删除终结器，然后等待镜像机器从用户集群中删除。 
        kubectl --kubeconfig ADMIN_KUBECONFIG patch machine/MACHINE_OBJECT_NAME -n USER_CLUSTER_NAME-gke-onprem-mgmt -p '{"metadata":{"finalizers":[]}}' --type=merge
  3. 按照 Controlplane V2 用户集群控制平面节点中的步骤在控制平面节点上触发节点修复，以便使正确的源机器规范重新同步到用户集群。
  4. 重新运行 gkectl upgrade cluster 以恢复升级
配置、安装 1.15、1.16、1.28、1.29

对于 HA 管理员集群或 ControlPlane V2 用户集群，控制平面 VIP 需要与其他集群节点位于同一子网中。否则，集群创建会失败，因为 kubelet 无法使用控制平面 VIP 与 API 服务器进行通信。

临时解决方法：

在创建集群之前，请确保在其他集群节点所在的子网中配置控制平面 VIP。
安装、升级、更新 1.29.0 - 1.29.100

集群创建/升级失败，vsphere CSI Pod 中出现错误，显示 vCenter 用户名无效。这是因为使用的用户名不是完全限定域名。vsphere-csi-controller Pod 中的错误消息如下：

    GetCnsconfig failed with err: username is invalid, make sure it is a fully qualified domain username

由于向 vSphere CSI 驱动程序添加了验证以强制使用完全限定的网域用户名，因此此问题仅在 1.29 及更高版本中出现。

临时解决方法：

在凭据配置文件中为 vCenter 用户名使用完全限定域名。例如，不要使用“username1”，而应使用“username1@example.com”。
升级、更新 1.28.0 - 1.28.500

将管理员集群从 1.16 升级到 1.28 时，新管理员主机器的引导可能无法生成控制平面证书。此问题是由于在 1.28 及更高版本中为 Kubernetes API 服务器生成证书的方式发生变化引起的。对于在 1.10 及更早版本上创建，并一直升级到 1.16，且叶证书在升级前未轮替的集群，此问题会重现。

如需确定管理员集群升级失败是否由此问题引起，请执行以下步骤：

  1. 使用 SSH 连接到失败的管理员主机器。
  2. 打开 /var/log/startup.log 并搜索如下所示的错误：
Error adding extensions from section apiserver_ext
801B3213B57F0000:error:1100007B:X509 V3 routines:v2i_AUTHORITY_KEYID:unable to get issuer keyid:../crypto/x509/v3_akid.c:177:
801B3213B57F0000:error:11000080:X509 V3 routines:X509V3_EXT_nconf_int:error in extension:../crypto/x509/v3_conf.c:48:section=apiserver_ext, name=authorityKeyIdentifier, value=keyid>

临时解决方法：

  1. 使用 SSH 连接到管理员主机器。如需了解详情，请参阅使用 SSH 连接到管理员集群节点。
  2. 复制 /etc/startup/pki-yaml.sh 并将其命名为 /etc/startup/pki-yaml-copy.sh
  3. 修改 /etc/startup/pki-yaml-copy.sh。在以下扩展的部分中找到 authorityKeyIdentifier=keyidset 并将其更改为 authorityKeyIdentifier=keyid,issuer：apiserver_ext、client_ext、etcd_server_ext和 kubelet_server_ext。例如：
          [ apiserver_ext ]
      keyUsage = critical, digitalSignature, keyEncipherment
      extendedKeyUsage=serverAuth
      basicConstraints = critical,CA:false
      authorityKeyIdentifier = keyid,issuer
      subjectAltName = @apiserver_alt_names
  4. 将更改保存到 /etc/startup/pki-yaml-copy.sh。
  5. 使用文本编辑器打开 /opt/bin/master.sh，查找所有出现的 /etc/startup/pki-yaml.sh 并替换为 /etc/startup/pki-yaml-copy.sh，然后保存更改。
  6. 运行 /opt/bin/master.sh 以生成证书并完成机器启动。
  7. 再次运行 gkectl upgrade admin 以升级管理员集群。
  8. 升级完成后，按照启动轮替中的说明为管理员集群和用户集群轮替叶证书。
  9. 证书轮替完成后，对 /etc/startup/pki-yaml-copy.sh 进行与之前相同的修改，然后运行 /opt/bin/master.sh。
配置 1.29.0

当您运行 gkectl 以创建、更新或升级已启用 Dataplane V2 的集群时，系统会输出以下错误的警告消息：

WARNING: Your user cluster is currently running our original architecture with 
[DataPlaneV1(calico)]. To enable new and advanced features we strongly recommend
to update it to the newer architecture with [DataPlaneV2] once our migration 
tool is available.

gkectl 中存在一个 bug，导致只要未使用 dataplaneV2.forwardMode，它就会始终显示此警告，即使您已在集群配置文件中设置了 enableDataplaneV2: true 也是如此。

临时解决方法：

您可以放心地忽略此警告。
配置 1.28.0-1.28.400、1.29.0

创建 HA 管理员集群时，预检检查会显示以下不正确的错误消息：

- Validation Category: Network Configuration
    - [FAILURE] CIDR, VIP and static IP (availability and overlapping): needed
    at least X+1 IP addresses for admin cluster with X nodes

对于 1.28 及更高版本的 HA 管理员集群，这个要求是不正确的，因为它们不再具有插件节点。此外，由于在管理员集群配置文件的 network.controlPlaneIPBlock 部分中指定了 3 个管理员集群控制平面节点 IP，因此只有 kubeception 用户集群控制平面节点需要 IP 地址块文件中的 IP。

临时解决方法：

如需在非固定版本中跳过错误的预检检查，请将 --skip-validation-net-config 添加到 gkectl 命令。
操作 1.29.0-1.29.100

如果您从非 HA 管理员集群迁移到 HA 管理员集群，管理员集群中的 Connect Agent 会断开与 gkeconnect.googleapis.com 的连接，并显示错误“未能验证 JWT 签名”。这是因为在迁移过程中，KSA 签名密钥会发生变化，因此需要重新注册以刷新 OIDC JWK。

临时解决方法：

如需将管理员集群重新连接到 Google Cloud，请执行以下步骤以触发重新注册：

首先获取 gke-connect 部署名称：

kubectl --kubeconfig KUBECONFIG get deployment -n gke-connect

删除 gke-connect 部署：

kubectl --kubeconfig KUBECONFIG delete deployment GKE_CONNECT_DEPLOYMENT -n gke-connect

您可以通过向 onpremadmincluster CR 添加“force-reconcile”注解来为 onprem-admin-cluster-controller 触发强制协调：

kubectl --kubeconfig KUBECONFIG patch onpremadmincluster ADMIN_CLUSTER_NAME -n kube-system --type merge -p '
metadata:
  annotations:
    onprem.cluster.gke.io/force-reconcile: "true"
'

其理念为，如果 onprem-admin-cluster-controller 发现没有可用的现有 gke-connect，它将始终重新部署 gke-connect 部署并重新注册集群。

执行解决办法后（控制器可能需要几分钟时间才能完成协调），您可以验证 gke-connect-agent 日志中将不再出现“无法验证 JWT 签名”400 错误：

kubectl --kubeconfig KUBECONFIG logs GKE_CONNECT_POD_NAME -n gke-connect
安装、操作系统 1.28.0-1.28.500、1.29.0

Google Distributed Cloud 在 Docker 配置中为 Docker 网桥 IP 指定了专用子网 --bip=169.254.123.1/24，以防止预留默认的 172.17.0.1/16 子网。但是，在 1.28.0-1.28.500 和 1.29.0 版中，由于 COS 操作系统映像的倒退，Google Distributed Cloud 自定义 Docker 配置后，Docker 服务未重启。因此，Docker 选择默认的 172.17.0.1/16 作为其网桥 IP 地址子网。如果您已在该 IP 地址范围内运行工作负载，则可能会导致 IP 地址冲突。

临时解决方法：

如需解决此问题，您必须重启 Docker 服务：

sudo systemctl restart docker

验证 Docker 选择正确的网桥 IP 地址：

ip a | grep docker0

此解决方案在重新创建虚拟机后不会保留。每当重新创建虚拟机时，您都必须重新应用此解决方法。
update 1.28.0-1.28.400、1.29.0-1.29.100

标准 CNI 二进制文件 bridge, ipvlan, vlan, macvlan, dhcp, tuning, host-local, ptp, portmap 不包含在受影响版本的操作系统映像中。这些 CNI 二进制文件不会由数据平面 v2 使用，但可用于多网络接口功能中的其他网络接口。

具有这些 CNI 插件的多个网络接口将不起作用。

临时解决方法：

如果您使用此功能，请升级到包含修复的版本。
update 1.15、1.16、1.28

在集群节点上安装 multipathd 会干扰 vSphere CSI 驱动程序，导致用户工作负载无法启动。

临时解决方法：

  • 停用 multipathd
更新 1.15、1.16

如果由于跳过验证而导致管理员集群中的某些必需配置为空，管理员集群 webhook 可能会阻止添加这些配置。例如，如果现有管理员集群中未设置 gkeConnect 字段，则使用 gkectl update admin 命令添加该字段可能会收到以下错误消息：

admission webhook "vonpremadmincluster.onprem.cluster.gke.io" denied the request: connect: Required value: GKE connect is required for user clusters

临时解决方法：

  • 对于 1.15 版管理员集群，请运行带有 --disable-admin-cluster-webhook 标志的 gkectl update admin 命令。例如：
            gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --disable-admin-cluster-webhook
  • 对于 1.16 版管理员集群，请运行带有 --force 标志的 gkectl update admin 命令。例如：
            gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig ADMIN_CLUSTER_KUBECONFIG --force
配置 1.15.0-1.15.10、1.16.0-1.16.6、1.28.0-1.28.200

如果您将要使用手动负载均衡器（loadBalancer.kind 设置为 "ManualLB"），则无需在 1.16 版及更高版本高可用性 (HA) 管理员集群的配置文件中配置 loadBalancer.manualLB 部分。但是，如果此部分为空，Google Distributed Cloud 会向所有 NodePort 分配默认值（包括 manualLB.controlPlaneNodePort），这会导致集群创建失败，并显示以下错误消息：

- Validation Category: Manual LB
  - [FAILURE] NodePort configuration: manualLB.controlPlaneNodePort must
   not be set when using HA admin cluster, got: 30968

临时解决方法：

在 HA 管理员集群的管理员集群配置中指定 manualLB.controlPlaneNodePort: 0：

loadBalancer:
  ...
  kind: ManualLB
  manualLB:
    controlPlaneNodePort: 0
  ...
存储 1.28.0-1.28.100

Ubuntu 操作系统映像中缺少 nfs-common，这可能会导致使用依赖于 NFS 的驱动程序（如 NetApp）的客户出现问题。

如果在升级到 1.28 版后，日志包含如下所示的条目，则表示您受到此问题的影响： 
Warning FailedMount 63s (x8 over 2m28s) kubelet MountVolume.SetUp failed for volume "pvc-xxx-yyy-zzz" : rpc error: code = Internal desc = error mounting NFS volume 10.0.0.2:/trident_pvc_xxx-yyy-zzz on mountpoint /var/lib/kubelet/pods/aaa-bbb-ccc/volumes/kubernetes.io~csi/pvc-xxx-yyy-zzz/mount: exit status 32".

临时解决方法：

确保您的节点可以从 Canonical 下载软件包。

接下来，将以下 DaemonSet 应用到您的集群以安装 nfs-common：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: install-nfs-common
  labels:
    name: install-nfs-common
  namespace: kube-system
spec:
  selector:
    matchLabels:
      name: install-nfs-common
  minReadySeconds: 0
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 100%
  template:
    metadata:
      labels:
        name: install-nfs-common
    spec:
      hostPID: true
      hostIPC: true
      hostNetwork: true
      initContainers:
      - name: install-nfs-common
        image: ubuntu
        imagePullPolicy: IfNotPresent
        securityContext:
          privileged: true
        command:
        - chroot
        - /host
        - bash
        - -c
        args:
        - |
          apt install -y nfs-common
        volumeMounts:
        - name: host
          mountPath: /host
      containers:
      - name: pause
        image: gcr.io/gke-on-prem-release/pause-amd64:3.1-gke.5
        imagePullPolicy: IfNotPresent
      volumes:
      - name: host
        hostPath:
          path: /
存储 1.28.0-1.28.100

1.28.0 及更高版本的管理员集群支持 SPBM。但是，配置文件模板中缺少字段 vCenter.storagePolicyName。

临时解决方法：

如果要为管理员集群配置存储政策，请在管理员集群配置文件中添加“vCenter.storagePolicyName”字段。请参阅说明。
日志记录和监控 1.28.0-1.28.100

最近添加的 API kubernetesmetadata.googleapis.com 不支持 VPC-SC。这会导致元数据收集代理无法在 VPC-SC 下访问此 API。因此，指标元数据标签将缺失。

临时解决方法：

通过运行以下命令，在“kube-system”命名空间中设置 CR“stackdriver”，并将“featureGates.disableExperimentalMetadataAgent”字段设置为“true”

`kubectl -n kube-system patch stackdriver stackdriver -p '{"spec":{"featureGates":{"disableExperimentalMetadataAgent":true}}}'`

然后运行以下命令

`kubectl -n kube-system patch deployment stackdriver-operator -p '{"spec":{"template":{"spec":{"containers":[{"name":"stackdriver-operator","env":[{"name":"ENABLE_LEGACY_METADATA_AGENT","value":"true"}]}]}}}}'`

升级、更新 1.15.0-1.15.7、1.16.0-1.16.4、1.28.0

当管理员集群和任何启用了 ControlPlane V2 的用户集群使用不同的 vSphere 凭据时（例如，在更新管理员集群的 vSphere 凭据后），重启后 clusterapi-controller 可能会无法连接到 vCenter。查看在管理员集群的“kube-system”命名空间中运行的 clusterapi-controller 的日志，

kubectl logs -f -l component=clusterapi-controllers -c vsphere-controller-manager \
    -n kube-system --kubeconfig KUBECONFIG
 如果日志包含如下所示的条目，则表示您受到此问题的影响： 
E1214 00:02:54.095668       1 machine_controller.go:165] Error checking existence of machine instance for machine object gke-admin-node-77f48c4f7f-s8wj2: Failed to check if machine gke-admin-node-77f48c4f7f-s8wj2 exists: failed to find datacenter "VSPHERE_DATACENTER": datacenter 'VSPHERE_DATACENTER' not found

临时解决方法：

更新 vSphere 凭据，以使管理员集群和所有启用了 Controlplane V2 的用户集群使用相同的 vSphere 凭据。
日志记录和监控 1.14

Prometheus 可能会报告类似于以下示例的提醒：

Alert Name: cluster:gke-admin-test1: Etcd cluster kube-system/kube-etcd: 100% of requests for Watch failed on etcd instance etcd-test-xx-n001.

如需检查此提醒是否为可以忽略的误报，请完成以下步骤：

  1. 根据提醒消息中提供的 grpc_method 检查原始 grpc_server_handled_total 指标。在此示例中，请检查 Watch 的 grpc_code 标签。

    您可以使用 Cloud Monitoring 和以下 MQL 查询来检查此指标： 
    fetch
    k8s_container | metric 'kubernetes.io/anthos/grpc_server_handled_total' | align rate(1m) | every 1m
  2. 如果代码不是以下任何一个，则可以放心地忽略 OK 以外针对所有代码的提醒： 
    Unknown|FailedPrecondition|ResourceExhausted|Internal|Unavailable|DataLoss|DeadlineExceeded

临时解决方法：

如需将 Prometheus 配置为忽略这些误报提醒，请查看以下选项：

  1. 在 Alert Manager 界面中暂停提醒。
  2. 如果无法暂停提醒，请查看以下步骤来抑制误报：
    1. 将监控 operator 缩减到 0 个副本，以便修改可以保留。
    2. 修改 prometheus-config configmap 并将 grpc_method!="Watch" 添加到 etcdHighNumberOfFailedGRPCRequests 提醒配置，如以下示例所示：
      • 原始： 
        rate(grpc_server_handled_total{cluster="CLUSTER_NAME",grpc_code!="OK",job=~".*etcd.*"}[5m])
      • 已修改： 
        rate(grpc_server_handled_total{cluster="CLUSTER_NAME",grpc_code=~"Unknown|FailedPrecondition|ResourceExhausted|Internal|Unavailable|DataLoss|DeadlineExceeded",grpc_method!="Watch",job=~".*etcd.*"}[5m])
         将以下 CLUSTER_NAME 替换为您的集群名称。
    3. 重启 Prometheus 和 Alertmanager Statefulset 以获取新配置。
  3. 如果代码属于有问题的情况之一，请检查 etcd 日志和 kube-apiserver 日志以进一步调试。
网络 1.16.0-1.16.2、1.28.0

如果没有流量，出站流量 NAT 连接可能会在连接建立连接 5 到 10 分钟后中断。

由于 conntrack 仅在入站方向（与集群的外部连接）上很重要，因此只有在连接在一段时间内未传输任何信息，然后目的地端传输了内容时，才会出现此问题。如果出站流量 NAT 的 Pod 始终实例化消息传递，则不会看到此问题。

出现此问题的原因是 anetd 垃圾回收无意中移除了守护程序认为未被使用的 conntrack 条目。anetd 中最近集成了上游修复，以纠正该行为。


临时解决方法：

没有简单的临时解决方法，而且我们在 1.16 版中尚未发现由于此行为导致的问题。如果您发现长期有效的连接由于此问题而中断，则临时解决方法是在出站流量 IP 地址所在的节点上使用工作负载，或持续在 TCP 连接上发送消息。
操作 1.14、1.15、1.16

如果您在设置 expirationSeconds 的情况下创建 CertificateSigningRequest (CSR)，则 expirationSeconds 会被忽略。

临时解决方法：

如果您受到此问题的影响，则可以通过在用户集群配置文件中添加 disableNodeIDVerificationCSRSigning: true 来更新用户集群，并运行 gkectl update cluster 命令以使用此配置更新集群。
网络、升级、更新 1.16.0-1.16.3

如果您尝试为现有集群停用捆绑式入站流量，则 gkectl update cluster 命令会失败，并显示类似于以下示例的错误：

[FAILURE] Config: ingress IP is required in user cluster spec

发生此错误是因为 gkectl 在预检检查期间检查负载均衡器入站流量 IP 地址。虽然停用捆绑式入站流量时不需要进行此检查，但当 disableBundledIngress 设置为 true 时，gkectl 预检检查会失败。


临时解决方法：

请在更新集群时使用 --skip-validation-load-balancer 参数，如以下示例所示：

gkectl update cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG  \
  --skip-validation-load-balancer

如需了解详情，请参阅如何为现有集群停用捆绑式入站流量。
升级、更新 1.13、1.14、1.15.0-1.15.6

如果您轮替管理员集群证书授权机构 (CA) 证书，则后续尝试运行 gkectl update admin 命令会失败。返回的错误类似于以下内容：

failed to get last CARotationStage: configmaps "ca-rotation-stage" not found

临时解决方法：

如果您受到此问题的影响，则可以通过在 gkectl update admin 命令中使用 --disable-update-from-checkpoint 标志来更新管理员集群：

gkectl update admin --config ADMIN_CONFIG_file \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --disable-update-from-checkpoint

使用 --disable-update-from-checkpoint 标志时，在集群更新期间，更新命令不会将检查点文件用作可靠来源。检查点文件仍会更新以供将来使用。
存储 1.15.0-1.15.6、1.16.0-1.16.2

在预检检查期间，CSI 工作负载验证检查会在 default 命名空间中安装一个 Pod。CSI Workload Pod 会验证 vSphere CSI 驱动程序已安装，并且可以执行动态卷预配。如果此 Pod 未启动，则 CSI 工作负载验证检查将失败。

以下是可能导致此 Pod 无法启动的一些已知问题：

  • 如果 Pod 未指定资源限制（某些安装了准入 webhook 的集群就是如此），则 Pod 不会启动。
  • 如果 Cloud Service Mesh 安装在 default 命名空间中启用了自动 Istio 边车代理注入功能的集群中，则 CSI 工作负载 Pod 不会启动。

如果 CSI 工作负载 Pod 未启动，您会在预检验证期间看到如下超时错误：

- [FAILURE] CSI Workload: failure in CSIWorkload validation: failed to create writer Job to verify the write functionality using CSI: Job default/anthos-csi-workload-writer-<run-id> replicas are not in Succeeded phase: timed out waiting for the condition

如需查看失败是否是由于缺少 Pod 资源限制设置引起的，请运行以下命令检查 anthos-csi-workload-writer-<run-id> 作业状态：

kubectl describe job anthos-csi-workload-writer-<run-id>

如果未正确为 CSI 工作负载 Pod 设置资源限制，则作业状态会包含如下错误消息：

CPU and memory resource limits is invalid, as it are not defined for container: volume-tester

如果 CSI 工作负载 Pod 因 Istio 边车代理注入而无法启动，您可以在 default 命名空间中暂时停用自动 Istio 边车代理注入功能。请检查命名空间的标签，并使用以下命令删除以 istio.io/rev 开头的标签：

kubectl label namespace default istio.io/rev-

如果 Pod 配置错误，请手动验证使用 vSphere CSI 驱动程序的动态卷预配有效：

  1. 创建使用 standard-rwo StorageClass 的 PVC。
  2. 创建使用 PVC 的 Pod。
  3. 验证 Pod 可以对卷进行数据读取/写入。
  4. 验证运行正常后，移除 Pod 和 PVC。

如果使用 vSphere CSI 驱动程序的动态卷预配有效，请运行带有 --skip-validation-csi-workload 标志的 gkectl diagnose 或 gkectl upgrade 以跳过 CSI 工作负载检查。
操作 1.16.0-1.16.2

当您登录用户管理的管理员工作站时，gkectl update cluster 命令可能会超时并且无法更新用户集群。如果管理员集群版本为 1.15，并且您在运行 gkectl update cluster 之前运行了 gkectl update admin，会发生这种情况。 发生此问题时，您在尝试更新集群时会看到以下错误： 

      Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition
Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition

在更新 1.15 版管理员集群期间，触发预检检查的 validation-controller 从集群中移除。如果您随后尝试更新用户集群，预检检查会挂起，直到达到超时时间。

临时解决方法：

  1. 运行以下命令以重新部署 validation-controller： 
          gkectl prepare --kubeconfig ADMIN_KUBECONFIG --bundle-path BUNDLE_PATH --upgrade-platform
  2. 准备完成后，再次运行 gkectl update cluster 以更新用户集群
操作 1.16.0-1.16.2

当您登录用户管理的管理员工作站时，gkectl create cluster 命令可能会超时并且无法创建用户集群。当管理员集群版本为 1.15 时会发生这种情况。发生此问题时，您在尝试创建集群时会看到以下错误： 

      Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition
Preflight check failed with failed to run server-side preflight checks: server-side preflight checks failed: timed out waiting for the condition

由于 validation-controller 是在 1.16 中添加的，因此在使用 1.15 管理员集群时，缺少负责触发预检检查的 validation-controller。因此，在尝试创建用户集群时，预检检查会挂起，直至达到超时时间。

临时解决方法：

  1. 运行以下命令以部署 validation-controller： 
          gkectl prepare --kubeconfig ADMIN_KUBECONFIG --bundle-path BUNDLE_PATH --upgrade-platform
  2. 准备完成后，再次运行 gkectl create cluster 以创建用户集群
升级、更新 1.16.0-1.16.2

将管理员集群从 1.15.x 版升级到 1.16.x 版时，或者在更新管理员集群时添加 connect、stackdriver、cloudAuditLogging 或 gkeOnPremAPI 配置，操作可能会被管理员集群 webhook 拒绝。系统可能会显示以下错误消息之一：

  • "projects for connect, stackdriver and cloudAuditLogging must be the same when specified during cluster creation."
  • "locations for connect, gkeOnPremAPI, stackdriver and cloudAuditLogging must be in the same region when specified during cluster creation."
  • "locations for stackdriver and cloudAuditLogging must be the same when specified during cluster creation."

管理员集群更新或升级需要 onprem-admin-cluster-controller 来协调 kind 集群中的管理员集群。在 kind 集群中恢复管理员集群状态时，管理员集群 webhook 无法区分 OnPremAdminCluster 对象是用于创建管理员集群，还是用于恢复更新或升级操作。在意外更新和升级时，系统会调用一些仅限创建的验证。


临时解决方法：

向 OnPremAdminCluster 对象添加 onprem.cluster.gke.io/skip-project-location-sameness-validation: true 注解：

  1. 修改 onpremadminclusters 集群资源： 
    kubectl edit onpremadminclusters ADMIN_CLUSTER_NAME -n kube-system –kubeconfig ADMIN_CLUSTER_KUBECONFIG
     替换以下内容：
    • ADMIN_CLUSTER_NAME：管理员集群的名称。
    • ADMIN_CLUSTER_KUBECONFIG：管理员集群 kubeconfig 文件的路径。
  2. 添加 onprem.cluster.gke.io/skip-project-location-sameness-validation: true 注解并保存自定义资源。
  3. 根据管理员集群的类型，完成以下步骤之一：
    • 对于具有检查点文件的非 HA 管理员集群：在更新命令中添加参数 disable-update-from-checkpoint，或在升级命令中添加参数“disable-upgrade-from-checkpoint”。只有在下次运行 update 或 upgrade 命令时才需要这些参数：
      • gkectl update admin --config ADMIN_CONFIG_file --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --disable-update-from-checkpoint
      • gkectl upgrade admin --config ADMIN_CONFIG_file --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --disable-upgrade-from-checkpoint
    • 对于 HA 管理员集群或检查点文件已停用：照常更新或升级管理员集群。更新或升级命令不需要额外参数。
操作 1.16.0-1.16.2

当您登录用户管理的管理员工作站时，gkectl delete cluster 命令可能会超时并且无法删除用户集群。如果您首次在用户管理的工作站上运行 gkectl 以创建、更新或升级用户集群，则会发生这种情况。发生此问题时，您在尝试删除集群时会看到以下错误： 

      failed to wait for user cluster management namespace "USER_CLUSTER_NAME-gke-onprem-mgmt"
      to be deleted: timed out waiting for the condition

在删除期间，集群首先会删除其所有对象。Validation 对象（在创建、更新或升级期间创建）的删除过程卡在删除阶段。这是因为终结器会阻止对象的删除，从而导致集群删除失败。

临时解决方法：

  1. 获取所有 Validation 对象的名称： 
             kubectl  --kubeconfig ADMIN_KUBECONFIG get validations \
           -n USER_CLUSTER_NAME-gke-onprem-mgmt
  2. 对于每个 Validation 对象，运行以下命令以从 Validation 对象中移除终结器： 
          kubectl --kubeconfig ADMIN_KUBECONFIG patch validation/VALIDATION_OBJECT_NAME \
        -n USER_CLUSTER_NAME-gke-onprem-mgmt -p '{"metadata":{"finalizers":[]}}' --type=merge

    从所有 Validation 对象中移除终结器后，这些对象会被移除，并且用户集群删除操作会自动完成。您无需采取额外行动。
网络 1.15、1.16

如果来源 Pod 和出站流量 NAT 网关 Pod 位于两个不同的工作器节点上，则来自来源 Pod 的流量无法访问任何外部服务。如果 Pod 位于同一主机上，则与外部服务或应用的连接会成功。

此问题是由于在启用隧道聚合时 vSphere 丢弃 VXLAN 数据包导致的。NSX 和 VMware 存在一个已知问题，即仅在已知 VXLAN 端口 (4789) 上发送聚合流量。


临时解决方法：

将 Cilium 使用的 VXLAN 端口更改为 4789：

  1. 修改 cilium-config ConfigMap： 
    kubectl edit cm -n kube-system cilium-config --kubeconfig USER_CLUSTER_KUBECONFIG
  2. 将以下内容添加到 cilium-config ConfigMap： 
    tunnel-port: 4789
  3. 重启 anetd DaemonSet： 
    kubectl rollout restart ds anetd -n kube-system --kubeconfig USER_CLUSTER_KUBECONFIG

每次升级集群时，此解决方法都会还原。每次升级后，您都必须重新配置。VMware 必须解决其在 vSphere 中的问题并提供永久性修复措施。
升级 1.15.0-1.15.4

由于控制器生成的加密密钥与管理员主数据磁盘上保存的密钥不匹配，启用了始终开启的 Secret 加密的管理员集群在从 1.14.x 升级到 1.15.x 时失败。gkectl upgrade admin 的输出包含以下错误消息：

      E0926 14:42:21.796444   40110 console.go:93] Exit with error:
      E0926 14:42:21.796491   40110 console.go:93] Failed to upgrade the admin cluster: failed to create admin cluster: failed to wait for OnPremAdminCluster "admin-cluster-name" to become ready: failed to wait for OnPremAdminCluster "admin-cluster-name" to be ready: error: timed out waiting for the condition, message: failed to wait for OnPremAdminCluster "admin-cluster-name" to stay in ready status for duration "2m0s": OnPremAdminCluster "non-prod-admin" is not ready: ready condition is not true: CreateOrUpdateControlPlane: Creating or updating credentials for cluster control plane

运行 kubectl get secrets -A --kubeconfig KUBECONFIG` 失败，并显示以下错误：

      Internal error occurred: unable to transform key "/registry/secrets/anthos-identity-service/ais-secret": rpc error: code = Internal desc = failed to decrypt: unknown jwk

临时解决方法

如果您有管理员集群的备份，请执行以下步骤以暂时解决升级失败的问题：

  1. 在管理员集群配置文件中停用 secretsEncryption，并使用以下命令更新集群： 
    gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG
  2. 创建新的管理员主虚拟机后，通过 SSH 连接到管理员主虚拟机，并将数据磁盘上的新密钥替换为备份中的旧密钥。密钥位于管理员主虚拟机的 /opt/data/gke-k8s-kms-plugin/generatedkeys 中。
  3. 更新 /etc/kubernetes/manifests 中的 kms-plugin.yaml 静态 Pod 清单来更新 --kek-id，以匹配原始加密密钥中的 kid 字段。
  4. 将 /etc/kubernetes/manifests/kms-plugin.yaml 移动到另一个目录，以重启 kms-plugin 静态 Pod，然后再将它移回来。
  5. 再次运行 gkectl upgrade admin 来恢复管理员升级。

防止升级失败

如果您尚未升级，我们建议您不要升级到 1.15.0-1.15.4。如果您必须升级到受影响的版本，请在升级管理员集群之前执行以下步骤：

  1. 备份管理员集群。
  2. 在管理员集群配置文件中停用 secretsEncryption，并使用以下命令更新集群： 
    gkectl update admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG
  3. 升级管理员集群。
  4. 重新启用始终开启的 Secret 加密。
存储 1.11-1.16

Google Distributed Cloud 不支持磁盘上的更改块跟踪 (CBT)。某些备份软件使用 CBT 功能跟踪磁盘状态并执行备份，这会导致磁盘无法连接到运行 Google Distributed Cloud 的虚拟机。如需了解详情，请参阅 VMware 知识库文章。


临时解决方法：

请勿备份 Google Distributed Cloud 虚拟机，因为第三方备份软件可能会导致在其磁盘上启用 CBT。您无需备份这些虚拟机。

请勿在节点上启用 CBT，因为此更改在更新或升级后不会保留。

如果您已有启用了 CBT 的磁盘，请按照 VMware 知识库文章中的解决方法步骤，在 First Class Disk 上停用 CBT。
存储 1.14、1.15、1.16

如果您使用 Nutanix 存储阵列向主机提供 NFSv3 共享，则可能会遇到数据损坏或 Pod 无法成功运行的情况。此问题是由某些 VMware 版本和 Nutanix 版本之间的已知兼容性问题引起的。如需了解详情，请参阅相关的 VMware 知识库文章。


临时解决方法：

VMware KB 文章已过时，因为它未指出当前没有解决办法。如需解决此问题，请在主机上更新到最新版 ESXi，并在存储阵列上更新到最新版 Nutanix。
操作系统 1.13.10、1.14.6、1.15.3

对于某些 Google Distributed Cloud 版本，在节点上运行的 kubelet 使用的版本与 Kubernetes 控制平面不同。由于操作系统映像上预加载的 kubelet 二进制文件使用的是不同的版本，因此会出现不匹配的情况。

下表列出了已发现的版本不匹配：

Google Distributed Cloud 版本 kubelet 版本 Kubernetes 版本
1.13.10 v1.24.11-gke.1200 v1.24.14-gke.2100
1.14.6 v1.25.8-gke.1500 v1.25.10-gke.1200
1.15.3 v1.26.2-gke.1001 v1.26.5-gke.2100

临时解决方法：

对此，您无需执行任何操作。 仅在 Kubernetes 补丁版本之间不一致，此版本偏差尚未引起任何问题。
升级、更新 1.15.0-1.15.4

当管理员集群的证书授权机构 (CA) 版本大于 1 时，由于 webhook 中的 CA 版本验证，集群更新或升级会失败。gkectl 升级/更新的输出包含以下错误消息： 

    CAVersion must start from 1

临时解决方法：

  • 缩减管理员集群中的 auto-resize-controller 部署以停用自动调整节点大小的功能。这是必要的操作，因为 1.15 中引入的管理员集群自定义资源的新字段可能会导致 auto-resize-controller 中出现 nil 指针错误。 
     kubectl scale deployment auto-resize-controller -n kube-system --replicas=0 --kubeconfig KUBECONFIG
  • 运行带有 --disable-admin-cluster-webhook 标志的 gkectl 命令。例如：
            gkectl upgrade admin --config ADMIN_CLUSTER_CONFIG_FILE --kubeconfig KUBECONFIG --disable-admin-cluster-webhook
操作 1.13、1.14.0-1.14.8、1.15.0-1.15.4、1.16.0-1.16.1

删除非 HA Controlplane V2 集群时，它会在节点删除时卡住，直至超时。

临时解决方法：

如果集群包含具有关键数据的 StatefulSet，请与 Cloud Customer Care 团队联系以解决此问题。

否则，请执行以下步骤：

  • 从 vSphere 中删除所有集群虚拟机。您可以通过 vSphere 界面删除虚拟机，也可以运行以下命令： 
          govc vm.destroy
    。
  • 再次强制删除集群： 
         gkectl delete cluster --cluster USER_CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG --force

存储 1.15.0+、1.16.0+

如果集群包含树内 vSphere 永久性卷（例如使用 standard StorageClass 创建的 PVC），您将观察到从 vCenter 每分钟触发 com.vmware.cns.tasks.attachvolume 任务的现象。


临时解决方法：

修改 vSphere CSI 功能 configMap 并将 list-volumes 设置为 false：

     kubectl edit configmap internal-feature-states.csi.vsphere.vmware.com -n kube-system --kubeconfig KUBECONFIG

重启 vSphere CSI 控制器 Pod：

     kubectl rollout restart deployment vsphere-csi-controller -n kube-system --kubeconfig KUBECONFIG
存储 1.16.0

如果集群包含树内 vSphere 永久性卷，gkectl diagnose 和 gkectl upgrade 命令可能会在验证集群存储设置时针对其永久性卷声明 (PVC) 发出误报的警告。警告消息如下所示：

    CSIPrerequisites pvc/pvc-name: PersistentVolumeClaim pvc-name bounds to an in-tree vSphere volume created before CSI migration enabled, but it doesn't have the annotation pv.kubernetes.io/migrated-to set to csi.vsphere.vmware.com after CSI migration is enabled

临时解决方法：

运行以下命令以检查具有上述警告的 PVC 的注解：

    kubectl get pvc PVC_NAME -n PVC_NAMESPACE -oyaml --kubeconfig KUBECONFIG

如果输出中的 annotations 字段包含以下内容，您可以放心地忽略该警告：

      pv.kubernetes.io/bind-completed: "yes"
      pv.kubernetes.io/bound-by-controller: "yes"
      volume.beta.kubernetes.io/storage-provisioner: csi.vsphere.vmware.com
升级、更新 1.15.0+、1.16.0+

如果您的集群未使用私有仓库，并且您的组件访问服务账号密钥和 Logging-monitoring（或 Connect-register）服务账号密钥已过期，则在您轮替服务账号密钥时，gkectl update credentials 会失败并显示类似于以下内容的错误：

Error: reconciliation failed: failed to update platform: ...

临时解决方法：

首先，轮替组件访问服务账号密钥。虽然会显示相同的错误消息，但您应该能够在组件访问服务账号密钥轮替后轮替其他密钥。

如果更新仍然没有成功，请与 Cloud Customer Care 团队联系以解决此问题。
升级 1.16.0-1.16.5

在用户集群升级期间，当用户集群控制器升级到 1.16 后，如果同一管理员集群还管理着其他 1.15 版用户集群，则其用户主机器可能会意外重新创建。

1.16 用户集群控制器中存在一个 bug，会触发 1.15 用户主机器重新创建。

具体的解决方法取决于您遇到此问题的方式。

使用 Google Cloud 控制台升级用户集群时的解决方法：

方法 1：使用包含修复的 1.16.6+ 版 GKE on VMware。

方法 2：执行以下步骤：

  1. 使用以下命令手动添加重新运行注解： 
    kubectl edit onpremuserclusters USER_CLUSTER_NAME -n USER_CLUSTER_NAME-gke-onprem-mgmt --kubeconfig ADMIN_KUBECONFIG

    重新运行注解为：

    onprem.cluster.gke.io/server-side-preflight-rerun: true
  2. 通过检查 OnPremUserCluster 的 status 字段来监控升级进度。

使用您自己的管理员工作站升级用户集群时的解决方法：

方法 1：使用包含修复的 1.16.6+ 版 GKE on VMware。

方法 2：执行以下步骤：

  1. 添加包含以下内容的构建信息文件 /etc/cloud/build.info。这会导致预检检查在管理员工作站（而不是服务器）上本地运行。 
    gke_on_prem_version: GKE_ON_PREM_VERSION
     例如： 
    gke_on_prem_version: 1.16.0-gke.669
  2. 重新运行升级命令。
  3. 升级完成后，删除 build.info 文件。
创建 1.16.0-1.16.5、1.28.0-1.28.100

在创建集群期间，如果您没有为 IP 块文件中的每个 IP 地址指定主机名，则预检检查会失败，并显示以下错误消息： 

multiple VMs found by DNS name  in xxx datacenter. Anthos Onprem doesn't support duplicate hostname in the same vCenter and you may want to rename/delete the existing VM.`

预检检查存在一个 bug，它认为空主机名是重复的。

临时解决方法：

方法 1：使用包含修复的版本。

方法 2：通过添加 --skip-validation-net-config 标志绕过此预检检查。

方法 3：为 IP 地址块文件中的每个 IP 地址指定唯一主机名。
升级、更新 1.16

对于非 HA 管理员集群和控制平面 v1 用户集群，当您升级或更新管理员集群时，管理员集群主机器重新创建可能会与用户集群主机器重新启动同时进行，这可能形成竞态条件。这会导致用户集群控制平面 Pod 无法与管理员集群控制平面通信，从而导致用户集群控制平面上的 kube-etcd 和 kube-apiserver 的卷挂接问题。

如需验证问题，请对受影响的 Pod 运行以下命令：

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace USER_CLUSTER_NAME describe pod IMPACTED_POD_NAME
 您将看到如下事件： 
Events:
  Type     Reason       Age                  From               Message
  ----     ------       ----                 ----               -------
  Warning  FailedMount  101s                 kubelet            Unable to attach or mount volumes: unmounted volumes=[kube-audit], unattached volumes=[], failed to process volumes=[]: timed out waiting for the condition
  Warning  FailedMount  86s (x2 over 3m28s)  kubelet            MountVolume.SetUp failed for volume "pvc-77cd0635-57c2-4392-b191-463a45c503cb" : rpc error: code = FailedPrecondition desc = volume ID: "bd313c62-d29b-4ecd-aeda-216648b0f7dc" does not appear staged to "/var/lib/kubelet/plugins/kubernetes.io/csi/csi.vsphere.vmware.com/92435c96eca83817e70ceb8ab994707257059734826fedf0c0228db6a1929024/globalmount"

临时解决方法：

  1. 通过 SSH 连接到用户控制平面节点，因为它是控制平面 v1 用户集群，因此用户控制平面节点在管理员集群中。
  2. 使用以下命令重启 kubelet： 
        sudo systemctl restart kubelet
    重启后，kubelet 可以正确重建阶段全局装载。
升级、更新 1.16.0

在升级或更新管理员集群期间，竞态条件可能会导致 vSphere 云控制器管理器意外删除新的控制平面节点。这会导致 clusterapi-controller 在等待节点创建时卡住，最终导致升级/更新超时。在这种情况下，gkectl 升级/更新命令的输出类似于以下内容：

    controlplane 'default/gke-admin-hfzdg' is not ready: condition "Ready": condition is not ready with reason "MachineInitializing", message "Wait for the control plane machine "gke-admin-hfzdg-6598459f9zb647c8-0\" to be rebooted"...

如需识别此问题，请运行以下命令，在管理员集群中登录 vSphere 云控制器管理器：

    kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
    kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n kube-system

以下是来自上述命令的示例错误消息：

    node name: 81ff17e25ec6-qual-335-1500f723 has a different uuid. Skip deleting this node from cache.

临时解决方法：

  1. 重新启动失败的机器以重新创建已删除的节点对象。
  2. 通过 SSH 连接到每个控制平面节点，并重启 vSphere 云控制器管理器静态 Pod： 
          sudo crictl ps | grep vsphere-cloud-controller-manager | awk '{print $1}'
      sudo crictl stop PREVIOUS_COMMAND_OUTPUT
  3. 重新运行升级/更新命令。
操作 1.16

如果同一数据中心内存在重复的主机名，则使用静态 IP 升级 1.15 集群或创建 1.16 集群会失败。发生此故障的原因是 vSphere 云控制器管理器无法在节点对象中添加外部 IP 和提供方 ID。这会导致集群升级/创建超时。

如需识别此问题，请获取集群的 vSphere 云控制器管理器 Pod 日志。您使用的命令取决于集群类型，如下所示：

  • 管理员集群： 
          kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n kube-system
  • 用户集群 (kubeception)： 
          kubectl get pods --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAME | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAME
  • 用户集群：(Controlplane V2)： 
          kubectl get pods --kubeconfig USER_KUBECONFIG -n kube-system | grep vsphere-cloud-controller-manager
      kubectl logs -f vsphere-cloud-controller-manager-POD_NAME_SUFFIX --kubeconfig USER_KUBECONFIG -n kube-system

以下是错误消息示例：

    I1003 17:17:46.769676       1 search.go:152] Finding node admin-vm-2 in vc=vcsa-53598.e5c235a1.asia-northeast1.gve.goog and datacenter=Datacenter
    E1003 17:17:46.771717       1 datacenter.go:111] Multiple vms found VM by DNS Name. DNS Name: admin-vm-2

检查数据中心内是否有重复的主机名：

您可以使用以下方法检查主机名是否重复，并在需要时执行解决方法。 
          export GOVC_DATACENTER=GOVC_DATACENTER
          export GOVC_URL=GOVC_URL
          export GOVC_USERNAME=GOVC_USERNAME
          export GOVC_PASSWORD=GOVC_PASSWORD
          export GOVC_INSECURE=true
          govc find . -type m -guest.hostName HOSTNAME
命令和输出示例： 
          export GOVC_DATACENTER=mtv-lifecycle-vc01
          export GOVC_URL=https://mtv-lifecycle-vc01.anthos/sdk
          export GOVC_USERNAME=xxx
          export GOVC_PASSWORD=yyy
          export GOVC_INSECURE=true
          govc find . -type m -guest.hostName f8c3cd333432-lifecycle-337-xxxxxxxz
          ./vm/gke-admin-node-6b7788cd76-wkt8g
          ./vm/gke-admin-node-6b7788cd76-99sg2
          ./vm/gke-admin-master-5m2jb

具体的解决方法取决于失败的操作。

升级的解决方法：

执行适用的集群类型的解决方法。

  • 用户集群：
    1. 将 user-ip-block.yaml 中受影响机器的主机名更新为唯一名称并触发强制更新：
                gkectl update cluster --kubeconfig ADMIN_KUBECONFIG --config NEW_USER_CLUSTER_CONFIG --force
    2. 重新运行 gkectl upgrade cluster
  • 管理员集群：
    1. 将 admin-ip-block.yaml 中受影响机器的主机名更新为唯一名称并触发强制更新：
                gkectl update admin --kubeconfig ADMIN_KUBECONFIG --config NEW_ADMIN_CLUSTER_CONFIG --force --skip-cluster-ready-check
    2. 如果是非 HA 管理员集群，并且您发现管理员主虚拟机使用重复的主机名，则还需要：
      获取管理员主机器名称 
                kubectl get machine --kubeconfig ADMIN_KUBECONFIG -owide -A
      更新管理员主机器对象
      注意：NEW_ADMIN_MASTER_HOSTNAME 应与您在第 1 步中在 admin-ip-block.yaml 中所设置的相同。
                kubectl patch machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG --type='json' -p '[{"op": "replace", "path": "/spec/providerSpec/value/networkSpec/address/hostname", "value":"NEW_ADMIN_MASTER_HOSTNAME"}]'
      验证管理员主机器对象中的主机名已更新：
                kubectl get machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG -oyaml
          kubectl get machine ADMIN_MASTER_MACHINE_NAME --kubeconfig ADMIN_KUBECONFIG -o jsonpath='{.spec.providerSpec.value.networkSpec.address.hostname}'
    3. 在停用检查点的情况下重新运行管理员集群升级：
                gkectl upgrade admin --kubeconfig ADMIN_KUBECONFIG --config ADMIN_CLUSTER_CONFIG --disable-upgrade-from-checkpoint

安装的解决方法：

执行适用的集群类型的解决方法。
操作 1.16.0、1.16.1、1.16.2、1.16.3

当 vSphere 用户名或密码包含 $ 或 ` 时，以下操作会失败：

  • 将启用了 Controlplane V2 的 1.15 用户集群升级到 1.16
  • 将 1.15 高可用性 (HA) 管理员集群升级到 1.16
  • 创建启用 Controlplane V2 的 1.16 版用户集群
  • 创建 1.16 HA 管理员集群

使用包含修复的 1.16.4+ 版本 Google Distributed Cloud，或执行以下临时解决方法。具体的解决方法取决于失败的操作。

升级的解决方法：

  1. 在 vCenter 端更改 vCenter 用户名或密码，以移除 $ 和 `。
  2. 更新凭据配置文件中的 vCenter 用户名或密码。
  3. 触发集群的强制更新。
    • 用户集群： 
              gkectl update cluster --kubeconfig ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG --force
    • 管理员集群： 
              gkectl update admin --kubeconfig ADMIN_KUBECONFIG --config ADMIN_CLUSTER_CONFIG --force --skip-cluster-ready-check

安装的解决方法：

  1. 在 vCenter 端更改 vCenter 用户名或密码，以移除 $ 和 `。
  2. 更新凭据配置文件中的 vCenter 用户名或密码。
  3. 执行适用的集群类型的解决方法。
存储 1.11+、1.12+、1.13+、1.14+、1.15+、1.16

删除节点然后使用相同的节点名称重新创建节点后，有很微小的可能，后续 PersistentVolumeClaim (PVC) 创建会失败，并显示如下错误：

    The object 'vim.VirtualMachine:vm-988369' has already been deleted or has not been completely created

这是由于竞态条件（即 vSphere CSI 控制器不从其缓存中删除已移除的机器）引起的。


临时解决方法：

重启 vSphere CSI 控制器 Pod：

    kubectl rollout restart deployment vsphere-csi-controller -n kube-system --kubeconfig KUBECONFIG
操作 1.16.0

在高可用性管理员集群上运行 gkectl repair admin-master 命令时，gkectl 会返回以下错误消息： 

  Exit with error: Failed to repair: failed to select the template: failed to get cluster name from kubeconfig, please contact Google support. failed to decode kubeconfig data: yaml: unmarshal errors:
    line 3: cannot unmarshal !!seq into map[string]*api.Cluster
    line 8: cannot unmarshal !!seq into map[string]*api.Context

临时解决方法：

在命令中添加 --admin-master-vm-template= 标志，并提供要修复的机器的虚拟机模板： 

  gkectl repair admin-master --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
      --config ADMIN_CLUSTER_CONFIG_FILE \
      --admin-master-vm-template=/DATA_CENTER/vm/VM_TEMPLATE_NAME

如需查找机器的虚拟机模板，请执行以下操作：

  1. 进入 vSphere 客户端中的 Hosts and Clusters（主机和集群）页面。
  2. 点击 VM Templates（虚拟机模板），然后按管理员集群名称过滤。

    您应该会看到管理员集群的三个虚拟机模板。

  3. 复制与要修复的机器名称匹配的虚拟机模板名称，并在修复命令中使用该模板名称。
  gkectl repair admin-master \
      --config=/home/ubuntu/admin-cluster.yaml \
      --kubeconfig=/home/ubuntu/kubeconfig \
      --admin-master-vm-template=/atl-qual-vc07/vm/gke-admin-98g94-zx...7vx-0-tmpl
网络 1.10.0+、1.11.0+、1.12.0+、1.13.0+、1.14.0-1.14.7、1.15.0-1.15.3、1.16.0

如果您使用 Seesaw 作为集群的负载均衡器类型，并且发现 Seesaw 虚拟机已关停或无法启动，则可能会在 vSphere 控制台中看到以下错误消息：

    GRUB_FORCE_PARTUUID set, initrdless boot failed. Attempting with initrd

此错误表示虚拟机上的磁盘空间不足，因为在 Seesaw 虚拟机上运行的 fluent-bit 未配置正确的日志轮换。


临时解决方法：

通过 du -sh -- /var/lib/docker/containers/* | sort -rh 找到占用大部分磁盘空间的日志文件。清理大小最大的日志文件，然后重新启动虚拟机。

注意：如果虚拟机完全无法访问，请将磁盘挂接到正常运行的虚拟机（例如管理员工作站），从挂接的磁盘中删除文件，然后将磁盘重新挂接到原来的 Seesaw 虚拟机。

为防止问题再次发生，请连接到虚拟机并修改 /etc/systemd/system/docker.fluent-bit.service 文件。在 Docker 命令中添加 --log-opt max-size=10m --log-opt max-file=5，然后运行 systemctl restart docker.fluent-bit.service
操作 1.13、1.14.0-1.14.6、1.15

如果您尝试升级 (gkectl upgrade admin) 或更新 (gkectl update admin) 启用了检查点的非高可用性管理员集群，升级或更新可能会失败，并显示如下错误： 

Checking admin cluster certificates...FAILURE
    Reason: 20 admin cluster certificates error(s).
Unhealthy Resources:
    AdminMaster clusterCA bundle: failed to get clusterCA bundle on admin master, command [ssh -o IdentitiesOnly=yes -i admin-ssh-key -o StrictHostKeyChecking=no -o ConnectTimeout=30 ubuntu@AdminMasterIP -- sudo cat /etc/kubernetes/pki/ca-bundle.crt] failed with error: exit status 255, stderr: Authorized uses only. All activity may be monitored and reported.
    ubuntu@AdminMasterIP: Permission denied (publickey).
 
failed to ssh AdminMasterIP, failed with error: exit status 255, stderr: Authorized uses only. All activity may be monitored and reported.
    ubuntu@AdminMasterIP: Permission denied (publickey)
 
error dialing ubuntu@AdminMasterIP: failed to establish an authenticated SSH connection: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey]...


临时解决方法：

如果您无法升级到包含修复的 Google Distributed Cloud 补丁版本，请与 Google 支持团队联系以获取帮助。
升级 1.13.0-1.13.9、1.14.0-1.14.6、1.15.1-1.15.2

当管理员集群在 GKE On-Prem API 中注册时，由于舰队成员资格无法更新，因此将管理员集群升级到受影响的版本可能会失败。发生此问题时，您在尝试升级集群时会看到以下错误：

    failed to register cluster: failed to apply Hub Membership: Membership API request failed: rpc error: code = InvalidArgument desc = InvalidFieldError for field endpoint.on_prem_cluster.resource_link: field cannot be updated

当您明确注册集群，或者使用 GKE On-Prem API 客户端升级用户集群时，管理员集群会注册到 API 中。


临时解决方法：

取消注册管理员集群： 
    gcloud alpha container vmware admin-clusters unenroll ADMIN_CLUSTER_NAME --project CLUSTER_PROJECT --location=CLUSTER_LOCATION --allow-missing
并恢复升级管理员集群。您可能会暂时看到过时的“无法注册集群”错误。一段时间后，它应该会自动更新。
升级、更新 1.13.0-1.13.9、1.14.0-1.14.4、1.15.0

在 GKE On-Prem API 中注册管理员集群时，其资源链接注解会应用于 OnPremAdminCluster 自定义资源，但由于使用的注解键有误，在之后的管理员集群升级中，该资源链接注解未被保留。这可能会导致管理员集群错误地再次在 GKE On-Prem API 中注册。

当您明确注册集群，或者使用 GKE On-Prem API 客户端升级用户集群时，管理员集群会注册到 API 中。


临时解决方法：

取消注册管理员集群： 
    gcloud alpha container vmware admin-clusters unenroll ADMIN_CLUSTER_NAME --project CLUSTER_PROJECT --location=CLUSTER_LOCATION --allow-missing
并再次重新注册管理员集群。
网络 1.15.0-1.15.2

OrderPolicy 未被识别为参数，因此未被使用。因此，Google Distributed Cloud 始终使用 Random。

出现此问题是因为 CoreDNS 模板未更新，导致 orderPolicy 被忽略。


临时解决方法：

更新 CoreDNS 模板并应用修复。该修复在升级之前一直有效。

  1. 修改现有模板： 
    kubectl edit cm -n kube-system coredns-template
     将模板的内容替换为以下内容： 
    coredns-template: |-
  .:53 {
    errors
    health {
      lameduck 5s
    }
    ready
    kubernetes cluster.local in-addr.arpa ip6.arpa {
      pods insecure
      fallthrough in-addr.arpa ip6.arpa
    }
{{- if .PrivateGoogleAccess }}
    import zones/private.Corefile
{{- end }}
{{- if .RestrictedGoogleAccess }}
    import zones/restricted.Corefile
{{- end }}
    prometheus :9153
    forward . {{ .UpstreamNameservers }} {
      max_concurrent 1000
      {{- if ne .OrderPolicy "" }}
      policy {{ .OrderPolicy }}
      {{- end }}
    }
    cache 30
{{- if .DefaultDomainQueryLogging }}
    log
{{- end }}
    loop
    reload
    loadbalance
}{{ range $i, $stubdomain := .StubDomains }}
{{ $stubdomain.Domain }}:53 {
  errors
{{- if $stubdomain.QueryLogging }}
  log
{{- end }}
  cache 30
  forward . {{ $stubdomain.Nameservers }} {
    max_concurrent 1000
    {{- if ne $.OrderPolicy "" }}
    policy {{ $.OrderPolicy }}
    {{- end }}
  }
}
{{- end }}
升级、更新 1.10、1.11、1.12、1.13.0-1.13.7、1.14.0-1.14.3

某些竞态条件可能会导致检查点与实际 CR 之间的 OnPremAdminCluster 状态不一致。发生此问题时，您在升级管理员集群后对其进行更新时可能会遇到以下错误：

Exit with error:
E0321 10:20:53.515562  961695 console.go:93] Failed to update the admin cluster: OnPremAdminCluster "gke-admin-rj8jr" is in the middle of a create/upgrade ("" -> "1.15.0-gke.123"), which must be completed before it can be updated
Failed to update the admin cluster: OnPremAdminCluster "gke-admin-rj8jr" is in the middle of a create/upgrade ("" -> "1.15.0-gke.123"), which must be completed before it can be updated
 如需解决此问题，您需要修改检查点或停用检查点以进行升级/更新，请与我们的支持团队联系，以继续解决此问题。
操作 1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

Google Distributed Cloud 会在每次协调过程中更改管理员集群控制平面上的管理员证书，例如在集群升级期间。此行为提高了为管理员集群获取无效证书的可能性，尤其是对于 1.15 版集群。

如果您受到此问题的影响，则可能会遇到如下问题：

  • 无效证书可能会导致以下命令超时并返回错误：
    • gkectl create admin
    • gkectl upgrade amdin
    • gkectl update admin

    这些命令可能会返回如下所示的授权错误：

    Failed to reconcile admin cluster: unable to populate admin clients: failed to get admin controller runtime client: Unauthorized
  • 管理员集群的 kube-apiserver 日志可能包含如下错误： 
    Unable to authenticate the request" err="[x509: certificate has expired or is not yet valid...

临时解决方法：

升级到包含修复的 Google Distributed Cloud 版本：1.13.10+、1.14.6+、1.15.2+。如果升级不可行，请与 Cloud Customer Care 团队联系以解决此问题。
网络、操作 1.10、1.11、1.12、1.13、1.14

kube-system 中的网络网关 Pod 可能会显示 Pending 或 Evicted 状态，如以下精简示例输出所示：

$ kubectl -n kube-system get pods | grep ang-node
ang-node-bjkkc     2/2     Running     0     5d2h
ang-node-mw8cq     0/2     Evicted     0     6m5s
ang-node-zsmq7     0/2     Pending     0     7h

这些错误表示逐出事件或由于节点资源而无法调度 Pod。由于 Anthos Network Gateway Pod 没有 PriorityClass，因此它们具有与其他工作负载相同的默认优先级。 当节点资源受限时，网络网关 Pod 可能会被逐出。此行为对于 ang-node DaemonSet 尤为糟糕，因为这些 Pod 必须在特定节点上调度，并且不能迁移。


临时解决方法：

升级到 1.15 或更高版本。

作为短期修复，您可以手动为 Anthos Network Gateway 组件分配 PriorityClass。Google Distributed Cloud 控制器会在协调过程中（例如在集群升级期间）覆盖这些手动更改。

  • 将 system-cluster-critical PriorityClass 分配给 ang-controller-manager 和 autoscaler 集群控制器 Deployment。
  • 将 system-node-critical PriorityClass 分配给 ang-daemon 节点 DaemonSet。
升级、更新 1.12、1.13、1.14、1.15.0-1.15.2

使用 gcloud 向非空 gkeConnect 部分注册管理员集群后，您可能会在尝试升级集群时看到以下错误：

failed to register cluster: failed to apply Hub Mem\
bership: Membership API request failed: rpc error: code = InvalidArgument desc = InvalidFieldError for field endpoint.o\
n_prem_cluster.admin_cluster: field cannot be updated

删除 gke-connect 命名空间： 

kubectl delete ns gke-connect --kubeconfig=ADMIN_KUBECONFIG
 获取管理员集群名称： 
kubectl get onpremadmincluster -n kube-system --kubeconfig=ADMIN_KUBECONFIG
 删除舰队成员资格： 
gcloud container fleet memberships delete ADMIN_CLUSTER_NAME
 并恢复升级管理员集群。
操作 1.13.0-1.13.8、1.14.0-1.14.5、1.15.0-1.15.1

gkectl diagnose snapshot --log-since 无法限制在集群节点上运行的 journalctl 命令的时间窗口

这不会影响截取集群快照的功能，因为快照仍然包含通过在集群节点上运行 journalctl 默认收集的所有日志。因此，不会错过任何调试信息。
安装、升级、更新 1.9+、1.10+、1.11+、1.12+

gkectl prepare windows 无法在 1.13 版之前的 Google Distributed Cloud 上安装 Docker，因为 MicrosoftDockerProvider 已被弃用。


临时解决方法：

解决此问题的一般方法是升级到 Google Distributed Cloud 1.13 并使用 1.13 gkectl 创建 Windows 虚拟机模板，然后创建 Windows 节点池。从当前版本升级到 Google Distributed Cloud 1.13 有两种方案，如下所示。

注意：我们也提供无需升级到 1.13 并在当前版本中解决此问题的方案，但它需要更多手动步骤。如果您想要考虑此方案，请与我们的支持团队联系。


方案 1：蓝/绿升级

您可以使用 Google Distributed Cloud 1.13+ 版本创建具有 Windows 节点池的新集群，并将工作负载迁移到新集群，然后删除当前集群。建议使用最新的 Google Distributed Cloud 次要版本。

注意：这需要额外的资源来预配新集群，但现有工作负载的停机时间和中断时间会减少。


方案 2：删除 Windows 节点池，并在升级到 Google Distributed Cloud 1.13 时重新添加回来

注意：对于此方案，在集群升级到 1.13 以及重新添加回 Windows 节点池之前，Windows 工作负载将无法运行。

  1. 通过从 user-cluster.yaml 文件中移除 Windows 节点池配置来删除现有的 Windows 节点池，然后运行以下命令： 
    gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
  2. 根据相应目标次要版本的升级用户指南，将仅使用 Linux 的管理员集群和用户集群升级到 1.12。
  3. （在升级到 1.13 之前，请务必执行此步骤）确保已在 OnPremUserCluster CR 中配置 enableWindowsDataplaneV2: true，否则集群将继续为 Windows 节点池使用 Docker，这将与新创建的未安装 Docker 的 1.13 Windows 虚拟机模板不兼容。如果未配置或设置为 false，请更新您的集群以在 user-cluster.yaml 中将其设置为 true，然后运行以下命令： 
    gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
  4. 根据升级用户指南将仅使用 Linux 的管理员集群和用户集群升级到 1.13。
  5. 使用 1.13 gkectl 准备 Windows 虚拟机模板： 
    gkectl prepare windows --base-vm-template BASE_WINDOWS_VM_TEMPLATE_NAME --bundle-path 1.13_BUNDLE_PATH --kubeconfig=ADMIN_KUBECONFIG
  6. 将 Windows 节点池配置添加回 user-cluster.yaml，并将 OSImage 字段设置为新创建的 Windows 虚拟机模板。
  7. 更新集群以添加 Windows 节点池 
    gkectl update cluster --kubeconfig=ADMIN_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE
安装、升级、更新 1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

节点上将使用 RootDistanceMaxSec 的默认值 5 秒，而不是预期配置 20 秒。如果您通过 SSH 连接到虚拟机以检查节点启动日志（位于“/var/log/startup.log”），可能会看到以下错误：

+ has_systemd_unit systemd-timesyncd
/opt/bin/master.sh: line 635: has_systemd_unit: command not found

使用 5 秒 RootDistanceMaxSec 可能会导致系统时钟在时钟偏移大于 5 秒时与 NTP 服务器不同步。


临时解决方法：

将以下 DaemonSet 应用到您的集群以配置 RootDistanceMaxSec：

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: change-root-distance
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: change-root-distance
  template:
    metadata:
      labels:
        app: change-root-distance
    spec:
      hostIPC: true
      hostPID: true
      tolerations:
      # Make sure pods gets scheduled on all nodes.
      - effect: NoSchedule
        operator: Exists
      - effect: NoExecute
        operator: Exists
      containers:
      - name: change-root-distance
        image: ubuntu
        command: ["chroot", "/host", "bash", "-c"]
        args:
        - |
          while true; do
            conf_file="/etc/systemd/timesyncd.conf.d/90-gke.conf"
            if [ -f $conf_file ] && $(grep -q "RootDistanceMaxSec=20" $conf_file); then
              echo "timesyncd has the expected RootDistanceMaxSec, skip update"
            else
              echo "updating timesyncd config to RootDistanceMaxSec=20"
              mkdir -p /etc/systemd/timesyncd.conf.d
              cat > $conf_file << EOF
          [Time]
          RootDistanceMaxSec=20
          EOF
              systemctl restart systemd-timesyncd
            fi
            sleep 600
          done
        volumeMounts:
        - name: host
          mountPath: /host
        securityContext:
          privileged: true
      volumes:
      - name: host
        hostPath:
          path: /
升级、更新 1.12.0-1.12.6、1.13.0-1.13.6、1.14.0-1.14.2

使用 1.13 版 gkectl 更新 1.12 版管理员集群时，您可能会看到以下错误：

Failed to update the admin cluster: updating OS image type in admin cluster
is not supported in "1.12.x-gke.x"

将 gkectl update admin 用于 1.13 版或 1.14 版集群时，您可能会在响应中看到以下消息：

Exit with error:
Failed to update the cluster: the update contains multiple changes. Please
update only one feature at a time

如果您检查 gkectl 日志，可能会发现多次更改包括将 osImageType 从空字符串设置为 ubuntu_containerd。

这些更新错误是由于管理员集群配置中 osImageType 字段的错误回填导致的，该字段在 1.9 版中引入。


临时解决方法：

升级到包含修复的 Google Distributed Cloud 版本。如果升级不可行，请与 Cloud Customer Care 联系以解决此问题。
安装、安全 1.13、1.14、1.15、1.16

在启用 Controlplane V2 的情况下 (enableControlplaneV2: true)，通过 authentication.sni 为用户集群的 Kubernetes API 服务器提供额外的服务证书将不起作用。


临时解决方法：

在包含修复的 Google Distributed Cloud 补丁可用之前，如果您需要使用 SNI，请停用 Controlplane V2 (enableControlplaneV2: false)。
安装 1.0-1.11、1.12、1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

当私有注册表用户名包含 $ 时，管理员控制平面机器无法启动。在检查管理员控制平面机器上的 /var/log/startup.log 时，您会看到以下错误：

++ REGISTRY_CA_CERT=xxx
++ REGISTRY_SERVER=xxx
/etc/startup/startup.conf: line 7: anthos: unbound variable

临时解决方法：

使用不含 $ 的私有仓库用户名，或者使用包含修复的 Google Distributed Cloud 版本。
升级、更新 1.12.0-1.12.4

更新管理员集群时，您会在日志中看到以下误报警告，您可以忽略它们。

    console.go:47] detected unsupported changes: &v1alpha1.OnPremAdminCluster{
      ...
      -         CARotation:        &v1alpha1.CARotationConfig{Generated: &v1alpha1.CARotationGenerated{CAVersion: 1}},
      +         CARotation:        nil,
      ...
    }
升级、更新 1.13.0-1.13.9、1.14.0-1.14.5、1.15.0-1.15.1

如果您在轮替 KSA 签名密钥之后更新用户集群，gkectl update 可能会失败并显示以下错误消息： 

Failed to apply OnPremUserCluster 'USER_CLUSTER_NAME-gke-onprem-mgmt/USER_CLUSTER_NAME':
admission webhook "vonpremusercluster.onprem.cluster.gke.io" denied the request:
requests must not decrement *v1alpha1.KSASigningKeyRotationConfig Version, old version: 2, new version: 1"


临时解决方法：

将 KSA 签名密钥版本更改回 1，但保留最新的密钥数据：
  1. 查看管理员集群中 USER_CLUSTER_NAME 命名空间下的密钥，并获取 ksa-signing-key 密钥的名称： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME get secrets | grep ksa-signing-key
  2. 复制 ksa-signing-key 密钥，并将复制的密钥命名为 service-account-cert： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME get secret KSA-KEY-SECRET-NAME -oyaml | \
sed 's/ name: .*/ name: service-account-cert/' | \
kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME apply -f -
  3. 删除之前的 ksa-signing-key 密钥： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME delete secret KSA-KEY-SECRET-NAME
  4. 将 ksa-signing-key-rotation-stage configmap 中的 data.data 字段更新为 '{"tokenVersion":1,"privateKeyVersion":1,"publicKeyVersions":[1]}'： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME \
edit configmap ksa-signing-key-rotation-stage
  5. 停用验证 webhook 以修改 OnPremUserCluster 自定义资源中的版本信息： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG patch validatingwebhookconfiguration onprem-user-cluster-controller -p '
webhooks:
- name: vonpremnodepool.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    resources:
    - onpremnodepools
- name: vonpremusercluster.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    resources:
    - onpremuserclusters
'
  6. 将 OnPremUserCluster 自定义资源中的 spec.ksaSigningKeyRotation.generated.ksaSigningKeyRotation 字段更新为 1： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME-gke-onprem-mgmt \
edit onpremusercluster USER_CLUSTER_NAME
  7. 等待目标用户集群准备就绪，您可通过以下命令查看状态： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=USER_CLUSTER_NAME-gke-onprem-mgmt \
get onpremusercluster
  8. 恢复用户集群的验证 webhook： 
    kubectl --kubeconfig=ADMIN_KUBECONFIG patch validatingwebhookconfiguration onprem-user-cluster-controller -p '
webhooks:
- name: vonpremnodepool.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    - UPDATE
    resources:
    - onpremnodepools
- name: vonpremusercluster.onprem.cluster.gke.io
  rules:
  - apiGroups:
    - onprem.cluster.gke.io
    apiVersions:
    - v1alpha1
    operations:
    - CREATE
    - UPDATE
    resources:
    - onpremuserclusters
'
  9. 在集群升级到包含修复的版本之前，避免再次进行 KSA 签名密钥轮替。
操作 1.13.1+、1.14、1.、1.16

当您使用 Terraform 删除具有 F5 BIG-IP 负载均衡器的用户集群后，F5 BIG-IP 虚拟服务器在集群删除后不会移除。


临时解决方法：

如需移除 F5 资源，请按照清理用户集群 F5 分区的步骤操作
安装、升级、更新 1.13.8、1.14.4

如果您创建 1.13.8 版或 1.14.4 版的管理员集群，或者将管理员集群升级到 1.13.8 版或 1.14.4 版，kind 集群会从 docker.io 拉取以下容器映像：

  • docker.io/kindest/kindnetd
  • docker.io/kindest/local-path-provisioner
  • docker.io/kindest/local-path-helper

    • 如果无法从管理员工作站访问 docker.io，则管理员集群创建或升级无法启动 kind 集群。在管理员工作站上运行以下命令会显示相应容器正在等待并具有 ErrImagePull：

    docker exec gkectl-control-plane kubectl get pods -A

    响应包含如下条目：

    ...
kube-system         kindnet-xlhmr                             0/1
    ErrImagePull  0    3m12s
...
local-path-storage  local-path-provisioner-86666ffff6-zzqtp   0/1
    Pending       0    3m12s
...

    这些容器映像应预加载到 kind 集群容器映像中。但是，kind v0.18.0 存在预加载的容器映像问题，这会导致错误地从互联网拉取这些映像。


    临时解决方法：

    在管理员集群等待创建或升级时，在管理员工作站上运行以下命令：

    docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/kindnetd:v20230330-48f316cd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af docker.io/kindest/kindnetd:v20230330-48f316cd
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/kindnetd:v20230330-48f316cd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af docker.io/kindest/kindnetd@sha256:c19d6362a6a928139820761475a38c24c0cf84d507b9ddf414a078cf627497af

docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-helper:v20230330-48f316cd@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270 docker.io/kindest/local-path-helper:v20230330-48f316cd
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-helper:v20230330-48f316cd@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270 docker.io/kindest/local-path-helper@sha256:135203f2441f916fb13dad1561d27f60a6f11f50ec288b01a7d2ee9947c36270

docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-provisioner:v0.0.23-kind.0@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501 docker.io/kindest/local-path-provisioner:v0.0.23-kind.0
docker exec gkectl-control-plane ctr -n k8s.io images tag docker.io/kindest/local-path-provisioner:v0.0.23-kind.0@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501 docker.io/kindest/local-path-provisioner@sha256:f2d0a02831ff3a03cf51343226670d5060623b43a4cfc4808bd0875b2c4b9501
    操作 1.13.0-1.13.7、1.14.0-1.14.4、1.15.0

    如果您的集群虚拟机连接了一个用于过滤掉重复 GARP（不必要的 ARP）请求的交换机，keepalived 主节点选举可能会遇到竞态条件，导致某些节点具有错误的 ARP 表条目。

    受影响的节点可以 ping 控制平面 VIP，但与控制平面 VIP 的 TCP 连接将超时。


    临时解决方法：

    在受影响集群的每个控制平面节点上运行以下命令： 
        iptables -I FORWARD -i ens192 --destination CONTROL_PLANE_VIP -j DROP
    升级、更新 1.13.0-1.13.7、1.14.0-1.14.4、1.15.0

    vsphere-csi-controller 应在 vCenter 证书轮替后刷新其 vCenter 密钥。但是，当前系统未正确重启 vsphere-csi-controller 的 Pod，导致 vsphere-csi-controller 在轮替后崩溃。

    临时解决方法：

    对于在 1.13 及更高版本中创建的集群，请按照以下说明重启 vsphere-csi-controller 

    kubectl --kubeconfig=ADMIN_KUBECONFIG rollout restart deployment vsphere-csi-controller -n kube-system
    安装 1.10.3-1.10.7、1.11、1.12、1.13.0-1.13.1

    即使在创建管理员集群期间集群注册失败，命令 gkectl create admin 也不会因此失败，并且可能会成功。换句话说，管理员集群创建可能在未注册到舰队的情况下“成功”。

    如需识别此症状，您可以在“gkectl create admin”的日志中查找以下错误消息。 
    Failed to register admin cluster

    您还可以在 Cloud 控制台的已注册集群中尝试查找该集群。

    临时解决方法：

    对于在 1.12 及更高版本中创建的集群，请在创建集群后按照重试管理员集群注册中的说明操作。对于在更低版本中创建的集群，

    1. 将诸如“foo: bar”的虚构键值对附加到连接和注册 SA 密钥文件
    2. 运行 gkectl update admin 以重新注册管理员集群。

    升级、更新 1.10、1.11、1.12、1.13.0-1.13.1

    在管理员集群升级期间，如果升级用户控制平面节点超时，管理员集群将不会向更新后的连接代理版本重新注册。


    临时解决方法：

    检查集群是否显示在已注册集群中。作为可选步骤，在设置身份验证后登录集群。如果集群仍为已注册状态，您可以跳过以下关于重新尝试注册的说明。对于升级到 1.12 及更高版本的集群，请在创建集群后按照重试管理员集群注册中的说明操作。对于升级到更低版本的集群，
    1. 将诸如“foo: bar”的虚构键值对附加到连接和注册 SA 密钥文件
    2. 运行 gkectl update admin 以重新注册管理员集群。

    配置 1.15.0

    对于高可用性管理员集群，gkectl prepare 会显示以下误报的错误消息：

    vCenter.dataDisk must be present in the AdminCluster spec

    临时解决方法：

    您可以放心地忽略此错误消息。
    VMware 1.15.0

    在创建使用虚拟机宿主机亲和性的节点池时，竞态条件可能导致创建多条具有相同名称的虚拟机宿主机亲和性规则。这可能会导致节点池创建失败。


    临时解决方法：

    移除旧的冗余规则，以使节点池创建能够继续进行。这些规则命名为 [USER_CLUSTER_NAME]-[HASH]。
    操作 1.15.0

    gkectl repair admin-master 命令可能会由于竞态条件而失败，并显示以下错误。 

    Failed to repair: failed to delete the admin master node object and reboot the admin master VM


    临时解决方法：

    此命令具有幂等性。它可以安全地重新运行，直到命令成功为止。
    升级、更新 1.15.0

    重新创建或更新控制平面节点后，由于 NodeAffinity 谓词失败，某些 Pod 可能会保持 Failed 状态。这些失败的 Pod 不会影响正常的集群操作或健康状况。


    临时解决方法：

    您可以放心地忽略失败的 Pod 或手动删除它们。
    安全、配置 1.15.0-1.15.1

    如果您使用准备好的凭据和私有注册表，但尚未为私有注册表配置准备好的凭据，OnPremUserCluster 可能无法变为就绪状态，并且您可能会看到以下错误消息： 

    failed to check secret reference for private registry …


    临时解决方法：

    根据配置准备好的凭据中的说明，为用户集群准备私有仓库凭据。

    升级、更新 1.15.0

    在 gkectl upgrade admin 期间，CSI 迁移的存储预检检查会验证 StorageClass 没有在 CSI 迁移后被忽略的参数。例如，如果某个 StorageClass 具有参数 diskformat，则 gkectl upgrade admin 会标记该 StorageClass 并在预检验证中报告失败。在 Google Distributed Cloud 1.10 及更低版本中创建的管理员集群具有 diskformat: thin 的 StorageClass，这会导致此验证失败，但此 StorageClass 在 CSI 迁移后仍然可以正常运行。这些故障应被解读为警告。

    如需了解详情，请参阅将树内 vSphere 卷迁移到 vSphere 容器存储插件中的 StorageClass 参数部分。


    临时解决方法：

    确认集群的 StorageClass 具有在 CSI 迁移后被忽略的参数后，运行带有 --skip-validation-cluster-health 标志的 gkectl upgrade admin。
    存储 1.15、1.16

    在某些情况下，磁盘可以作为只读磁盘挂接到 Windows 节点。这会导致相应的卷在 Pod 中成为只读卷。当一组新节点替换旧节点时（例如集群升级或节点池更新），较有可能发生此问题。之前正常运行的有状态工作负载在新的一组节点上可能无法写入其卷。


    临时解决方法：

    1. 获取无法写入其卷的 Pod 的 UID： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get pod \
    POD_NAME --namespace POD_NAMESPACE \
    -o=jsonpath='{.metadata.uid}{"\n"}'
    2. 使用 PersistentVolumeClaim 获取 PersistentVolume 的名称： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get pvc \
    PVC_NAME --namespace POD_NAMESPACE \
    -o jsonpath='{.spec.volumeName}{"\n"}'
    3. 确定运行 Pod 的节点的名称： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIGget pods \
    --namespace POD_NAMESPACE \
    -o jsonpath='{.spec.nodeName}{"\n"}'
    4. 通过 SSH 或 vSphere 网页界面获取对节点的 Powershell 访问权限。
    5. 设置环境变量： 
      PS C:\Users\administrator> pvname=PV_NAME
PS C:\Users\administrator> podid=POD_UID
    6. 确定与 PersistentVolume 关联的磁盘的磁盘编号： 
      PS C:\Users\administrator> disknum=(Get-Partition -Volume (Get-Volume -UniqueId ("\\?\"+(Get-Item (Get-Item
"C:\var\lib\kubelet\pods\$podid\volumes\kubernetes.io~csi\$pvname\mount").Target).Target))).DiskNumber
    7. 验证磁盘为 readonly： 
      PS C:\Users\administrator> (Get-Disk -Number $disknum).IsReadonly
       结果应为 True。
    8. 将 readonly 设置为 false。 
      PS C:\Users\administrator> Set-Disk -Number $disknum -IsReadonly $false
PS C:\Users\administrator> (Get-Disk -Number $disknum).IsReadonly
    9. 删除 Pod 以使其重启： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete pod POD_NAME \
    --namespace POD_NAMESPACE
    10. Pod 应该被安排到同一节点上。但是，如果 Pod 被安排到新节点上，您可能需要在新节点上重复上述步骤。

    升级、更新 1.12、1.13.0-1.13.7、1.14.0-1.14.4

    gkectl update credentials vsphere --admin-cluster 后 vsphere-csi-secret 不会更新

    如果您在更新集群凭据后更新管理员集群的 vSphere 凭据，则可能会发现管理员集群中的 kube-system 命名空间下的 vsphere-csi-secret 仍然使用旧凭据。


    临时解决方法：

    1. 获取 vsphere-csi-secret 密钥名称： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system get secrets | grep vsphere-csi-secret
    2. 更新您在上一步中获得的 vsphere-csi-secret 密钥的数据： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system patch secret CSI_SECRET_NAME -p \
  "{\"data\":{\"config\":\"$( \
    kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system get secrets CSI_SECRET_NAME -ojsonpath='{.data.config}' \
      | base64 -d \
      | sed -e '/user/c user = \"VSPHERE_USERNAME_TO_BE_UPDATED\"' \
      | sed -e '/password/c password = \"VSPHERE_PASSWORD_TO_BE_UPDATED\"' \
      | base64 -w 0 \
    )\"}}"
    3. 重启 vsphere-csi-controller： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system rollout restart deployment vsphere-csi-controller
    4. 您可以使用以下命令跟踪发布状态： 
      kubectl --kubeconfig=ADMIN_KUBECONFIG -n=kube-system rollout status deployment vsphere-csi-controller
       部署成功发布后，控制器应使用更新后的 vsphere-csi-secret。
    升级、更新 1.10、1.11、1.12.0-1.12.6、1.13.0-1.13.6、1.14.0-1.14.2

    audit-proxy 可能会因空 --cluster-name 而发生崩溃循环。此行为是由更新逻辑中的一个 bug 引起的，即集群名称不会传播到审核代理 Pod/容器清单。


    临时解决方法：

    对于具有 enableControlplaneV2: true 的控制平面 v2 用户集群，使用 SSH 连接到用户控制平面机器，并使用 --cluster_name=USER_CLUSTER_NAME 更新 /etc/kubernetes/manifests/audit-proxy.yaml。

    对于控制平面 v1 用户集群，修改 kube-apiserver statefulset 中的 audit-proxy 容器以添加 --cluster_name=USER_CLUSTER_NAME：

    kubectl edit statefulset kube-apiserver -n USER_CLUSTER_NAME --kubeconfig=ADMIN_CLUSTER_KUBECONFIG
    升级、更新 1.11、1.12、1.13.0-1.13.5、1.14.0-1.14.1

    在 gkectl upgrade cluster 之后，控制平面 Pod 可能会立即再次重新部署。 gkectl list clusters 中的集群状态从 RUNNING 变为 RECONCILING。 对用户集群发出的请求可能会超时。

    出现这种行为的原因是在 gkectl upgrade cluster 之后自动进行控制平面证书轮替。

    只有不使用控制平面 v2 的用户集群会出现此问题。


    临时解决方法：

    等待集群状态在 gkectl list clusters 中恢复为 RUNNING，或升级到包含修复的版本：1.13.6+、1.14.2+ 或 1.15+。
    升级、更新 1.12.7

    Google Distributed Cloud 1.12.7-gke.19 是一个有问题的版本，您不应使用它。这些工件已从 Cloud Storage 存储桶中移除。

    临时解决方法：

    请改用 1.12.7-gke.20 版本。
    升级、更新 1.12.0+、1.13.0-1.13.7、1.14.0-1.14.3

    如果您使用以下方法之一更新仓库凭据：

    • gkectl update credentials componentaccess（如果不使用私有仓库）
    • gkectl update credentials privateregistry（如果使用私有仓库）

    您可能会发现 gke-connect-agent 会继续使用旧版映像，或者由于 ImagePullBackOff 而无法拉取 gke-connect-agent Pod。

    此问题将在 Google Distributed Cloud 1.13.8、1.14.4 和后续版本中修复。


    临时解决方法：

    方法 1：手动重新部署 gke-connect-agent：

    1. 删除 gke-connect 命名空间： 
      kubectl --kubeconfig=KUBECONFIG delete namespace gke-connect
    2. 使用原始注册服务账号密钥重新部署 gke-connect-agent（无需更新密钥）：

      对于管理员集群： 
      gkectl update credentials register --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config ADMIN_CLUSTER_CONFIG_FILE --admin-cluster
       对于用户集群： 
      gkectl update credentials register --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG_FILE

    方法 2：您可以手动更改 gke-connect-agent 部署使用的映像拉取 Secret regcred 的数据：

    kubectl --kubeconfig=KUBECONFIG -n=gke-connect patch secrets regcred -p "{\"data\":{\".dockerconfigjson\":\"$(kubectl --kubeconfig=KUBECONFIG -n=kube-system get secrets private-registry-creds -ojsonpath='{.data.\.dockerconfigjson}')\"}}"

    方法 3：您可以通过以下方式在 gke-connect-agent 部署中添加集群的默认映像拉取 Secret：

    1. 将默认 Secret 复制到 gke-connect 命名空间： 
      kubectl --kubeconfig=KUBECONFIG -n=kube-system get secret private-registry-creds -oyaml | sed 's/ namespace: .*/ namespace: gke-connect/' | kubectl --kubeconfig=KUBECONFIG -n=gke-connect apply -f -
    2. 获取 gke-connect-agent 部署名称： 
      kubectl --kubeconfig=KUBECONFIG -n=gke-connect get deployment | grep gke-connect-agent
    3. 将默认 Secret 添加到 gke-connect-agent 部署： 
      kubectl --kubeconfig=KUBECONFIG -n=gke-connect patch deployment DEPLOYMENT_NAME -p '{"spec":{"template":{"spec":{"imagePullSecrets": [{"name": "private-registry-creds"}, {"name": "regcred"}]}}}}'
    安装 1.13、1.14

    通过运行 gkectl check-config 在使用手动负载均衡器创建集群之前验证配置时，命令将失败，并显示以下错误消息。

     - Validation Category: Manual LB    Running validation check for "Network 
configuration"...panic: runtime error: invalid memory address or nil pointer 
dereference

    临时解决方法：

    方法 1：您可以使用将包含修复的补丁版本 1.13.7 和 1.14.4。

    方法 2：您也可以运行相同命令来验证配置，但跳过负载均衡器验证。

    gkectl check-config --skip-validation-load-balancer
    操作 1.0、1.1、1.2、1.3、1.4、1.5、1.6、1.7、1.8、1.9、1.10、1.11、1.12、1.13 和 1.14

    运行 etcd 3.4.13 或更早版本的集群可能会遇到 watch 耗尽且非操作性资源进行监控，这可能会导致以下问题：

    • Pod 调度中断
    • 节点无法注册
    • kubelet 不观察 Pod 变化

    这些问题可能会导致集群无法正常运行。

    此问题在 Google Distributed Cloud 1.12.7、1.13.6、1.14.3 和后续版本中已得到解决。这些较新的版本使用 etcd 3.4.21 版。所有旧版 Google Distributed Cloud 都会受此问题影响。

    临时解决方法

    如果您无法立即升级，则可以通过减少集群中的节点数来降低集群故障的风险。移除节点，直到 etcd_network_client_grpc_sent_bytes_total 指标小于 300 MBps。

    如需在 Metrics Explorer 中查看此指标，请执行以下操作：

    1. 前往 Google Cloud 控制台中的 Metrics Explorer：

      转到 Metrics Explorer

    2. 选择 Configuration（配置）标签页。
    3. 展开选择一个指标，在过滤栏中输入 Kubernetes Container，然后使用子菜单选择该指标：
      1. 在活跃资源菜单中，选择 Kubernetes 容器。
      2. 在活跃指标类别菜单中，选择 Anthos。
      3. 在活跃指标菜单中，选择 etcd_network_client_grpc_sent_bytes_total。
      4. 点击“应用”。
    升级、更新 1.10、1.11、1.12、1.13 和 1.14

    在集群重启或升级时，GKE Identity Service 可能会收到超出其负载的流量，这些流量包含通过身份验证 webhook 从 kube-apiserver 转发到 GKE Identity Service 的过期 JWT 令牌。尽管 GKE Identity Service 不会崩溃循环，但它会变得无响应，并停止响应更多请求。 此问题最终会导致控制平面的延迟时间增加。

    此问题已在以下 Google Distributed Cloud 版本中得到解决：

    • 1.12.6+
    • 1.13.6+
    • 1.14.2+

    要确定您是否受到此问题影响，请执行以下步骤：

    1. 检查是否可以从外部访问 GKE Identity Service 端点： 
      curl -s -o /dev/null -w "%{http_code}" \
    -X POST https://CLUSTER_ENDPOINT/api/v1/namespaces/anthos-identity-service/services/https:ais:https/proxy/authenticate -d '{}'

      将 CLUSTER_ENDPOINT 替换为您的集群的控制平面 VIP 和控制平面负载均衡器端口（例如 172.16.20.50:443）。

      如果您受到此问题的影响，该命令会返回 400 状态代码。如果请求超时，请重启 ais Pod 并重新运行 curl 命令，看看是否能解决问题。如果您收到状态代码 000，则说明问题已解决，您无需再执行任何操作。如果您仍然收到 400 状态代码，则说明 GKE Identity Service HTTP 服务器未启动。在这种情况下，请继续。

    2. 检查 GKE Identity Service 和 kube-apiserver 日志：
      1. 检查 GKE Identity Service 日志： 
        kubectl logs -f -l k8s-app=ais -n anthos-identity-service \
    --kubeconfig KUBECONFIG

        如果日志包含如下所示的条目，则表示您受到此问题的影响：

        I0811 22:32:03.583448      32 authentication_plugin.cc:295] Stopping OIDC authentication for ???. Unable to verify the OIDC ID token: JWT verification failed: The JWT does not appear to be from this identity provider. To match this provider, the 'aud' claim must contain one of the following audiences:
      2. 检查集群的 kube-apiserver 日志：

        在以下命令中，KUBE_APISERVER_POD 是给定集群上的 kube-apiserver Pod 的名称。

        管理员集群：

        kubectl --kubeconfig ADMIN_KUBECONFIG logs \
    -n kube-system KUBE_APISERVER_POD kube-apiserver

        用户集群：

        kubectl --kubeconfig ADMIN_KUBECONFIG logs \
    -n USER_CLUSTER_NAME KUBE_APISERVER_POD kube-apiserver

        如果 kube-apiserver 日志包含如下所示的条目，则表示您受到此问题的影响：

        E0811 22:30:22.656085       1 webhook.go:127] Failed to make webhook authenticator request: error trying to reach service: net/http: TLS handshake timeout
E0811 22:30:22.656266       1 authentication.go:63] "Unable to authenticate the request" err="[invalid bearer token, error trying to reach service: net/http: TLS handshake timeout]"

    临时解决方法

    如果您无法立即升级集群以获取修复，作为临时解决方法，您可以找到引发问题的 Pod 并将其重启：

    1. 将 GKE Identity Service 的详细程度增加到 9： 
      kubectl patch deployment ais -n anthos-identity-service --type=json \
    -p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", \
    "value":"--vmodule=cloud/identity/hybrid/charon/*=9"}]' \
    --kubeconfig KUBECONFIG
    2. 检查 GKE Identity Service 日志中是否存在无效的令牌上下文： 
      kubectl logs -f -l k8s-app=ais -n anthos-identity-service \
    --kubeconfig KUBECONFIG
    3. 如需获取与每个无效令牌上下文关联的令牌载荷，请使用以下命令解析每个相关的服务账号 Secret：
      kubectl -n kube-system get secret SA_SECRET \
    --kubeconfig KUBECONFIG \
    -o jsonpath='{.data.token}' | base64 --decode
    4. 如需解码令牌并查看来源 Pod 名称和命名空间，请将令牌复制到位于 jwt.io 的调试程序。
    5. 重启令牌中标识的 Pod。
    操作 1.8、1.9、1.10

    使用 etcddefrag:gke_master_etcddefrag_20210211.00_p0 映像的 etcd-maintenance Pod 会受到影响。`etcddefrag` 容器会在每个碎片整理周期内打开与 etcd 服务器的新连接，并且旧连接不会被清理。


    临时解决方法：

    方法 1：升级到最新的 1.8 到 1.11 补丁版本，其中包含修复代码。

    方法 2：如果您使用的是早于 1.9.6 和 1.10.3 的补丁版本，则需要缩减管理员集群和用户集群的 etcd 维护 Pod：

    kubectl scale --replicas 0 deployment/gke-master-etcd-maintenance -n USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG
kubectl scale --replicas 0 deployment/gke-master-etcd-maintenance -n kube-system --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    操作 1.9、1.10、1.11、1.12、1.13

    集群健康控制器和 gkectl diagnose cluster 命令都会执行一组健康检查，包括跨命名空间的 Pod 健康检查。但是，它们会开始错误地跳过用户控制平面 Pod。如果您使用控制平面 v2 模式，则不会影响集群。


    临时解决方法：

    这不会影响任何工作负载或集群管理。如果要检查控制平面 pod 的运行状况，您可以运行以下命令：

    kubectl get pods -owide -n USER_CLUSTER_NAME --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    升级、更新 1.6+、1.7+

    1.6 和 1.7 管理员集群升级可能会受到 k8s.gcr.io -> registry.k8s.io 重定向的影响

    Kubernetes 在 2023 年 3 月 20 日将流量从 k8s.gcr.io 重定向到 registry.k8s.io。在 Google Distributed Cloud 1.6.x 和 1.7.x 中，管理员集群升级使用容器映像 k8s.gcr.io/pause:3.2。如果您为管理员工作站使用代理，该代理不允许 registry.k8s.io，并且容器映像 k8s.gcr.io/pause:3.2 未在本地缓存，则在拉取容器映像时管理员集群升级将失败。


    临时解决方法：

    将 registry.k8s.io 添加到管理员工作站的代理的许可名单。
    网络 1.10、1.11、1.12.0-1.12.6、1.13.0-1.13.6、1.14.0-1.14.2

    gkectl create loadbalancer 失败，显示以下错误消息：

    - Validation Category: Seesaw LB - [FAILURE] Seesaw validation: xxx cluster lb health check failed: LB"xxx.xxx.xxx.xxx" is not healthy: Get "http://xxx.xxx.xxx.xxx:xxx/healthz": dial tcpxxx.xxx.xxx.xxx:xxx: connect: no route to host

    这是因为 Seesaw 群组文件已存在。预检检查会尝试验证不存在的 Seesaw 负载均衡器。

    临时解决方法：

    移除此集群的现有 Seesaw 群组文件。对于管理员集群，该文件名为 seesaw-for-gke-admin.yaml；对于用户集群，该文件名为 seesaw-for-{CLUSTER_NAME}.yaml。
    网络 1.14

    使用 Ubuntu 或 COS 操作系统映像时，Google Distributed Cloud 1.14 版容易发生 netfilter 连接跟踪 (conntrack) 表插入失败。插入失败会导致随机应用超时，即使 conntrack 表有空间可用于添加新条目，也可能会发生这种情况。失败是由内核 5.15 及更高版本中的更改引起的，这些更改根据链长度限制表插入。

    如需查看您是否受到此问题的影响，您可以使用以下命令检查每个节点上的内核内连接跟踪系统统计信息：

    sudo conntrack -S

    响应如下所示：

    cpu=0       found=0 invalid=4 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=1       found=0 invalid=0 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=2       found=0 invalid=16 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=3       found=0 invalid=13 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=4       found=0 invalid=9 insert=0 insert_failed=0 drop=0 early_drop=0 error=0 search_restart=0 clash_resolve=0 chaintoolong=0 
cpu=5       found=0 invalid=1 insert=0 insert_failed=0 drop=0 early_drop=0 error=519 search_restart=0 clash_resolve=126 chaintoolong=0 
...

    如果响应中的 chaintoolong 值为非零数字，则表示您受到此问题的影响。

    临时解决方法

    短期缓解措施是增加 netfiler 哈希表 (nf_conntrack_buckets) 和 netfilter 连接跟踪表 (nf_conntrack_max) 的大小。在每个集群节点上使用以下命令来增加表的大小：

    sysctl -w net.netfilter.nf_conntrack_buckets=TABLE_SIZE
sysctl -w net.netfilter.nf_conntrack_max=TABLE_SIZE

    将 TABLE_SIZE 替换为新的大小（以字节为单位）。默认表大小值为 262144。我们建议您设置一个等于节点核心数 65,536 倍的值。例如，如果您的节点有 8 个核心，请将表大小设置为 524288。
    网络 1.13.0-1.13.2

    使用 Controlplane v2 或新的安装模型时，calico-typha 或 anetd-operator 可能会被调度到 Windows 节点并陷入崩溃循环。

    这是因为这两个部署可以容忍所有污点，包括 Windows 节点污点。


    临时解决方法：

    升级到 1.13.3+，或运行以下命令以修改“calico-typha”或“anetd-operator”部署：

        # If dataplane v2 is not used.
    kubectl edit deployment -n kube-system calico-typha --kubeconfig USER_CLUSTER_KUBECONFIG
    # If dataplane v2 is used.
    kubectl edit deployment -n kube-system anetd-operator --kubeconfig USER_CLUSTER_KUBECONFIG

    移除以下 spec.template.spec.tolerations：

        - effect: NoSchedule
      operator: Exists
    - effect: NoExecute
      operator: Exists

    并添加以下容忍设置：

        - key: node-role.kubernetes.io/master
      operator: Exists
    配置 1.14.0-1.14.2

    如果您使用凭据 fileRef 指定 privateRegistry 部分，则可能无法创建用户集群。预检可能会失败，并显示以下消息： 

    [FAILURE] Docker registry access: Failed to login.


    临时解决方法：

    • 如果您不打算指定此字段，或者想要使用与管理员集群相同的私有仓库凭据，则只需移除或注释掉用户集群配置文件中的 privateRegistry 部分即可。
    • 如果您想要为用户集群使用特定的私有注册表凭据，则可以通过以下方式暂时指定 privateRegistry 部分：
      privateRegistry:
  address: PRIVATE_REGISTRY_ADDRESS
  credentials:
    username: PRIVATE_REGISTRY_USERNAME
    password: PRIVATE_REGISTRY_PASSWORD
  caCertPath: PRIVATE_REGISTRY_CACERT_PATH
       (注意：这只是暂时性的修复方法并且这些字段已弃用，请考虑在升级到 1.14.3+ 时使用凭据文件。）

    运维 1.10+

    Dataplane V2 接管负载均衡，并创建内核套接字，而不是基于数据包的 DNAT。这意味着 Cloud Service Mesh 无法执行数据包检查，因为 Pod 被绕过并且从不使用 IPTable。

    此问题会在 kube-proxy 免费模式下出现，表现为 Cloud Service Mesh 服务连接中断或流量路由不正确，因为边车代理无法执行数据包检查。

    Google Distributed Cloud 1.10 的所有版本都存在此问题，但某些较新的 1.10 版本 (1.10.2+) 提供了临时解决方法。


    临时解决方法：

    升级到 1.11 以实现完全兼容；如果运行 1.10.2 或更高版本，请运行以下命令：

        kubectl edit cm -n kube-system cilium-config --kubeconfig USER_CLUSTER_KUBECONFIG

    将 bpf-lb-sock-hostns-only: true 添加到 configmap，然后重启 anetd daemonset：

          kubectl rollout restart ds anetd -n kube-system --kubeconfig USER_CLUSTER_KUBECONFIG

    存储 1.12+、1.13.3

    在分离 PV/PVC 时，kube-controller-manager 可能会在 6 分钟后超时，并强制分离 PV/PVC。来自 kube-controller-manager 的详细日志会显示类似于以下内容的事件：

    $ cat kubectl_logs_kube-controller-manager-xxxx | grep "DetachVolume started" | grep expired

kubectl_logs_kube-controller-manager-gke-admin-master-4mgvr_--container_kube-controller-manager_--kubeconfig_kubeconfig_--request-timeout_30s_--namespace_kube-system_--timestamps:2023-01-05T16:29:25.883577880Z W0105 16:29:25.883446       1 reconciler.go:224] attacherDetacher.DetachVolume started for volume "pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16" (UniqueName: "kubernetes.io/csi/csi.vsphere.vmware.com^126f913b-4029-4055-91f7-beee75d5d34a") on node "sandbox-corp-ant-antho-0223092-03-u-tm04-ml5m8-7d66645cf-t5q8f"
This volume is not safe to detach, but maxWaitForUnmountDuration 6m0s expired, force detaching

    如需验证问题，请登录节点并运行以下命令：

    # See all the mounting points with disks
lsblk -f

# See some ext4 errors
sudo dmesg -T

    kubelet 日志中会显示如下错误：

    Error: GetDeviceMountRefs check failed for volume "pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16" (UniqueName: "kubernetes.io/csi/csi.vsphere.vmware.com^126f913b-4029-4055-91f7-beee75d5d34a") on node "sandbox-corp-ant-antho-0223092-03-u-tm04-ml5m8-7d66645cf-t5q8f" :
the device mount path "/var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16/globalmount" is still mounted by other references [/var/lib/kubelet/plugins/kubernetes.io/csi/pv/pvc-8bb4780b-ba8e-45f4-a95b-19397a66ce16/globalmount

    临时解决方法：

    使用 SSH 连接到受影响的节点，然后重新启动该节点。
    升级、更新 1.12+、1.13+、1.14+

    如果您使用第三方 CSI 驱动程序，则可能无法升级集群。gkectl cluster diagnose 命令可能会返回以下错误：

    "virtual disk "kubernetes.io/csi/csi.netapp.io^pvc-27a1625f-29e3-4e4f-9cd1-a45237cc472c" IS NOT attached to machine "cluster-pool-855f694cc-cjk5c" but IS listed in the Node.Status"


    临时解决方法：

    使用 --skip-validation-all 选项执行升级。
    操作 1.10+、1.11+、1.12+、1.13+、1.14+

    通过 gkectl repair admin-master 创建的管理员主节点可能使用低于预期的虚拟机硬件版本。发生此问题时，您会在 gkectl diagnose cluster 报告中看到错误。 

    CSIPrerequisites [VM Hardware]: The current VM hardware versions are lower than vmx-15 which is unexpected. Please contact Anthos support to resolve this issue.


    临时解决方法：

    关停管理员主节点，遵循 https://kb.vmware.com/s/article/1003746 将节点升级到错误消息中所述的预期版本，然后启动节点。
    操作系统 1.10+、1.11+、1.12+、1.13+、1.14+、1.15+、1.16+

    在 systemd v244 中，systemd-networkd 会对 KeepConfiguration 配置进行默认行为更改。在此更改之前，虚拟机不会在关停或重新启动时向 DHCP 服务器发送 DHCP 租约释放消息。在此更改之后，虚拟机会向 DHCP 服务器发送此消息并返回 IP 地址。因此，系统可能会将释放的 IP 地址重新分配给其他虚拟机，并且/或者可能为虚拟机分配其他 IP 地址，从而导致虚拟机 IP 地址冲突（在 Kubernetes 级层而不是 vSphere 级层）和/或 IP 地址更改，这可能会以各种方式破坏集群。

    例如，您可能会看到以下症状。

    • vCenter 界面显示没有虚拟机使用相同的 IP 地址，但 kubectl get nodes -o wide 返回具有重复 IP 地址的节点。
      NAME   STATUS    AGE  VERSION          INTERNAL-IP    EXTERNAL-IP    OS-IMAGE            KERNEL-VERSION    CONTAINER-RUNTIME
node1  Ready     28h  v1.22.8-gke.204  10.180.85.130  10.180.85.130  Ubuntu 20.04.4 LTS  5.4.0-1049-gkeop  containerd://1.5.13
node2  NotReady  71d  v1.22.8-gke.204  10.180.85.130  10.180.85.130  Ubuntu 20.04.4 LTS  5.4.0-1049-gkeop  containerd://1.5.13
    • 由于 calico-node 错误，新节点无法启动 
      2023-01-19T22:07:08.817410035Z 2023-01-19 22:07:08.817 [WARNING][9] startup/startup.go 1135: Calico node 'node1' is already using the IPv4 address 10.180.85.130.
2023-01-19T22:07:08.817514332Z 2023-01-19 22:07:08.817 [INFO][9] startup/startup.go 354: Clearing out-of-date IPv4 address from this node IP="10.180.85.130/24"
2023-01-19T22:07:08.825614667Z 2023-01-19 22:07:08.825 [WARNING][9] startup/startup.go 1347: Terminating
2023-01-19T22:07:08.828218856Z Calico node failed to start


    临时解决方法：

    在集群上部署以下 DaemonSet 以还原 systemd-networkd 默认行为更改。运行此 DaemonSet 的虚拟机在关停/重新启动时不会向 DHCP 服务器释放 IP 地址。租约到期时，DHCP 服务器会自动释放 IP 地址。 

          apiVersion: apps/v1
      kind: DaemonSet
      metadata:
        name: set-dhcp-on-stop
      spec:
        selector:
          matchLabels:
            name: set-dhcp-on-stop
        template:
          metadata:
            labels:
              name: set-dhcp-on-stop
          spec:
            hostIPC: true
            hostPID: true
            hostNetwork: true
            containers:
            - name: set-dhcp-on-stop
              image: ubuntu
              tty: true
              command:
              - /bin/bash
              - -c
              - |
                set -x
                date
                while true; do
                  export CONFIG=/host/run/systemd/network/10-netplan-ens192.network;
                  grep KeepConfiguration=dhcp-on-stop "${CONFIG}" > /dev/null
                  if (( $? != 0 )) ; then
                    echo "Setting KeepConfiguration=dhcp-on-stop"
                    sed -i '/\[Network\]/a KeepConfiguration=dhcp-on-stop' "${CONFIG}"
                    cat "${CONFIG}"
                    chroot /host systemctl restart systemd-networkd
                  else
                    echo "KeepConfiguration=dhcp-on-stop has already been set"
                  fi;
                  sleep 3600
                done
              volumeMounts:
              - name: host
                mountPath: /host
              resources:
                requests:
                  memory: "10Mi"
                  cpu: "5m"
              securityContext:
                privileged: true
            volumes:
            - name: host
              hostPath:
                path: /
            tolerations:
            - operator: Exists
              effect: NoExecute
            - operator: Exists
              effect: NoSchedule

    运维、升级、更新 1.12.0-1.12.5、1.13.0-1.13.5、1.14.0-1.14.1

    此问题仅会影响从 1.11.x 版升级的管理员集群，不会影响 1.12 版之后新创建的管理员集群。

    将 1.11.x 版集群升级到 1.12.x 版后，admin-cluster-creds Secret 中的 component-access-sa-key 字段会被擦除为空。您可以通过运行以下命令进行检查： 

    kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get secret admin-cluster-creds -o yaml | grep 'component-access-sa-key'
     如果您发现输出为空，则表示密钥已被擦除。

    在组件访问服务账号密钥被删除后，安装新用户集群或升级现有用户集群将失败。下面列出了您可能会遇到的一些错误消息：

    • 缓慢验证预检失败，并显示错误消息："Failed to create the test VMs: failed to get service account key: service account is not configured."
    • gkectl prepare 准备失败，并显示错误消息："Failed to prepare OS images: dialing: unexpected end of JSON input"
    • 如果您在使用 Google Cloud 控制台或 gcloud CLI 升级 1.13 版用户集群，则在运行 gkectl update admin --enable-preview-user-cluster-central-upgrade 以部署升级平台控制器时，该命令会失败并显示以下消息："failed to download bundle to disk: dialing: unexpected end of JSON input"（您可以在 kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get onprembundle -oyaml 输出的 status 字段中看到此消息）。


    解决方法：

    通过运行以下命令，手动将组件访问服务账号密钥添加回 Secret： 

    kubectl --kubeconfig ADMIN_KUBECONFIG -n kube-system get secret admin-cluster-creds -ojson | jq --arg casa "$(cat COMPONENT_ACESS_SERVICE_ACOOUNT_KEY_PATH | base64 -w 0)" '.data["component-access-sa-key"]=$casa' | kubectl --kubeconfig ADMIN_KUBECONFIG apply -f -

    操作 1.13.0+、1.14.0+

    对于使用 Controlplane V2 或新的安装模型创建的用户集群，启用了自动扩缩功能的节点池始终使用其在 user-cluster.yaml 中的 autoscaling.minReplicas。集群自动扩缩器 pod 的日志还会显示其健康状况不佳。 

      > kubectl --kubeconfig $USER_CLUSTER_KUBECONFIG -n kube-system \
  logs $CLUSTER_AUTOSCALER_POD --container_cluster-autoscaler
 TIMESTAMP  1 gkeonprem_provider.go:73] error getting onpremusercluster ready status: Expected to get a onpremusercluster with id foo-user-cluster-gke-onprem-mgmt/foo-user-cluster
 TIMESTAMP 1 static_autoscaler.go:298] Failed to get node infos for groups: Expected to get a onpremusercluster with id foo-user-cluster-gke-onprem-mgmt/foo-user-cluster
    可以通过运行以下命令找到集群自动扩缩器 Pod。 
      > kubectl --kubeconfig $USER_CLUSTER_KUBECONFIG -n kube-system \
   get pods | grep cluster-autoscaler
cluster-autoscaler-5857c74586-txx2c                          4648017n    48076Ki    30s


    解决方法：

    使用“gkectl update cluster”停用所有节点池中的自动扩缩功能，直到升级到包含修复的版本
    安装 1.12.0-1.12.4、1.13.0-1.13.3、1.14.0

    当用户在 IP 地址块文件中使用 CIDR 时，配置验证将失败，并显示以下错误：

    - Validation Category: Config Check
    - [FAILURE] Config: AddressBlock for admin cluster spec is invalid: invalid IP:
172.16.20.12/30


    解决方法：

    将各个 IP 添加到 IP 地址块文件中，直到升级到包含修补程序的版本：1.12.5、1.13.4、1.14.1+。
    升级、更新 1.14.0-1.14.1

    在 admin-cluster.yaml 中更新控制平面操作系统映像类型时，如果其相应的用户集群是通过 Controlplane V2 创建的，则用户控制平面机器在 gkectl 命令完成时可能无法完成其重新创建。


    解决方法：

    更新完成后，使用 kubectl --kubeconfig USER_KUBECONFIG get nodes -owide 监控节点操作系统映像类型，从而继续等待用户控制平面机器也完成其重新创建。例如，如果从 Ubuntu 更新为 COS，则即使在更新命令完成后，也应该等待所有控制平面机器从 Ubuntu 完全更改为 COS。
    操作 1.10、1.11、1.12、1.13、1.14.0

    Google Distributed Cloud 1.14.0 中的 Calico 问题导致 Pod 创建和删除失败，并在 kubectl describe pods 的输出中显示以下错误消息：

      error getting ClusterInformation: connection is unauthorized: Unauthorized

    此问题仅在使用 Calico 创建集群或升级到 1.14 后的 24 小时内才会观察到。

    管理员集群始终使用 Calico，而对于用户集群，user-cluster.yaml 中有一个配置字段“enableDataPlaneV2”，如果该字段设置为“false”，或未指定该字段，则表示您在用户集群中使用 Calico。

    节点的 install-cni 容器使用有效期为 24 小时的令牌创建 kubeconfig。此令牌需要定期由 calico-node Pod 进行续订。calico-node Pod 无法续订此令牌，因为它无权访问节点上包含 kubeconfig 文件的目录。


    临时解决方法：

    此问题已在 Google Distributed Cloud 1.14.1 版中得到解决。请升级到此版本或更高版本。

    如果您无法立即升级，请在管理员集群和用户集群中对 calico-node DaemonSet 应用以下补丁：

      kubectl -n kube-system get daemonset calico-node \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG -o json \
    | jq '.spec.template.spec.containers[0].volumeMounts += [{"name":"cni-net-dir","mountPath":"/host/etc/cni/net.d"}]' \
    | kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f -

  kubectl -n kube-system get daemonset calico-node \
    --kubeconfig USER_CLUSTER_KUBECONFIG -o json \
    | jq '.spec.template.spec.containers[0].volumeMounts += [{"name":"cni-net-dir","mountPath":"/host/etc/cni/net.d"}]' \
    | kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f -
    替换以下内容：
    • ADMIN_CLUSTER_KUBECONFIG：管理员集群 kubeconfig 文件的路径。
    • USER_CLUSTER_CONFIG_FILE：用户集群配置文件的路径。
    安装 1.12.0-1.12.4、1.13.0-1.13.3、1.14.0

    尽管用户配置正确，集群创建仍然失败。用户看到由于集群没有足够的 IP 地址导致创建失败。


    解决方法：

    将 CIDR 拆分为几个较小的 CIDR 地址块，例如将 10.0.0.0/30 变为 10.0.0.0/31, 10.0.0.2/31。只要有 N+1 个 CIDR（其中 N 是集群中的节点数），就足以满足需求。
    运维、升级、更新 1.11.0 - 1.11.1、1.10.0 - 1.10.4 和 1.9.0 - 1.9.6

    启用始终开启的 Secret 加密功能并进行集群备份后，管理员集群备份将无法包含始终开启的 Secret 加密功能所需的加密密钥和配置。因此，使用 gkectl repair admin-master --restore-from-backup 通过此备份修复管理员主节点会导致以下错误：

    Validating admin master VM xxx ...
Waiting for kube-apiserver to be accessible via LB VIP (timeout "8m0s")...  ERROR
Failed to access kube-apiserver via LB VIP. Trying to fix the problem by rebooting the admin master
Waiting for kube-apiserver to be accessible via LB VIP (timeout "13m0s")...  ERROR
Failed to access kube-apiserver via LB VIP. Trying to fix the problem by rebooting the admin master
Waiting for kube-apiserver to be accessible via LB VIP (timeout "18m0s")...  ERROR
Failed to access kube-apiserver via LB VIP. Trying to fix the problem by rebooting the admin master

    运维、升级、更新 1.10+

    如果在创建集群时未启用始终开启的 Secret 加密功能，但之后使用 gkectl update 操作启用，则 gkectl repair admin-master 无法修复管理员集群控制平面节点。建议在创建集群时启用始终开启的 Secret 加密功能。当前没有缓解措施。
    升级、更新 1.10

    将第一个用户集群从 1.9 升级到 1.10 可能会在同一管理员集群下的其他用户集群中重新创建节点。重新创建是以滚动方式执行的。

    disk_label 已从 MachineTemplate.spec.template.spec.providerSpec.machineVariables 中移除，这意外触发了所有 MachineDeployment 的更新。


    临时解决方法：
    升级、更新 1.10.0

    将用户集群升级到 1.10.0 可能会导致 Docker 频繁重启。

    您可以通过运行 kubectl describe node NODE_NAME --kubeconfig USER_CLUSTER_KUBECONFIG 来检测此问题

    节点条件会显示 Docker 是否频繁重启。以下是示例输出：

    Normal   FrequentDockerRestart    41m (x2 over 141m)     systemd-monitor  Node condition FrequentDockerRestart is now: True, reason: FrequentDockerRestart

    如需了解根本原因，您需要通过 SSH 连接到存在该症状的节点，并运行 sudo journalctl --utc -u docker 或 sudo journalctl -x 等命令


    临时解决方法：
    升级、更新 1.11、1.12

    如果您使用的是低于 1.12 的 Google Distributed Cloud 版本，并且在集群的 gmp-system 命名空间中手动设置了 Google 管理的 Prometheus (GMP) 组件，则在升级到 1.12.x 版后，这些组件不会保留。

    从 1.12 版开始，gmp-system 命名空间中的 GMP 组件和 CRD 由 stackdriver 对象管理，并且 enableGMPForApplications 标志默认设置为 false。在升级到 1.12 之前，如果您在命名空间中手动部署了 GMP 组件，则 stackdriver 将删除这些资源。


    临时解决方法：
    操作 1.11、1.12、1.13.0 - 1.13.1

    在 system 场景中，集群快照不包括 default 命名空间下的任何资源。

    但是，此命名空间下的某些 Kubernetes 资源（如 Cluster API 对象）包含有用的调试信息。集群快照应包含这些信息。


    临时解决方法：

    您可以手动运行以下命令来收集调试信息。

    export KUBECONFIG=USER_CLUSTER_KUBECONFIG
kubectl get clusters.cluster.k8s.io -o yaml
kubectl get controlplanes.cluster.k8s.io -o yaml
kubectl get machineclasses.cluster.k8s.io -o yaml
kubectl get machinedeployments.cluster.k8s.io -o yaml
kubectl get machines.cluster.k8s.io -o yaml
kubectl get machinesets.cluster.k8s.io -o yaml
kubectl get services -o yaml
kubectl describe clusters.cluster.k8s.io
kubectl describe controlplanes.cluster.k8s.io
kubectl describe machineclasses.cluster.k8s.io
kubectl describe machinedeployments.cluster.k8s.io
kubectl describe machines.cluster.k8s.io
kubectl describe machinesets.cluster.k8s.io
kubectl describe services
     其中：

    USER_CLUSTER_KUBECONFIG 是用户集群的 kubeconfig 文件。
    升级、更新 1.11.0-1.11.4、1.12.0-1.12.3、1.13.0-1.13.1

    删除、更新或升级用户集群时，在以下情况下节点排空可能会停滞：

    • 从 1.12.x 版开始，管理员集群已在 vSAN 上使用 vSphere CSI 驱动程序，并且
    • 未在管理员集群和用户集群中通过树内 vSphere 插件创建 PVC/PV 对象。

    如需找出此症状，请运行以下命令：

    kubectl logs clusterapi-controllers-POD_NAME_SUFFIX  --kubeconfig ADMIN_KUBECONFIG -n USER_CLUSTER_NAMESPACE

    以下是来自上述命令的示例错误消息：

    E0920 20:27:43.086567 1 machine_controller.go:250] Error deleting machine object [MACHINE]; Failed to delete machine [MACHINE]: failed to detach disks from VM "[MACHINE]": failed to convert disk path "kubevols" to UUID path: failed to convert full path "ds:///vmfs/volumes/vsan:[UUID]/kubevols": ServerFaultCode: A general system error occurred: Invalid fault

    kubevols 是 vSphere 树内驱动程序的默认目录。如果未创建 PVC/PV 对象，您可能会遇到 bug，即节点排空在查找 kubevols 时停滞，因为当前实现假定 kubevols 始终存在。


    临时解决方法：

    在创建节点的数据存储区中创建 kubevols 目录。此操作在 user-cluster.yaml 或 admin-cluster.yaml 文件的 vCenter.datastore 字段中定义。
    配置 1.7、1.8、1.9、1.10、1.11、1.12、1.13、1.14

    删除用户集群时，集群自动扩缩器对应的 clusterrole 和 clusterrolebinding 也会被删除。这会影响启用了集群自动扩缩器的同一管理员集群上的所有其他用户集群。这是因为同一管理员集群中的所有集群自动扩缩器 Pod 都使用相同的 clusterrole 和 clusterrolebinding。

    症状如下：

    • cluster-autoscaler 日志
      • kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
cluster-autoscaler
       其中，ADMIN_CLUSTER_KUBECONFIG 是管理员集群的 kubeconfig 文件。 以下是您可能会看到的错误消息示例：
      2023-03-26T10:45:44.866600973Z W0326 10:45:44.866463       1 reflector.go:424] k8s.io/client-go/dynamic/dynamicinformer/informer.go:91: failed to list *unstructured.Unstructured: onpremuserclusters.onprem.cluster.gke.io is forbidden: User "..." cannot list resource "onpremuserclusters" in API group "onprem.cluster.gke.io" at the cluster scope
2023-03-26T10:45:44.866646815Z E0326 10:45:44.866494       1 reflector.go:140] k8s.io/client-go/dynamic/dynamicinformer/informer.go:91: Failed to watch *unstructured.Unstructured: failed to list *unstructured.Unstructured: onpremuserclusters.onprem.cluster.gke.io is forbidden: User "..." cannot list resource "onpremuserclusters" in API group "onprem.cluster.gke.io" at the cluster scope

    临时解决方法：

    配置 1.7、1.8、1.9、1.10、1.11、1.12、1.13

    删除用户集群时，相应的 clusterrole 也会被删除，从而导致自动修复和 vSphere 指标导出器无法正常工作

    症状如下：

    • cluster-health-controller 日志
      • kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
cluster-health-controller
       其中，ADMIN_CLUSTER_KUBECONFIG 是管理员集群的 kubeconfig 文件。 以下是您可能会看到的错误消息示例：
      error retrieving resource lock default/onprem-cluster-health-leader-election: configmaps "onprem-cluster-health-leader-election" is forbidden: User "system:serviceaccount:kube-system:cluster-health-controller" cannot get resource "configmaps" in API group "" in the namespace "default": RBAC: clusterrole.rbac.authorization.k8s.io "cluster-health-controller-role" not found
    • vsphere-metrics-exporter 日志
      • kubectl logs --kubeconfig ADMIN_CLUSTER_KUBECONFIG -n kube-system \
vsphere-metrics-exporter
       其中，ADMIN_CLUSTER_KUBECONFIG 是管理员集群的 kubeconfig 文件。 以下是您可能会看到的错误消息示例：
      vsphere-metrics-exporter/cmd/vsphere-metrics-exporter/main.go:68: Failed to watch *v1alpha1.Cluster: failed to list *v1alpha1.Cluster: clusters.cluster.k8s.io is forbidden: User "system:serviceaccount:kube-system:vsphere-metrics-exporter" cannot list resource "clusters" in API group "cluster.k8s.io" in the namespace "default"

    临时解决方法：

    配置 1.12.1-1.12.3、1.13.0-1.13.2

    一个可能会在不运行 gkectl prepare 的情况下使 gkectl check-config 失败的已知问题。这会造成混淆，因为我们建议在运行 gkectl prepare 之前运行该命令。

    症状是 gkectl check-config 命令将失败，并显示以下错误消息：

    Validator result: {Status:FAILURE Reason:os images [OS_IMAGE_NAME] don't exist, please run `gkectl prepare` to upload os images. UnhealthyResources:[]}

    临时解决方法：

    方法 1：运行 gkectl prepare 以上传缺少的操作系统映像。

    方法 2：使用 gkectl check-config --skip-validation-os-images 跳过操作系统映像验证。
    升级、更新 1.11、1.12、1.13

    一个可能会在更新 anti affinity groups 时使 gkectl update admin/cluster 失败的已知问题。

    症状是 gkectl update 命令将失败，并显示以下错误消息：

    Waiting for machines to be re-deployed...  ERROR
Exit with error:
Failed to update the cluster: timed out waiting for the condition

    临时解决方法：
    安装、升级、更新 1.13.0-1.13.8、1.14.0-1.14.4、1.15.0

    在集群创建、升级、更新和节点自动修复期间，如果 ipMode.type 为 static 且 IP 地址块文件中配置的主机名包含一个或多个英文句点，则节点注册会失败。在这种情况下，节点的证书签名请求 (CSR) 不会自动获得批准。

    如需查看节点的待处理 CSR，请运行以下命令：

    kubectl get csr -A -o wide

    查看以下日志以获取错误消息：

    • 在管理员集群中查看 clusterapi-controllers Pod 中 clusterapi-controller-manager 容器的日志：
      kubectl logs clusterapi-controllers-POD_NAME \
    -c clusterapi-controller-manager -n kube-system \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG
    • 如需在用户集群中查看相同的日志，请运行以下命令：
      kubectl logs clusterapi-controllers-POD_NAME \
    -c clusterapi-controller-manager -n USER_CLUSTER_NAME \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG
       其中：
      • ADMIN_CLUSTER_KUBECONFIG 是管理员集群的 kubeconfig 文件。
      • USER_CLUSTER_NAME 是用户集群的名称。
      以下是您可能会看到的错误消息示例："msg"="failed to validate token id" "error"="failed to find machine for node node-worker-vm-1" "validate"="csr-5jpx9"
    • 查看有问题的节点上的 kubelet 日志：
      journalctl --u kubelet
       以下是您可能会看到的错误消息示例："Error getting node" err="node \"node-worker-vm-1\" not found"

    如果您在 IP 地址块文件的主机名字段中指定域名，则第一个英文句点后面的任何字符都将被忽略。例如，如果您将主机名指定为 bob-vm-1.bank.plc，则虚拟机主机名和节点名称将设置为 bob-vm-1。

    启用节点 ID 验证后，CSR 审批人会将节点名称与机器规范中的主机名进行比较，并且无法协调名称。审批人拒绝 CSR，节点引导失败。


    临时解决方法：

    用户集群

    通过完成以下步骤停用节点 ID 验证：

    1. 在用户集群配置文件中添加以下字段：
      disableNodeIDVerification: true
disableNodeIDVerificationCSRSigning: true
    2. 保存文件，然后运行以下命令来更新用户集群：
      gkectl update cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG_FILE
       替换以下内容：
      • ADMIN_CLUSTER_KUBECONFIG：管理员集群 kubeconfig 文件的路径。
      • USER_CLUSTER_CONFIG_FILE：用户集群配置文件的路径。

    管理员集群

    1. 打开 OnPremAdminCluster 自定义资源进行修改：
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    edit onpremadmincluster -n kube-system
    2. 将以下注解添加到自定义资源：
      features.onprem.cluster.gke.io/disable-node-id-verification: enabled
    3. 修改管理员集群控制平面中的 kube-controller-manager 清单：
      1. 通过 SSH 连接到管理员集群控制平面节点。
      2. 打开 kube-controller-manager 清单进行修改：
        sudo vi /etc/kubernetes/manifests/kube-controller-manager.yaml
      3. 找到 controllers 的列表：
        --controllers=*,bootstrapsigner,tokencleaner,-csrapproving,-csrsigning
      4. 按如下所示更新此部分：
        --controllers=*,bootstrapsigner,tokencleaner
    4. 打开 Deployment Cluster API 控制器进行修改：
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    edit deployment clusterapi-controllers -n kube-system
    5. 将 node-id-verification-enabled 和 node-id-verification-csr-signing-enabled 的值更改为 false：
      --node-id-verification-enabled=false
--node-id-verification-csr-signing-enabled=false
    安装、升级、更新 1.11.0-1.11.4

    管理员集群创建/升级操作永远卡在以下日志，并最终超时：

    Waiting for Machine gke-admin-master-xxxx to become ready...

    外部集群快照中的 Cluster API 控制器日志包含以下日志：

    Invalid value 'XXXX' specified for property startup-data

    以下是 Cluster API 控制器日志的示例文件路径：

    kubectlCommands/kubectl_logs_clusterapi-controllers-c4fbb45f-6q6g6_--container_vsphere-controller-manager_--kubeconfig_.home.ubuntu..kube.kind-config-gkectl_--request-timeout_30s_--namespace_kube-system_--timestamps
    
    VMware has a 64k vApp property size limit. In the identified versions,
    the data passed via vApp property is close to the limit. When the private
    registry certificate contains a certificate bundle, it may cause the final
    data to exceed the 64k limit.
    
    
    Workaround:
    
    
    Only include the required certificates in the private registry
    certificate file configured in privateRegistry.caCertPath in
    the admin cluster config file.
    
    
    Or upgrade to a version with the fix when available.
    Networking 1.10, 1.11.0-1.11.3, 1.12.0-1.12.2, 1.13.0

    In networkgatewaygroups.status.nodes, some nodes switch between NotHealthy and Up.

    Logs for the ang-daemon Pod running on that node reveal repeated errors: 

    2022-09-16T21:50:59.696Z ERROR ANGd Failed to report status {"angNode": "kube-system/my-node", "error": "updating Node CR status: sending Node CR update: Operation cannot be fulfilled on networkgatewaynodes.networking.gke.io \"my-node\": the object has been modified; please apply your changes to the latest version and try again"}

    NotHealthy 状态会阻止控制器为该节点分配额外的浮动 IP。这可能会导致其他节点上的负担更重，或者缺乏实现高可用性的冗余。

    数据平面活动不受影响。

    networkgatewaygroup 对象的争用导致某些状态更新由于重试处理故障而失败。如果过多的状态更新失败，ang-controller-manager 会将节点视为超过其检测信号时间限制，并将节点标记为 NotHealthy。

    重试处理故障在更高版本中已得到修复。


    临时解决方法：

    升级到固定版本（如有）。
    升级、更新 1.12.0-1.12.2、1.13.0

    一个可能会导致集群升级或更新在等待旧机器对象删除时停滞的已知问题。这是因为终结器无法从该机器对象中移除。这会影响节点池的任何滚动更新操作。

    问题是 gkectl 命令超时，并显示以下错误消息：

    E0821 18:28:02.546121   61942 console.go:87] Exit with error:
E0821 18:28:02.546184   61942 console.go:87] error: timed out waiting for the condition, message: Node pool "pool-1" is not ready: ready condition is not true: CreateOrUpdateNodePool: 1/3 replicas are updated
Check the status of OnPremUserCluster 'cluster-1-gke-onprem-mgmt/cluster-1' and the logs of pod 'kube-system/onprem-user-cluster-controller' for more detailed debugging information.

    在 clusterapi-controller Pod 日志中，错误如下所示：

    $ kubectl logs clusterapi-controllers-[POD_NAME_SUFFIX] -n cluster-1
    -c vsphere-controller-manager --kubeconfig [ADMIN_KUBECONFIG]
    | grep "Error removing finalizer from machine object"
[...]
E0821 23:19:45.114993       1 machine_controller.go:269] Error removing finalizer from machine object cluster-1-pool-7cbc496597-t5d5p; Operation cannot be fulfilled on machines.cluster.k8s.io "cluster-1-pool-7cbc496597-t5d5p": the object has been modified; please apply your changes to the latest version and try again

    即使没有这个问题，对于成功运行的同一台机器，错误也会重复几分钟，在大多数情况下它可以快速通过，但在极少数情况下，它可能会在这种竞态条件下卡住几个小时。

    问题是 vCenter 中已经删除了底层虚拟机，但无法移除相应的机器对象，由于其他控制器的更新非常频繁，因此操作在移除终结器时卡住了。这可能会导致 gkectl 命令超时，但控制器会继续协调集群，因此升级或更新过程最终会完成。


    临时解决方法：

    我们为此问题准备了几种不同的缓解方法，具体取决于您的环境和要求。

    • 方法 1：等待升级最终自行完成。

      根据环境中的分析和重现，升级最终可以自行完成，无需任何人工干预。请注意，此方法无法确定每个机器对象完成终结器移除需要多长时间。如果足够幸运，移除操作可以立即完成，或者如果机器集控制器协调太快并且机器控制器永远无法在协调之间移除终结器，该操作可能会持续几个小时。

      此方法的优点是，您不需要执行任何操作，而且工作负载不会中断。它只需要较长时间来完成升级而已。
    • 方法 2：将自动修复注解应用于所有旧机器对象。

      机器集控制器将过滤掉包含自动修复注解和删除时间戳非零的机器，并且不会继续在这些机器上发出删除调用，这有助于避免出现竞态条件。

      其缺点是机器上的 pod 会直接被删除而不是被逐出，意味着它不会遵循 PDB 配置，这可能会导致工作负载停机。

      用于获取所有机器名称的命令：
      kubectl --kubeconfig CLUSTER_KUBECONFIG get machines
       用于为每个机器应用自动修复注解的命令： 
      kubectl annotate --kubeconfig CLUSTER_KUBECONFIG \
    machine MACHINE_NAME \
    onprem.cluster.gke.io/repair-machine=true

    如果您遇到此问题，并且升级或更新在一段较长的时间后仍然无法完成，请与我们的支持团队联系以获取缓解措施。
    安装、升级、更新 1.10.2、1.11、1.12、1.13

    gkectl prepare 命令失败，并显示以下内容：

    - Validation Category: OS Images
    - [FAILURE] Admin cluster OS images exist: os images [os_image_name] don't exist, please run `gkectl prepare` to upload os images.

    gkectl prepare 的预检检查包含不正确的验证。


    临时解决方法：

    运行相同的命令，并附加 --skip-validation-os-images 标志。
    安装 1.7、1.8、1.9、1.10、1.11、1.12、1.13

    管理员集群创建失败，并显示以下内容：

    Exit with error:
Failed to create root cluster: unable to apply admin base bundle to external cluster: error: timed out waiting for the condition, message:
Failed to apply external bundle components: failed to apply bundle objects from admin-vsphere-credentials-secret 1.x.y-gke.z to cluster external: Secret "vsphere-dynamic-credentials" is invalid:
[data[https://xxx.xxx.xxx.username]: Invalid value: "https://xxx.xxx.xxx.username": a valid config key must consist of alphanumeric characters, '-', '_' or '.'
(e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+'), data[https://xxx.xxx.xxx.password]:
Invalid value: "https://xxx.xxx.xxx.password": a valid config key must consist of alphanumeric characters, '-', '_' or '.'
(e.g. 'key.name', or 'KEY_NAME', or 'key-name', regex used for validation is '[-._a-zA-Z0-9]+')]

    该网址用作 Secret 密钥的一部分，不支持“/”或“:”。


    临时解决方法：

    从管理员集群或用户集群配置 yaml 的 vCenter.Address 字段中移除 https:// 或 http:// 前缀。
    安装、升级、更新 1.10、1.11、1.12、1.13

    gkectl prepare 可能会崩溃，相应的堆栈跟踪记录如下：

    panic: runtime error: invalid memory address or nil pointer dereference [signal SIGSEGV: segmentation violation code=0x1 addr=0x18 pc=0xde0dfa]

goroutine 1 [running]:
gke-internal.googlesource.com/syllogi/cluster-management/pkg/util.CheckFileExists(0xc001602210, 0x2b, 0xc001602210, 0x2b) pkg/util/util.go:226 +0x9a
gke-internal.googlesource.com/syllogi/cluster-management/gkectl/pkg/config/util.SetCertsForPrivateRegistry(0xc000053d70, 0x10, 0xc000f06f00, 0x4b4, 0x1, 0xc00015b400)gkectl/pkg/config/util/utils.go:75 +0x85
...

    问题是 gkectl prepare 使用错误的权限创建了专用注册表证书目录。


    临时解决方法：

    如需解决此问题，请在管理员工作站上运行以下命令：

    sudo mkdir -p /etc/docker/certs.d/PRIVATE_REGISTRY_ADDRESS
sudo chmod 0755 /etc/docker/certs.d/PRIVATE_REGISTRY_ADDRESS
    升级、更新 1.10、1.11、1.12、1.13

    管理员集群升级失败后，请不要运行 gkectl repair admin-master。这样做可能会导致后续管理员集群升级尝试失败，并出现管理员集群主节点开启失败或虚拟机无法访问等问题。


    临时解决方法：

    如果您已经遇到此失败场景，请与支持团队联系。
    升级、更新 1.10、1.11

    如果在尝试恢复管理员集群升级后未重新创建管理员控制平面机器，管理员控制平面虚拟机模板会被删除。管理员控制平面虚拟机模板是管理员主节点的模板，用于通过 gkectl repair admin-master 恢复控制平面机器。


    临时解决方法：

    管理员控制平面虚拟机模板将在下一次管理员集群升级期间重新生成。
    操作系统 1.12、1.13

    在 1.12.0 版中，系统默认会为 Container-Optimized OS (COS) 节点启用 cgroup v2（统一）。这可能会导致 COS 集群中的工作负载不稳定。


    临时解决方法：

    我们在 1.12.1 版中切换回 cgroup v1 (Hybrid)。如果您使用的是 COS 节点，我们建议您在 1.12.1 版发布后尽快升级到该版本。
    身份 1.10、1.11、1.12、1.13

    gkectl update 会还原您对 ClientConfig 自定义资源所做的所有手动更改。


    临时解决方法：

    我们强烈建议您在每次手动更改后备份 ClientConfig 资源。
    安装 1.10、1.11、1.12、1.13

    验证失败，因为找不到 F5 BIG-IP 分区（即使该分区存在）。

    F5 BIG-IP API 的问题可能会导致验证失败。


    临时解决方法：

    尝试再次运行 gkectl check-config。
    安装 1.12

    如果 apiserver/etcd 速度缓慢，您可能会看到由于 cert-manager-cainjector 出现崩溃循环而导致安装失败：

    # These are logs from `cert-manager-cainjector`, from the command
# `kubectl --kubeconfig USER_CLUSTER_KUBECONFIG -n kube-system
  cert-manager-cainjector-xxx`

I0923 16:19:27.911174       1 leaderelection.go:278] failed to renew lease kube-system/cert-manager-cainjector-leader-election: timed out waiting for the condition

E0923 16:19:27.911110       1 leaderelection.go:321] error retrieving resource lock kube-system/cert-manager-cainjector-leader-election-core:
  Get "https://10.96.0.1:443/api/v1/namespaces/kube-system/configmaps/cert-manager-cainjector-leader-election-core": context deadline exceeded

I0923 16:19:27.911593       1 leaderelection.go:278] failed to renew lease kube-system/cert-manager-cainjector-leader-election-core: timed out waiting for the condition

E0923 16:19:27.911629       1 start.go:163] cert-manager/ca-injector "msg"="error running core-only manager" "error"="leader election lost"

    临时解决方法：
    VMware 1.10、1.11、1.12、1.13

    如果版本低于 7.0U2 的 vCenter 在升级之后或其他情况下重启，则 vCenter 的虚拟机信息中的网络名称将变得不正确，导致机器处于 Unavailable 状态。这最终会使节点自动修复以创建新节点。

    相关的 govmomi bug。


    临时解决方法：

    此解决方法由 VMware 支持团队提供：

    1. 此问题已在 vCenter 7.0U2 及更高版本中得到修复。
    2. 对于较低版本，请右键点击主机，然后选择连接 > 断开连接。接下来，重新连接，这会强制更新虚拟机的端口组。
    操作系统 1.10、1.11、1.12、1.13

    对于 Google Distributed Cloud 1.7.2 及更高版本，Ubuntu 操作系统映像通过 CIS L1 Server Benchmark 进行了安全强化。

    为满足 CIS 规则“5.2.16 确保已配置 SSH 空闲超时间隔”，/etc/ssh/sshd_config 具有以下设置：

    ClientAliveInterval 300
ClientAliveCountMax 0

    这些设置的目的是在空闲 5 分钟后终止客户端会话。但是，ClientAliveCountMax 0 值会导致意外行为。在管理员工作站或集群节点上使用 SSH 会话时，即使 SSH 客户端不处于空闲状态（例如在运行耗时的命令时），SSH 连接也可能会断开，命令可能会终止并显示以下消息：

    Connection to [IP] closed by remote host.
Connection to [IP] closed.

    临时解决方法：

    您可以执行以下任一项操作：

    • 使用 nohup 防止命令在 SSH 断开连接时终止，
      nohup gkectl upgrade admin --config admin-cluster.yaml \
    --kubeconfig kubeconfig
    • 更新 sshd_config 以使用非零 ClientAliveCountMax 值。CIS 规则建议使用小于 3 的值：
      sudo sed -i 's/ClientAliveCountMax 0/ClientAliveCountMax 1/g' \
    /etc/ssh/sshd_config
sudo systemctl restart sshd

    请确保重新连接 SSH 会话。
    安装 1.10、1.11、1.12、1.13

    在 1.13 版本中，monitoring-operator 会在 cert-manager 命名空间中安装 cert-manager。如果由于某些原因您需要安装自己的 cert-manager，请按照以下说明操作以避免冲突：

    您只需要对每个集群应用一次这个解决方法，并且更改在集群升级后会保留。

    注意：安装您自己的 cert-manager 的一个常见症状是 cert-manager 版本或映像（例如 v1.7.2）可能会还原为旧版本。这是由于 monitoring-operator 尝试协调 cert-manager 并在此过程中还原版本引起的。

    临时解决方法：

    <p避免升级期间发生冲突

    1. 卸载您的 cert-manager 版本。如果您定义了自己的资源，建议您备份这些资源。
    2. 执行升级。
    3. 按照以下说明恢复您自己的 cert-manager。

    在用户集群中恢复您自己的 cert-manager

    • 将 monitoring-operator 部署调节为 0：
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n USER_CLUSTER_NAME \
    scale deployment monitoring-operator --replicas=0
    • 将 monitoring-operator 管理的 cert-manager 部署调节为 0：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager --replicas=0
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager-cainjector\
    --replicas=0
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager-webhook --replicas=0
    • 重新安装您的 cert-manager 版本。 恢复自定义资源（如果有）。
    • 如果您使用的是上游默认 cert-manager 安装，或者确定 cert-manager 已安装在 cert-manager 命名空间中，则可以跳过此步骤。否则，将 metrics-ca cert-manager.io/v1 证书和 metrics-pki.cluster.local 颁发者资源从 cert-manager 复制到已安装的 cert-manager 的集群资源命名空间。
      relevant_fields='
{
  apiVersion: .apiVersion,
  kind: .kind,
  metadata: {
    name: .metadata.name,
    namespace: "YOUR_INSTALLED_CERT_MANAGER_NAMESPACE"
  },
  spec: .spec
}
'
f1=$(mktemp)
f2=$(mktemp)
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get issuer -n cert-manager metrics-pki.cluster.local -o json \
    | jq "${relevant_fields}" > $f1
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get certificate -n cert-manager metrics-ca -o json \
    | jq "${relevant_fields}" > $f2
kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f $f1
kubectl apply --kubeconfig USER_CLUSTER_KUBECONFIG -f $f2

    在管理员集群中恢复您自己的 cert-manager

    通常，您无需在管理员集群中重新安装 cert-manager，因为管理员集群仅运行 Google Distributed Cloud 控制平面工作负载。在极少数情况下，您还需要在管理员集群中安装自己的 cert-manager，请按照以下说明操作以避免冲突。请注意，如果您是 Apigee 客户，并且只需要在 Apigee 中使用 cert-manager，则无需运行管理员集群命令。

    • 将 monitoring-operator 部署调节为 0。
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n kube-system scale deployment monitoring-operator --replicas=0
    • 将 monitoring-operator 管理的 cert-manager 部署调节为 0。
      kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager \
    --replicas=0

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
     -n cert-manager scale deployment cert-manager-cainjector \
     --replicas=0

kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    -n cert-manager scale deployment cert-manager-webhook \
    --replicas=0
    • 重新安装您的 cert-manager 版本。 恢复自定义资源（如果有）。
    • 如果您使用的是上游默认 cert-manager 安装，或者确定 cert-manager 已安装在 cert-manager 命名空间中，则可以跳过此步骤。否则，将 metrics-ca cert-manager.io/v1 证书和 metrics-pki.cluster.local 颁发者资源从 cert-manager 复制到已安装的 cert-manager 的集群资源命名空间。
      relevant_fields='
{
  apiVersion: .apiVersion,
  kind: .kind,
  metadata: {
    name: .metadata.name,
    namespace: "YOUR_INSTALLED_CERT_MANAGER_NAMESPACE"
  },
  spec: .spec
}
'
f3=$(mktemp)
f4=$(mktemp)
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \n
    get issuer -n cert-manager metrics-pki.cluster.local -o json \
    | jq "${relevant_fields}" > $f3
kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    get certificate -n cert-manager metrics-ca -o json \
    | jq "${relevant_fields}" > $f4
kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f $f3
kubectl apply --kubeconfig ADMIN_CLUSTER_KUBECONFIG -f $f4
    </p
    操作系统 1.10、1.11、1.12、1.13

    Google Distributed Cloud 附带的 Ubuntu 操作系统映像中的 Docker、containerd 和 runc 使用 Ubuntu PPA 固定到特殊版本。这可确保 Google Distributed Cloud 在每个版本之前限定所有容器运行时更改。

    但是，Ubuntu CVE Tracker（用作各种 CVE 扫描工具的漏洞 Feed）并不知道特殊版本。因此，您将在 Docker、containerd 和 runc 漏洞扫描结果中看到误报。

    例如，您可能会在 CVE 扫描结果中看到以下误报。这些 CVE 已在 Google Distributed Cloud 的最新补丁版本中修复。

    如需了解任何 CVE 修复，请参阅版本说明。


    临时解决方法：

    Canonical 已注意到该问题，并且在 https://github.com/canonical/sec-cvescan/issues/73 对修复进行了跟踪。
    升级、更新 1.10、1.11、1.12、1.13

    如果要将非 HA 集群从 1.9 升级到 1.10，您可能会注意到针对用户集群的 kubectl exec、kubectl log 和 webhook 可能短时间内不可用。此停机时间可能长达一分钟。这是因为传入请求（kubectl exec、kubectl log 和 webhook）由用户集群的 kube-apiserver 处理。用户 kube-apiserver 是一个 Statefulset。在非 HA 集群中，Statefulset 只有一个副本。因此在升级期间，可能会出现旧的 kube-apiserver 不可用，而新的 kube-apiserver 尚未就绪的情况。


    临时解决方法：

    此停机仅在升级过程中发生。如果您希望缩短升级期间的停机时间，我们建议您切换回 HA 集群。
    安装、升级、更新 1.10、1.11、1.12、1.13

    如果您要创建或升级 HA 集群，并发现集群诊断中的 konnectivity 就绪性检查失败，在大多数情况下，这不会影响 Google Distributed Cloud 的功能（kubectl exec、kubectl log 和 webhook）。发生这种情况的原因是，由于网络不稳定或其他问题，有时一个或两个 konnectivity 副本可能在一段时间内无法就绪。


    临时解决方法：

    konnectivity 会自行恢复。等待 30 分钟到 1 小时，并重新运行集群诊断。
    操作系统 1.7、1.8、1.9、1.10、1.11

    从 Google Distributed Cloud 1.7.2 版开始，Ubuntu 操作系统映像通过 CIS L1 Server Benchmark 进行了安全强化。

    因此，安装了 cron 脚本 /etc/cron.daily/aide，以便安排 aide 检查，从而确保遵循 CIS L1 服务器规则“1.4.2 确保定期检查文件系统完整性”。

    Cron 作业每天的运行时间为世界协调时间 (UTC) 上午 6:25。根据文件系统上的文件数，您可能会在该时间前后遇到由此 aide 进程引起的 CPU 和内存用量激增。


    临时解决方法：

    如果激增影响了您的工作负载，您可以停用每日 Cron 作业：

    sudo chmod -x /etc/cron.daily/aide
    网络 1.10、1.11、1.12、1.13

    部署 Google Distributed Cloud 1.9 版或更高版本时，如果部署在使用 NSX-T 有状态分布式防火墙规则的环境中具有 Seesaw 捆绑负载均衡器，则 stackdriver-operator 可能无法创建 gke-metrics-agent-conf ConfigMap 并会导致 gke-connect-agent Pod 进入崩溃循环。

    潜在的问题是，有状态的 NSX-T 分布式防火墙规则通过 Seesaw 负载均衡器终止从客户端到用户集群 API 服务器的连接，因为 Seesaw 使用非对称连接流。NSX-T 分布式防火墙规则的集成问题会影响所有使用 Seesaw 的 Google Distributed Cloud 版本。当您自己的应用创建大小超过 32K 的大型 Kubernetes 对象时，您可能会在该应用中看到类似的连接问题。


    临时解决方法：

    按照相关说明停用 NSX-T 分布式防火墙规则，或者将无状态分布式防火墙规则用于 Seesaw 虚拟机。

    如果您的集群使用手动负载均衡器，请按照相关说明配置负载均衡器，使其在检测到后端节点故障时重置客户端连接。如果没有此配置，Kubernetes API 服务器的客户端可能会在服务器实例发生故障时停止响应几分钟。
    日志记录和监控 1.10、1.11、1.12、1.13、1.14、1.15

    对于 Google Distributed Cloud 1.10 至 1.15 版，一些客户会发现结算页面上的 Metrics volume 费用超出预期。只有在同时满足以下所有条件时，此问题才会对您产生影响：

    • 已启用应用日志记录和监控功能 (enableStackdriverForApplications=true)
    • 应用 Pod 具有 prometheus.io/scrap=true 注解。（安装 Cloud Service Mesh 也可以添加此注解。）

    如需确认您是否受此问题影响，请列出您的用户定义的指标。如果您看到针对具有 external.googleapis.com/prometheus 名称前缀的不需要的指标的计费，并且在 kubectl -n kube-system get stackdriver stackdriver -o yaml 的响应中看到 enableStackdriverForApplications 设置为 true，则表示此问题适用于您。


    临时解决方法

    如果您受到此问题的影响，我们建议您将集群升级到 1.12 版或更高版本，停止使用 enableStackdriverForApplications 标志，并切换到新的应用监控解决方案 managed-service-for-prometheus，它不再依赖于 prometheus.io/scrap=true 注解。在新解决方案中，您还可以使用 enableCloudLoggingForApplications 和 enableGMPForApplications 标志分别控制应用的日志和指标收集。

    如需停止使用 enableStackdriverForApplications 标志，请打开“stackdriver”对象进行修改：

    kubectl --kubeconfig=USER_CLUSTER_KUBECONFIG --namespace kube-system edit stackdriver stackdriver

    移除 enableStackdriverForApplications: true 行，保存并关闭编辑器。

    如果您无法停用基于注解的指标收集，请按以下步骤操作：

    1. 找到具有不需要的计费指标的来源 Pod 和 Service。 
      kubectl --kubeconfig KUBECONFIG \
  get pods -A -o yaml | grep 'prometheus.io/scrape: "true"'
kubectl --kubeconfig KUBECONFIG get \
  services -A -o yaml | grep 'prometheus.io/scrape: "true"'
    2. 从 Pod 或 Service 中移除 prometheus.io/scrap=true 注解。 如果注解由 Cloud Service Mesh 添加，请考虑在不使用 Prometheus 选项的情况下配置 Cloud Service Mesh，或关闭 Istio 指标合并功能。
    安装 1.11、1.12、1.13

    如果在错误的权限级层绑定自定义角色，Google Distributed Cloud 安装程序可能会失败。

    如果角色绑定不正确，使用 govc 创建 vSphere 数据磁盘会挂起并且创建的磁盘的大小为 0。如需解决此问题，您应在 vSphere vCenter 级层（根）绑定自定义角色。


    临时解决方法：

    如果您要在 DC 级层（或低于根的级层）绑定自定义角色，还需要在 vCenter 根级层将只读角色绑定到用户。

    如需详细了解角色创建，请参阅 vCenter 用户账号权限。
    日志记录和监控 1.9.0-1.9.4、1.10.0-1.10.1

    您可能会看到流向 monitoring.googleapis.com 的网络流量很高，即使在没有用户工作负载的新集群中也是如此。

    此问题会影响 1.10.0-1.10.1 和 1.9.0-1.9.4 版。此问题已在 1.10.2 和 1.9.5 版中得到解决。


    临时解决方法：
    日志记录和监控 1.10、1.11

    对于 Google Distributed Cloud 1.10 版及更高版本，如果“stackdriver”对象中的“enableStackdriverForApplications”设置为“true”，“gke-metrics-agent”DaemonSet 会经常出现 CrashLoopBackOff 错误。


    临时解决方法：

    为了缓解此问题，请运行以下命令来停用应用指标收集。这些命令不会停用应用日志收集。

    1. 为防止后续更改还原，请缩容 stackdriver-operator：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system scale deploy stackdriver-operator \
    --replicas=0
       将 USER_CLUSTER_KUBECONFIG 替换为用户集群 kubeconfig 文件的路径。
    2. 打开 gke-metrics-agent-conf ConfigMap 进行修改： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit configmap gke-metrics-agent-conf
    3. 在 services.pipelines 下，注释掉整个 metrics/app-metrics 部分：
      services:
  pipelines:
    #metrics/app-metrics:
    #  exporters:
    #  - googlecloud/app-metrics
    #  processors:
    #  - resource
    #  - metric_to_resource
    #  - infer_resource
    #  - disk_buffer/app-metrics
    #  receivers:
    #  - prometheus/app-metrics
    metrics/metrics:
      exporters:
      - googlecloud/metrics
      processors:
      - resource
      - metric_to_resource
      - infer_resource
      - disk_buffer/metrics
      receivers:
      - prometheus/metrics
    4. 关闭修改会话。
    5. 重启 gke-metrics-agent DaemonSet： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system rollout restart daemonset gke-metrics-agent
    日志记录和监控 1.11、1.12、1.13

    如果 OOTB 信息中心内使用了已弃用的指标，您将看到一些空图表。如需在 Monitoring 信息中心内查找已弃用的指标，请运行以下命令：

    gcloud monitoring dashboards list > all-dashboard.json

# find deprecated metrics
cat all-dashboard.json | grep -E \
  'kube_daemonset_updated_number_scheduled\
    |kube_node_status_allocatable_cpu_cores\
    |kube_node_status_allocatable_pods\
    |kube_node_status_capacity_cpu_cores'

    以下已弃用的指标应迁移到其对应的替代指标。

    已弃用替换
    kube_daemonset_updated_number_scheduled kube_daemonset_status_updated_number_scheduled
    kube_node_status_allocatable_cpu_cores
    kube_node_status_allocatable_memory_bytes
    kube_node_status_allocatable_pods    		 kube_node_status_allocatable
    kube_node_status_capacity_cpu_cores
    kube_node_status_capacity_memory_bytes
    kube_node_status_capacity_pods    		 kube_node_status_capacity
    kube_hpa_status_current_replicas kube_horizontalpodautoscaler_status_current_replicas

    临时解决方法：

    替换已弃用的指标

    1. 删除 Google Cloud Monitoring 信息中心内的“GKE On-Prem 节点状态”。请按照相关说明重新安装“GKE On-Prem 节点状态”。
    2. 删除 Google Cloud Monitoring 信息中心内的“GKE On-Prem 节点利用率”。请按照相关说明重新安装“GKE On-Prem 节点利用率”。
    3. 删除 Google Cloud Monitoring 信息中心内的“GKE On-Prem vSphere 虚拟机健康状况”。请按照相关说明重新安装“GKE On-Prem vSphere 虚拟机健康状况”。

      4. 此弃用行为是由于 kube-state-metrics 代理从 v1.9 升级到 v2.4（Kubernetes 1.22 要求进行此升级）引起的。您可以替换自定义信息中心或提醒政策中所有已弃用的 kube-state-metrics 指标（具有 kube_ 前缀）。
    日志记录和监控 1.10、1.11、1.12、1.13

    对于 Google Distributed Cloud 1.10 及更高版本，Cloud Monitoring 中集群的数据可能包含如下不相关的摘要指标条目：

    Unknown metric: kubernetes.io/anthos/go_gc_duration_seconds_summary_percentile

    其他可能具有不相关的摘要指标的指标类型包括

    ：
    • apiserver_admission_step_admission_duration_seconds_summary
    • go_gc_duration_seconds
    • scheduler_scheduling_duration_seconds
    • gkeconnect_http_request_duration_seconds_summary
    • alertmanager_nflog_snapshot_duration_seconds_summary

    虽然这些摘要类型指标在指标列表中，但 gke-metrics-agent 目前不支持这些指标。
    日志记录和监控 1.10、1.11、1.12、1.13

    您可能会发现部分（但不是全部）节点上缺少以下指标：

    • kubernetes.io/anthos/container_memory_working_set_bytes
    • kubernetes.io/anthos/container_cpu_usage_seconds_total
    • kubernetes.io/anthos/container_network_receive_bytes_total

    临时解决方法：

    如需解决此问题，请执行以下步骤作为解决方法。对于 [1.9.5+、1.10.2+、1.11.0 版]：按照步骤 1 - 4，增加 gke-metrics-agent 的 CPU

    1. 打开 stackdriver 资源进行修改： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit stackdriver stackdriver
    2. 如需将 gke-metrics-agent 的 CPU 请求从 10m 增加到 50m，将 CPU 限制从 100m 增加到 200m，请将以下 resourceAttrOverride 部分添加到 stackdriver 清单中：
      spec:
  resourceAttrOverride:
    gke-metrics-agent/gke-metrics-agent:
      limits:
        cpu: 100m
        memory: 4608Mi
      requests:
        cpu: 10m
        memory: 200Mi
       修改后的资源应类似于以下内容： 
      spec:
  anthosDistribution: on-prem
  clusterLocation: us-west1-a
  clusterName: my-cluster
  enableStackdriverForApplications: true
  gcpServiceAccountSecretName: ...
  optimizedMetrics: true
  portable: true
  projectID: my-project-191923
  proxyConfigSecretName: ...
  resourceAttrOverride:
    gke-metrics-agent/gke-metrics-agent:
      limits:
        cpu: 200m
        memory: 4608Mi
      requests:
        cpu: 50m
        memory: 200Mi
    3. 保存更改并关闭文本编辑器。
    4. 如需验证更改是否已生效，请运行以下命令： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system get daemonset gke-metrics-agent -o yaml \
    | grep "cpu: 50m"
       如果修改生效，则该命令会查找 cpu: 50m。
    日志记录和监控 1.11.0-1.11.2、1.12.0

    如果管理员集群受到此问题的影响，则表示缺少调度器和控制器管理器指标。例如，缺少以下两个指标

    # scheduler metric example
scheduler_pending_pods
# controller-manager metric example
replicaset_controller_rate_limiter_use

    临时解决方法：

    升级到 v1.11.3+、v1.12.1+ 或 v1.13+。
    1.11.0-1.11.2、1.12.0

    如果用户集群受到此问题的影响，则表示缺少调度器和控制器管理器指标。例如，缺少以下两个指标：

    # scheduler metric example
scheduler_pending_pods
# controller-manager metric example
replicaset_controller_rate_limiter_use

    临时解决方法：

    此问题在 Google Distributed Cloud 1.13.0 及更高版本中已得到解决。请将集群升级到包含修复的版本。
    安装、升级、更新 1.10、1.11、1.12、1.13

    如果您创建的是 1.9.x 或 1.10.0 版的管理员集群，并且该管理员集群在创建期间未能使用提供的 gkeConnect 规范注册，则系统会显示以下错误。

    Failed to create root cluster: failed to register admin cluster: failed to register cluster: failed to apply Hub Membership: Membership API request failed: rpc error:  ode = PermissionDenied desc = Permission 'gkehub.memberships.get' denied on PROJECT_PATH

    您仍然可以使用该管理员集群，但如果您之后尝试将该管理员集群升级到 1.10.y 版，则系统会显示以下错误。

    failed to migrate to first admin trust chain: failed to parse current version "": invalid version: "" failed to migrate to first admin trust chain: failed to parse current version "": invalid version: ""

    临时解决方法：
    身份 1.10、1.11、1.12、1.13

    如果您使用 GKE Identity Service 功能来管理 GKE Identity Service ClientConfig，则 Connect Agent 可能会意外重启。


    临时解决方法：

    如果您在现有集群中遇到此问题，则可以执行以下操作之一：

    • 停用 GKE Identity Service。如果您停用 GKE Identity Service，将不会移除已部署的 GKE Identity Service 二进制文件，也不会移除 GKE Identity Service ClientConfig。如需停用 GKE Identity Service，请运行以下命令： 
      gcloud container fleet identity-service disable \
    --project PROJECT_ID
       将 PROJECT_ID 替换为集群的舰队宿主项目的 ID。
    • 将集群更新为 1.9.3 版或更高版本，或者更新为 1.10.1 版或更高版本，以便升级 Connect Agent 版本。
    网络 1.10、1.11、1.12、1.13

    Seesaw 在 DSR 模式下运行，默认情况下，Seesaw 由于数据平面 IP 学习无法在 Cisco ACI 中正常运行。


    临时解决方法：

    一种可能的解决方法是通过将 Seesaw IP 地址作为 L4-L7 虚拟 IP 添加到 Cisco 应用政策基础架构控制器 (APIC) 中来停用 IP 学习。

    如需配置 L4-L7 虚拟 IP 选项，请点击租户 > 应用配置文件 > 应用 EPG 或 uSeg EPG。如果无法停用 IP 学习，则会导致 Cisco API 架构中的不同位置之间出现 IP 端点波动。
    VMware 1.10、1.11、1.12、1.13

    VMWare 最近发现了以下 vSphere 7.0 Update 3 版本出现严重问题：

    • vSphere ESXi 7.0 Update 3（版本 18644231）
    • vSphere ESXi 7.0 Update 3a（版本 18825058）
    • vSphere ESXi 7.0 Update 3b（版本 18905247）
    • vSphere vCenter 7.0 Update 3b（版本 18901211）

    临时解决方法：

    VMWare 现已移除了这些版本。您应该将 ESXi 和 vCenter Server 升级到较新的版本。
    操作系统 1.10、1.11、1.12、1.13

    对于在使用 Container-Optimized OS (COS) 映像的节点上运行的 Pod，您无法将 emptyDir 卷装载为 exec。它会装载为 noexec，系统会显示以下错误：exec user process caused: permission denied。例如，如果您部署以下测试 Pod，则会看到此错误消息：

    apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: test
  name: test
spec:
  containers:
  - args:
    - sleep
    - "5000"
    image: gcr.io/google-containers/busybox:latest
    name: test
    volumeMounts:
      - name: test-volume
        mountPath: /test-volume
    resources:
      limits:
        cpu: 200m
        memory: 512Mi
  dnsPolicy: ClusterFirst
  restartPolicy: Always
  volumes:
    - emptyDir: {}
      name: test-volume

    在测试 Pod 中，如果您运行 mount | grep test-volume，它会显示 noexec 选项：

    /dev/sda1 on /test-volume type ext4 (rw,nosuid,nodev,noexec,relatime,commit=30)

    临时解决方法：
    升级、更新 1.10、1.11、1.12、1.13

    在节点池上启用和停用自动扩缩功能后，节点池副本不会更新。


    临时解决方法：

    从相应节点池的机器部署中移除 cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size 和 cluster.x-k8s.io/cluster-api-autoscaler-node-group-min-size 注解。
    日志记录和监控 1.11、1.12、1.13

    从 1.11 版开始，在开箱即用的监控信息中心上，Windows Pod 状态信息中心和 Windows 节点状态信息中心还会显示来自 Linux 集群的数据。这是因为 Windows 节点和 Pod 指标也会在 Linux 集群上公开。
    日志记录和监控 1.10、1.11、1.12

    对于 Google Distributed Cloud 1.10、1.11 和 1.12 版，如果磁盘上的缓冲日志损坏，则 stackdriver-log-forwarder DaemonSet 可能会出现 CrashLoopBackOff 错误。


    临时解决方法：

    为了缓解此问题，我们需要清理节点上的缓冲日志。

    1. 为防止出现意外行为，请缩容 stackdriver-log-forwarder：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n kube-system patch daemonset stackdriver-log-forwarder -p '{"spec": {"template": {"spec": {"nodeSelector": {"non-existing": "true"}}}}}'
       将 USER_CLUSTER_KUBECONFIG 替换为用户集群 kubeconfig 文件的路径。
    2. 部署清理 DaemonSet 以清理损坏的区块：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    -n kube-system -f - << EOF
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluent-bit-cleanup
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: fluent-bit-cleanup
  template:
    metadata:
      labels:
        app: fluent-bit-cleanup
    spec:
      containers:
      - name: fluent-bit-cleanup
        image: debian:10-slim
        command: ["bash", "-c"]
        args:
        - |
          rm -rf /var/log/fluent-bit-buffers/
          echo "Fluent Bit local buffer is cleaned up."
          sleep 3600
        volumeMounts:
        - name: varlog
          mountPath: /var/log
        securityContext:
          privileged: true
      tolerations:
      - key: "CriticalAddonsOnly"
        operator: "Exists"
      - key: node-role.kubernetes.io/master
        effect: NoSchedule
      - key: node-role.gke.io/observability
        effect: NoSchedule
      volumes:
      - name: varlog
        hostPath:
          path: /var/log
EOF
    3. 为确保清理 DaemonSet 清理了所有区块，您可以运行以下命令。这两个命令的输出应等于集群中的节点数：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  logs -n kube-system -l app=fluent-bit-cleanup | grep "cleaned up" | wc -l

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system get pods -l app=fluent-bit-cleanup --no-headers | wc -l
    4. 删除清理 DaemonSet：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system delete ds fluent-bit-cleanup
    5. 恢复 stackdriver-log-forwarder：
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
  -n kube-system patch daemonset stackdriver-log-forwarder --type json -p='[{"op": "remove", "path": "/spec/template/spec/nodeSelector/non-existing"}]'
    日志记录和监控 1.10、1.11、1.12、1.13、1.14、1.15、1.16

    如果您没有看到来自您的集群的 Cloud Logging 日志，并且发现日志中存在以下错误： 

    2023-06-02T10:53:40.444017427Z [2023/06/02 10:53:40] [error] [input chunk] chunk 1-1685703077.747168499.flb would exceed total limit size in plugin stackdriver.0
2023-06-02T10:53:40.444028047Z [2023/06/02 10:53:40] [error] [input chunk] no available chunk
    可能的原因是日志输入速率超过了日志记录代理的限制，导致 stackdriver-log-forwarder 不发送日志。 所有 Google Distributed Cloud 版本中都会出现此问题。

    临时解决方法：

    如需缓解此问题，您需要提高日志记录代理的资源限制。

    1. 打开 stackdriver 资源进行修改： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system edit stackdriver stackdriver
    2. 如需增加 stackdriver-log-forwarder 的 CPU 请求，请将以下 resourceAttrOverride 部分添加到 stackdriver 清单中： 
      spec:
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder:
      limits:
        cpu: 1200m
        memory: 600Mi
      requests:
        cpu: 600m
        memory: 600Mi
       修改后的资源应类似于以下内容： 
      spec:
  anthosDistribution: on-prem
  clusterLocation: us-west1-a
  clusterName: my-cluster
  enableStackdriverForApplications: true
  gcpServiceAccountSecretName: ...
  optimizedMetrics: true
  portable: true
  projectID: my-project-191923
  proxyConfigSecretName: ...
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder:
      limits:
        cpu: 1200m
        memory: 600Mi
      requests:
        cpu: 600m
        memory: 600Mi
    3. 保存更改并关闭文本编辑器。
    4. 如需验证更改是否已生效，请运行以下命令： 
      kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    --namespace kube-system get daemonset stackdriver-log-forwarder -o yaml \
    | grep "cpu: 1200m"
       如果修改生效，则该命令会查找 cpu: 1200m。
    安全 1.13

    节点在短时间内准备就绪，但 kubelet 服务器证书未准备就绪。kubectl exec 和 kubectl logs 在这几十秒内不可用。这是因为新服务器证书审批人需要一段时间才能看到节点更新后的有效 IP 地址。

    此问题仅会影响 kubelet 服务器证书，不会影响 Pod 调度。
    升级、更新 1.12

    用户集群升级失败，并显示以下内容：

    .LBKind in body is required (Check the status of OnPremUserCluster 'cl-stg-gdl-gke-onprem-mgmt/cl-stg-gdl' and the logs of pod 'kube-system/onprem-user-cluster-controller' for more detailed debugging information.

    管理员集群未完全升级，状态版本仍为 1.10。用户集群升级到 1.12 不会被任何预检检查阻止，并且会因版本偏差问题而失败。


    临时解决方法：

    先将管理员集群升级到 1.11，然后将用户集群升级到 1.12。
    存储 1.10.0-1.10.5、1.11.0-1.11.2、1.12.0

    gkectl diagnose cluster 命令失败，并显示以下内容： 

    Checking VSphere Datastore FreeSpace...FAILURE
    Reason: vCenter datastore: [DATASTORE_NAME] insufficient FreeSpace, requires at least [NUMBER] GB

    不应对现有集群节点池进行数据存储区可用空间验证，但该验证被错误地添加到 gkectl diagnose cluster 中。


    临时解决方法：

    您可以忽略错误消息或使用 --skip-validation-infra 跳过验证。
    操作、网络 1.11、1.12.0-1.12.1

    如果管理员集群设置了 MetalLB 负载均衡器配置，您可能无法添加新用户集群。

    用户集群删除过程可能会由于某种原因而停滞，从而导致 MatalLB ConfigMap 失效。无法在此状态下添加新用户集群。


    临时解决方法：

    您可以强制删除用户集群。
    安装、操作系统 1.10、1.11、1.12、1.13

    如果 osImageType 为管理员集群使用 cos，并且在创建管理员集群之后和创建用户集群之前执行 gkectl check-config，则在以下情况下会失败：

    Failed to create the test VMs: VM failed to get IP addresses on the network.

    为用户集群 check-config 创建的测试虚拟机默认使用管理员集群中的相同 osImageType，而当前测试虚拟机与 COS 不兼容。


    临时解决方法：

    为避免创建测试虚拟机的预检检查速度缓慢，请使用 gkectl check-config --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config USER_CLUSTER_CONFIG --fast。
    日志记录和监控 1.12.0-1.12.1

    此问题会影响使用管理员集群中的 Grafana 监控 Google Distributed Cloud 1.12.0 和 1.12.1 版中的用户集群的客户。此问题的原因是用户集群中的 pushprox-client 证书与管理员集群中的 pushprox-server 的许可名单不匹配。症状是用户集群中的 pushprox-client 输出如下所示的错误日志：

    level=error ts=2022-08-02T13:34:49.41999813Z caller=client.go:166 msg="Error reading request:" err="invalid method \"RBAC:\""

    临时解决方法：
    其他 1.11.3

    gkectl repair admin-master 命令失败，并显示以下内容： 

    Failed to repair: failed to select the template: no VM templates is available for repairing the admin master (check if the admin cluster version >= 1.4.0 or contact support

    如果管理员控制平面虚拟机的名称以 t、m、p 或 l 字符结尾，则 gkectl repair admin-master 无法提取用于修复管理员控制平面虚拟机的虚拟机模板。


    临时解决方法：

    使用 --skip-validation 重新运行该命令。
    日志记录和监控 1.11、1.12、1.13、1.14、1.15、1.16

    Cloud Audit Logs 需要特殊权限设置，目前仅会通过 GKE Hub 为用户集群自动执行。建议至少有一个用户集群使用与管理员集群相同的项目 ID 和服务账号，以用于 Cloud Audit Logs，这样管理员集群将拥有所需的权限。

    但是，如果管理员集群使用与任何用户集群都不同的项目 ID 或服务账号，则来自管理员集群的审核日志将无法注入 Google Cloud。症状是管理员集群的 audit-proxy Pod 中出现一系列 Permission Denied 错误。

    临时解决方法：
    操作、安全 1.11

    如果您的工作站无权访问用户集群工作器节点，则在运行 gkectl diagnose 时会发生以下失败：

    Checking user cluster certificates...FAILURE
    Reason: 3 user cluster certificates error(s).
    Unhealthy Resources:
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out

    如果您的工作站无权访问管理员集群工作器节点或管理员集群工作器节点，则在运行 gkectl diagnose 时会发生以下失败：

    Checking admin cluster certificates...FAILURE
    Reason: 3 admin cluster certificates error(s).
    Unhealthy Resources:
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out
    Node kubelet CA and certificate on node xxx: failed to verify kubelet certificate on node xxx: dial tcp xxx.xxx.xxx.xxx:10250: connect: connection timed out

    临时解决方法：

    可以放心地忽略这些消息。
    操作系统 1.8、1.9、1.10、1.11、1.12、1.13

    /var/log/audit/ 会填充审核日志。您可以通过运行 sudo du -h -d 1 /var/log/audit 来检查磁盘用量。

    管理员工作站上的某些 gkectl 命令（例如 gkectl diagnose snapshot）计入磁盘空间用量。

    从 Google Distributed Cloud v1.8 开始，Ubuntu 映像通过 CIS Level 2 Benchmark 进行了安全强化。并且，其中一个合规性规则“4.1.2.2 确保不会自动删除审核日志”可确保 auditd 设置 max_log_file_action = keep_logs。这会使所有审核规则保留在磁盘上。


    临时解决方法：
    网络 1.10、1.11.0-1.11.3、1.12.0-1.12.2、1.13.0

    由于存在以下验证 webhook 错误，用户无法创建或更新 NetworkGatewayGroup 对象：

    [1] admission webhook "vnetworkgatewaygroup.kb.io" denied the request: NetworkGatewayGroup.networking.gke.io "default" is invalid: [Spec.FloatingIPs: Invalid value: "10.0.0.100": IP address conflicts with node address with name: "my-node-name"

    在受影响的版本中，kubelet 可能会错误地绑定到分配给节点的浮动 IP 地址，并将其报告为 node.status.addresses 中的节点地址。验证 webhook 会针对集群中的所有 node.status.addresses 检查 NetworkGatewayGroup 浮动 IP 地址，并将其视为冲突。


    临时解决方法：

    在创建或更新 NetworkGatewayGroup 对象失败的集群中，暂时停用 ANG 验证 webhook 并提交更改：

    1. 保存 webhook 配置，以便在结束时恢复：
      kubectl -n kube-system get validatingwebhookconfiguration \
    ang-validating-webhook-configuration -o yaml > webhook-config.yaml
    2. 修改 webhook 配置。
      kubectl -n kube-system edit validatingwebhookconfiguration \
    ang-validating-webhook-configuration
    3. 从 webhook 配置列表中移除 vnetworkgatewaygroup.kb.io 项，然后关闭以应用更改。
    4. 创建或修改 NetworkGatewayGroup 对象。
    5. 重新应用原始 webhook 配置。
      kubectl -n kube-system apply -f webhook-config.yaml
    安装、升级、更新 1.10.0-1.10.2

    在尝试管理员集群升级过程中，管理员控制平面虚拟机可能会在创建期间停滞。管理员控制平面虚拟机在启动期间进入无限等待循环，您会在 /var/log/cloud-init-output.log 文件中看到以下无限循环错误：

    + echo 'waiting network configuration is applied'
waiting network configuration is applied
++ get-public-ip
+++ ip addr show dev ens192 scope global
+++ head -n 1
+++ grep -v 192.168.231.1
+++ grep -Eo 'inet ([0-9]{1,3}\.){3}[0-9]{1,3}'
+++ awk '{print $2}'
++ echo
+ '[' -n '' ']'
+ sleep 1
+ echo 'waiting network configuration is applied'
waiting network configuration is applied
++ get-public-ip
+++ ip addr show dev ens192 scope global
+++ grep -Eo 'inet ([0-9]{1,3}\.){3}[0-9]{1,3}'
+++ awk '{print $2}'
+++ grep -v 192.168.231.1
+++ head -n 1
++ echo
+ '[' -n '' ']'
+ sleep 1

    这是因为当 Google Distributed Cloud 尝试在启动脚本中获取节点 IP 地址时，它使用 grep -v ADMIN_CONTROL_PLANE_VIP 跳过也可以分配给 NIC 的管理员集群控制平面 VIP。但是，该命令也会跳过任何具有控制平面 VIP 前缀的 IP 地址，这会导致启动脚本挂起。

    例如，假设管理员集群控制平面 VIP 为 192.168.1.25。如果管理员集群控制平面虚拟机的 IP 地址具有相同的前缀（例如 192.168.1.254），则该控制平面虚拟机会在创建期间停滞。如果广播地址与控制平面 VIP 具有相同的前缀（例如 192.168.1.255），也可能会触发此问题。


    临时解决方法：

    • 如果管理员集群创建超时的原因在于广播 IP 地址，请在管理员集群控制平面虚拟机上运行以下命令：
      ip addr add ${ADMIN_CONTROL_PLANE_NODE_IP}/32 dev ens192
       这将创建不包含广播地址的一行，并取消阻止启动过程。取消阻止启动脚本后，通过运行以下命令移除添加的这一行：
      ip addr del ${ADMIN_CONTROL_PLANE_NODE_IP}/32 dev ens192
    • 但是，如果管理员集群创建超时的原因在于控制平面虚拟机的 IP 地址，则您无法取消阻止启动脚本。切换到其他 IP 地址，然后重新创建或升级到 1.10.3 版或更高版本。
    操作系统、升级、更新 1.10.0-1.10.2

    使用 COS 映像时，数据磁盘无法正确装载到管理员集群主节点，并且使用 COS 映像的管理员集群的状态在管理员集群升级或管理员主节点修复时会丢失。（使用 COS 映像的管理员集群是一项预览版功能）


    临时解决方法：

    重新创建管理员集群（将 osImageType 设置为 ubuntu_containerd）

    创建管理员集群并将 osImageType 设置为 cos 后，获取管理员集群 SSH 密钥并通过 SSH 连接到管理员主节点。df -h 结果包含 /dev/sdb1 98G 209M 93G 1% /opt/data。并且 lsblk 结果包含 -sdb1 8:17 0 100G 0 part /opt/data
    操作系统 1.10

    在 Google Distributed Cloud 1.10.0 版中，Ubuntu 上的域名解析默认路由到监听 127.0.0.53 的本地 systemd-resolved。这是因为对于在 1.10.0 版中使用的 Ubuntu 20.04 映像，/etc/resolv.conf 通过 sym 链接到 /run/systemd/resolve/stub-resolv.conf，它指向 127.0.0.53 localhost DNS 存根。

    因此，localhost DNS 域名解析会拒绝检查上游 DNS 服务器（在 /run/systemd/resolve/resolv.conf 中指定）是否存在具有 .local 后缀的名称，除非这些名称被指定为搜索网域。

    这样便会导致对 .local 名称的所有查找均失败。例如，在节点启动期间，kubelet 在从具有 .local 后缀的私有注册表中拉取映像时会失败。这是因为指定具有 .local 后缀的 vCenter 地址对管理员工作站不起作用。


    临时解决方法：

    如果您在管理员集群配置文件以及用户集群配置文件中指定 searchDomainsForDNS 字段来包含相应网域，则可以避免集群节点出现此问题。

    目前 gkectl update 尚不支持更新 searchDomainsForDNS 字段。

    因此，如果您未在创建集群之前设置此字段，则必须通过 SSH 连接到节点，并通过将 /etc/resolv.conf 的 symlink 从 /run/systemd/resolve/stub-resolv.conf（包含 127.0.0.53 本地存根）更改为 /run/systemd/resolve/resolv.conf（指向实际的上游 DNS）来绕过本地 systemd-resolved 存根：

    sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf

    对于管理员工作站，gkeadm 不支持指定搜索网域，因此必须通过这一手动步骤解决此问题。

    此解决方案在重新创建虚拟机后不会保留。每当重新创建虚拟机时，您都必须重新应用此解决方法。
    安装、操作系统 1.10

    Google Distributed Cloud 为使用 --bip=169.254.123.1/24 的 Docker 网桥 IP 地址指定专用子网，这样它就不会预留默认的 172.17.0.1/16 子网。但是，在 1.10.0 版中，Ubuntu 操作系统映像中存在一个 bug，导致自定义 Docker 配置被忽略。

    因此，Docker 选择默认的 172.17.0.1/16 作为其网桥 IP 地址子网。如果您已在该 IP 地址范围内运行工作负载，则可能会导致 IP 地址冲突。


    临时解决方法：

    如需解决此问题，您必须重命名 dockerd 的以下 systemd 配置文件，然后重启服务：

    sudo mv /etc/systemd/system/docker.service.d/50-cloudimg-settings.cfg \
    /etc/systemd/system/docker.service.d/50-cloudimg-settings.conf

sudo systemctl daemon-reload

sudo systemctl restart docker

    验证 Docker 选择正确的网桥 IP 地址：

    ip a | grep docker0

    此解决方案在重新创建虚拟机后不会保留。每当重新创建虚拟机时，您都必须重新应用此解决方法。
    升级、更新 1.11

    在 Google Distributed Cloud 1.11.0 版中，与日志记录和监控相关的自定义资源定义发生了变化：

    • stackdriver 自定义资源的组名称从 addons.sigs.k8s.io 更改为 addons.gke.io；
    • monitoring 和 metricsserver 自定义资源的组名称从 addons.k8s.io 更改为 addons.gke.io；
    • 上述资源的规范开始根据其架构进行评估。具体而言，stackdriver 自定义资源中的 resourceAttrOverride 和 storageSizeOverride 规范需要在 cpu、内存和存储空间大小请求和限制的值中提供字符串类型。

    更改组名称是为了符合 Kubernetes 1.22 中的 CustomResourceDefinition 更新。

    如果您没有应用或修改受影响的自定义资源的其他逻辑，则无需执行任何操作。Google Distributed Cloud 升级过程将负责迁移受影响的资源，并在组名称更改后保留其现有规范。

    但是，如果您运行任何应用或修改受影响资源的逻辑，则需要特别注意。首先，您需要使用清单文件中的新组名称来引用它们。例如：

    apiVersion: addons.gke.io/v1alpha1  ## instead of `addons.sigs.k8s.io/v1alpha1`
kind: Stackdriver

    其次，请确保 resourceAttrOverride 和 storageSizeOverride 规范值均为字符串类型。例如：

    spec:
  resourceAttrOverride:
    stackdriver-log-forwarder/stackdriver-log-forwarder
      limits:
        cpu: 1000m # or "1"
        # cpu: 1 # integer value like this would not work 
        memory: 3000Mi

    否则，应用和修改将不会生效，并且可能导致日志记录和监控组件出现意外状态。可能的症状包括：

    • onprem-user-cluster-controller 中的协调错误日志，例如：
      potential reconciliation error: Apply bundle components failed, requeue after 10s, error: failed to apply addon components: failed to apply bundle objects from stackdriver-operator-addon 1.11.2-gke.53 to cluster my-cluster: failed to create typed live object: .spec.resourceAttrOverride.stackdriver-log-forwarder/stackdriver-log-forwarder.limits.cpu: expected string, got &value.valueUnstructured{Value:1}
    • kubectl edit stackdriver stackdriver 失败，例如：
      Error from server (NotFound): stackdrivers.addons.gke.io "stackdriver" not found

    如果您遇到上述错误，则表示在升级之前，Stackdriver CR 规范下就已存在不受支持的类型。如需解决此问题，您可以在旧的组名称 kubectl edit stackdrivers.addons.sigs.k8s.io stackdriver 下手动修改 Stackdriver CR，并执行以下操作：

    1. 将资源请求和限制更改为字符串类型；
    2. 移除任何 addons.gke.io/migrated-and-deprecated: true 注解（如果存在）。
    然后恢复或重启升级过程。

    操作系统 1.7 及更高版本

    每当 ESXi 服务器发生故障并且为该服务器启用了 vCenter 高可用性功能时，故障 ESXi 服务器中的所有虚拟机都会触发 vMotion 机制，并迁移到另一个正常的 ESXi 服务器。迁移的 COS 虚拟机将丢失其 IP。

    临时解决方法：

    重新启动虚拟机
    网络 1.14.7、1.15.0-1.15.3、1.16.0 版之前的所有版本

    Seesaw 每 20 秒发送的定期 GARP（免费 ARP）不会在 ARP 标头中设置目标 IP。某些网络可能不接受此类数据包（如 Cisco ACI）。它可能会导致在脑裂（由于 VRRP 丢包）恢复后，服务停机时间延长。

    临时解决方法：

    通过在任一 Seesaw 虚拟机上运行 sudo seesaw -c failover 来触发 Seeaw 故障切换。这样应该会恢复流量。
    操作系统 1.16、1.28.0-1.28.200

    错误地为工作器节点设置了“staticPodPath”

    临时解决方法：

    手动创建文件夹“/etc/kubernetes/manifests”
    如果您需要其他帮助，请与 Cloud Customer Care 联系。