排查集群创建或升级问题

本页面介绍了如何调查 Google Distributed Cloud for VMware（纯软件）中的集群创建和升级问题。

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

安装问题

以下部分可能会帮助您排查与安装 Google Distributed Cloud 相关的问题。

使用引导集群调试问题

在安装期间，Google Distributed Cloud 会创建临时引导集群。安装成功后，Google Distributed Cloud 会删除引导集群，留下您的管理员集群和用户集群。通常情况下，您应该无需与引导集群进行交互。 不过，如果您在安装过程中遇到问题，可以使用引导集群日志来帮助调试问题。

如果将 --cleanup-external-cluster=false 传递给 gkectl create cluster，则引导集群不会被删除，您可以使用引导集群来调试安装问题。

检查引导集群的日志

1. 找到在 kube-system 命名空间中运行的 Pod 的名称：

   kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl get pods -n kube-system
   

2. 查看 Pod 的日志：

   kubectl --kubeconfig /home/ubuntu/.kube/kind-config-gkectl -n kube-system get logs POD_NAME
   

   将 POD_NAME 替换为您要查看的 Pod 的名称。

3. 如需直接获取引导集群的日志，请在集群创建、更新和升级期间运行以下命令：

   docker exec -it gkectl-control-plane bash
   

   此命令会在引导集群中运行的 gkectl-control-plane 容器内打开一个终端。

4. 要检查 kubelet 和 containerd 日志，请使用以下命令并查找输出中的错误或警告：

   systemctl status -l kubelet
   journalctl --utc -u kubelet
   systemctl status -l containerd
   journalctl --utc -u containerd
   

检查引导集群的快照

如果您尝试创建或升级管理员集群，并且该操作失败，Google Distributed Cloud 会获取引导集群的外部快照。引导集群的此快照与在管理员集群上运行 gkectl diagnose snapshot 命令截取的快照类似，但该过程会自动触发。引导集群快照包含对管理员集群创建和升级过程的重要调试信息。如果需要，您可以向 Cloud Customer Care 提供此快照。

外部快照包含来自 onprem-admin-cluster-controller 的 Pod 日志，您可以查看这些日志以调试集群创建或升级问题。日志存储在单独的文件中，例如：

kubectl_logs_onprem-admin-cluster-controller-6767f6597-nws8g_ \
    --container_onprem-admin-cluster-controller_ \
    --kubeconfig_.home.ubuntu..kube.kind-config-gkectl_\
    --namespace_kube-system

虚拟机在管理员控制平面启动后无法启动

如果虚拟机在管理员控制平面启动后无法启动，您可以通过在管理员集群中检查 Cluster API 控制器 Pod 的日志来调查问题：

1. 找到 Cluster API 控制器 Pod 的名称：

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       get pods | grep clusterapi-controllers
   

2. 查看 vsphere-controller-manager 的日志。首先指定 Pod，但不指定容器：

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       logs POD_NAME
   

   输出结果表明您必须指定容器，并且为您提供了 Pod 中的容器的名称。例如：

   ... a container name must be specified ...,
   choose one of: [clusterapi-controller-manager vsphere-controller-manager rbac-proxy]
   

3. 选择一个容器并查看其日志：

   kubectl --kubeconfig ADMIN_CLUSTER_KUBECONFIG --namespace kube-system \
       logs POD_NAME --container CONTAINER_NAME
   

已分配足够数量的 IP 地址，但 Machine 无法向集群注册

如果存在 IP 地址冲突，就可能会发生此问题。例如，您为机器指定的 IP 地址被用于负载均衡器。

如需解决此问题，请更新您的集群 IP 地址块文件，这样，机器地址就不会与集群配置文件或 Seesaw IP 地址块文件中指定的地址冲突

集群升级问题

以下部分提供了有关如何解决集群升级期间可能遇到的问题的提示。

在升级后回滚节点池

如果您在升级用户集群后发现集群节点存在问题，则可以将所选节点池回滚到先前版本。

Ubuntu 和 COS 节点池支持回滚所选节点池，但 Windows 节点池不支持回滚。

节点池的版本可以与用户集群控制平面的版本相同，也可以低一个次要版本。例如，如果控制平面为 1.14 版，则节点池可以为 1.14 版或 1.13 版。

查看可用的节点池版本

假设您最近将用户集群工作器节点和控制平面从 1.13.1-gke.35 版升级到 1.14.0 版，但后来发现升级后的工作器节点存在问题。因此，您决定将一个或多个节点池回滚到您之前运行的版本：1.13.1-gke.35。 在开始回滚之前，您需要验证先前版本是否可用于回滚。

如需查看可用版本，请运行以下命令：

gkectl version --cluster-name USER_CLUSTER_NAME \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG

输出结果会显示每个节点池的当前版本和上一个版本。例如：

user cluster version: 1.14.0-gke.x

node pools:
- pool-1:
  - version: 1.14.0-gke.x
  - previous version: 1.13.1-gke.35
- pool-2:
  - version: 1.14.0-gke.x
  - previous version: 1.13.1-gke.35

available node pool versions:
- 1.13.1-gke.35
- 1.14.0-gke.x

回滚节点池版本

您可以一次回滚一个节点池的版本 1 节点池，也可以一步回滚多个节点池。

如需回滚节点池版本，请完成以下步骤：

1. 在用户集群配置文件中，将一个或多个节点池的 gkeOnPremVersion 值设置为先前版本。以下示例展示了如何回滚到 1.13.1-gke.35 版：

   nodePools:
   - name: pool-1
     cpus: 4
     memoryMB: 8192
     replicas: 3
     gkeOnPremVersion: 1.13.1-gke.35
     ...
   

2. 更新集群以回滚节点池：

   gkectl update cluster --config USER_CLUSTER_CONFIG \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

3. 验证回滚是否成功：

   gkectl version --cluster-name USER_CLUSTER_NAME \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   以下输出结果即表明 pool-1 已回滚到 1.13.1-gke.35 版。

   user cluster version: 1.14.0-gke.x
   
   node pools:
   - pool-1:
     - version: 1.13.1-gke.35
     - previous version: 1.14.0-gke.x
   - pool-2:
     - version: 1.14.0-gke.x
     - previous version: 1.13.1-gke.35
   
   available node pool versions:
   - 1.13.1-gke.35
   - 1.14.0-gke.x
   

升级到新的补丁程序版本

您可以将所有节点池和控制平面升级到新的补丁版本。如果您回滚到先前的版本，并希望升级到包含修复程序的版本，这可能会有所帮助。

如需升级到新版本，请完成以下步骤：

1. 在用户集群配置文件中进行以下更改：

   1. 将 gkeOnPremVersion 的值设置为新的补丁版本。此示例使用 1.14.1-gke.x。

   2. 对于每个节点池，移除 gkeOnPremVersion 字段或将其设置为空字符串。如果没有为节点池指定版本，节点池的版本将默认为针对集群指定的版本。

      这些更改类似于以下示例：

      gkeOnPremVersion: 1.14.1-gke.x
      
      nodePools:
      -   name: pool-1
        cpus: 4
        memoryMB: 8192
        replicas: 3
        gkeOnPremVersion: ""
      -   name: pool-2
        cpus: 8
        memoryMB: 8192
        replicas: 2
        gkeOnPremVersion: ""
      

2. 按照升级 Google Distributed Cloud 中的说明运行 gkectl prepare 和 gkectl upgrade cluster。

3. 验证新集群版本，并查看可用于回滚的版本：

   gkectl version --cluster-name USER_CLUSTER_NAME \
       --kubeconfig ADMIN_CLUSTER_KUBECONFIG
   

   输出类似于以下内容：

    user cluster version: 1.14.1-gke.y
   
    node pools:
    - pool-1:
      - version: 1.14.1-gke.y
      - previous version: 1.13.1-gke.35
    - pool-2:
      - version: 1.14.1-gke.y
      - previous version: 1.13.1-gke.35
   
    available node pool versions:
    - 1.13.1-gke.35
    - 1.14.0-gke.x
    - 1.14.1-gke.y
    ```
   

健康检查会在集群升级失败时自动运行

如果您尝试升级管理员集群或用户集群，并且此操作失败，则 Google Distributed Cloud 会自动在该集群上运行 gkectl diagnose cluster 命令。

如需跳过自动诊断，请将 --skip-diagnose-cluster 标志传递给 gkectl upgrade。

升级过程卡住

Google Distributed Cloud 在升级期间在后台使用 Kubernetes drain 命令。此 drain 过程可能会被一项部署阻止，该部署只有一个副本，且副本中包含通过 minAvailable: 1 为其创建的 PodDisruptionBudget (PDB)。

在 Google Distributed Cloud 1.13 版中，您可以通过 Kubernetes Pod 事件检查失败。

1. 找到 Machine 的名称：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get machines --all-namespaces
   

2. 使用 kubectl describe machine 命令检查错误：

   kubectl --kubeconfig USER_CLUSTER_KUBECONFIG describe machine MACHINE_NAME
   

   输出类似于以下内容：

   Events:
     Type     Reason              Age    From                Message
     ----     ------              ----   ----                -------
     Warning  PodEvictionTooLong  3m49s  machine-controller  Waiting too long(12m10.284294321s) for pod(default/test-deployment-669b85c4cc-z8pz7) eviction.
   

3. 可选：如需查看机器对象状态的详细分析，请运行 gkectl diagnose cluster：

   输出类似于以下内容：

   ...
   Checking machineset...SUCCESS
   Checking machine objects...FAILURE
       Reason: 1 machine objects error(s).
       Unhealthy Resources:
       Pod test-deployment-669b85c4cc-7zjpq: Pod cannot be evicted successfully. There is 1 related PDB.
   ...
   Checking all poddisruptionbudgets...FAILURE
       Reason: 1 pod disruption budget error(s).
       Unhealthy Resources:
       PodDisruptionBudget test-pdb: default/test-pdb might be configured incorrectly, the total replicas(3) should be larger than spec.MinAvailable(3).
   ...
   Some validation results were FAILURE or UNKNOWN. Check report above.
   

如要解决此问题，请保存 PDB 并从集群中移除它，然后再尝试升级。在升级完成后，您可以重新加回此 PDB。

移除不受支持的更改以解除升级屏蔽

将集群升级到 1.16 或更低版本时，升级期间会静默忽略对大多数字段所做的更改，这意味着这些更改在升级期间和升级后都不会生效。

将用户集群升级到 1.28 或更高版本时，我们会验证配置文件中所做的所有更改，并针对不受支持的更改返回错误，而不是仅忽略这些更改。此功能仅适用于用户集群。升级管理员集群时，系统会静默忽略对大多数字段所做的更改，并且这些更改不会在升级后生效。

例如，如果您在将用户集群升级到 1.28 时尝试停用节点自动修复功能，升级会失败，并显示以下错误消息：

failed to generate desired create config: failed to generate desired OnPremUserCluster from seed config: failed to apply validating webhook to OnPremUserCluster: the following changes on immutable fields are forbidden during upgrade: (diff: -before, +after):
   v1alpha1.OnPremUserClusterSpec{
    ... // 20 identical fields
    UsageMetering:         nil,
    CloudAuditLogging:     &{ProjectID: "syllogi-partner-testing", ClusterLocation: "us-central1", ServiceAccountKey: &{KubernetesSecret: &{Name: "user-cluster-creds", KeyName: "cloud-audit-logging-service-account-key"}}},
-   AutoRepair:            &v1alpha1.AutoRepairConfig{Enabled: true},
+   AutoRepair:            &v1alpha1.AutoRepairConfig{},
    CARotation:            &{Generated: &{CAVersion: 1}},
    KSASigningKeyRotation: &{Generated: &{KSASigningKeyVersion: 1}},
    ... // 8 identical fields
  }

如果您需要绕过此错误，可以使用以下解决方法：

• 还原尝试更改的内容，然后重新运行升级。例如，在前面的场景中，您可以还原对 AutoRepair 配置所做的更改，然后重新运行 gkectl upgrade。
• 或者，您也可以通过运行 gkectl get-config、更新配置文件中集群和节点池的 gkeOnPremVersion 字段，然后重新运行 gkectl upgrade，来生成与集群当前状态匹配的配置文件。

使用内部 kubeconfig 文件调试 F5 BIG-IP 问题

安装完成后，Google Distributed Cloud 会在管理员工作站的主目录中生成一个名为 internal-cluster-kubeconfig-debug 的 kubeconfig 文件。此 kubeconfig 文件与管理员集群的 kubeconfig 文件完全相同，只是它直接指向管理员集群的控制层面节点（Kubernetes API 服务器在该节点上运行）。您可以使用 internal-cluster-kubeconfig-debug 文件调试 F5 BIG-IP 问题。

调试 vSphere 问题

您可以使用 govc 调查与 vSphere 相关的问题。例如，您可以确认 vCenter 用户账号的权限和访问权限，并且可以收集 vSphere 日志。

重新创建缺失的用户集群 kubeconfig 文件

在以下情况下，您可能需要重新创建用户集群 kubeconfig 文件：

• 您尝试创建用户集群但创建操作失败，而您希望拥有其用户集群 kubeconfig 文件。
• 用户集群 kubeconfig 文件缺失，例如在删除后。

如需为用户集群生成新的 kubeconfig 文件，请执行以下步骤：

1. 定义环境变量：

   首先，使用适当的值设置以下环境变量：

   USER_CONTROLPLANEVIP=USER_CONTROLPLANEVIP
   USER_CLUSTER_NAME=USER_CLUSTER_NAME
   ADMIN_CLUSTER_KUBECONFIG=PATH_TO_ADMIN_KUBECONFIG
   KUBECONFIG_SECRET_NAME=$(kubectl --kubeconfig $ADMIN_CLUSTER_KUBECONFIG get secrets -n $USER_CLUSTER_NAME | grep ^admin | cut -d' ' -f1 | head -n 1)
   

   替换以下内容：

   • ADMIN_CLUSTER_KUBECONFIG：管理员集群的 kubeconfig 文件的路径。
   • USER_CONTROLPLANEVIP：用户集群的 controlPlaneVIP。您可以从用户集群清单文件中检索此信息。

2. 生成 kubeconfig 文件：

   运行以下命令以创建新的 kubeconfig 文件：

   kubectl --kubeconfig $ADMIN_CLUSTER_KUBECONFIG get secrets $KUBECONFIG_SECRET_NAME \
    -n $USER_CLUSTER_NAME -o jsonpath='{.data.admin\.conf}'  | base64 -d | \
    sed -r "s/ kube-apiserver.*local\./${USER_CONTROLPLANEVIP}/" \
    > USER_CLUSTER_KUBECONFIG
   

   您需要进行如下替换：

   • USER_CLUSTER_KUBECONFIG：用户集群的新 kubeconfig 文件的名称。

后续步骤

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