VMware vSphere 业务集群故障排除

从 ac adm alpha cluster status 报告的阶段开始排查。对于所有提供商都常见的故障,请参阅故障排除。

创建阶段

症状首先查看的位置
create 报告找不到某个 vCenter 对象修正 install-config.yaml 中的名称,然后重新运行 create。每次运行时,ac 只会报告一个缺失对象。以清单路径形式提供的名称(包含 /)仅在克隆 VM 时检查。
[1/4] CAPI Cluster 未推进Cluster 和 VSphereCluster 条件。
[2/4] KubeadmControlPlane 未推进KubeadmControlPlane、Machine、VSphereMachine 和 VSphereVM 条件,以及池条件和 status.configStatuses。
控制平面未启动端点和 registry:负载均衡器或 VIP 的运行状况、DNS、registry API、ACP 端口规则,以及 global 集群和节点是否能够访问它们。
节点一直未初始化CPI 的交付情况:ClusterResourceSetBinding 以及业务集群中的 CPI Pod。
[3/4] MachineDeployment 未推进MachineDeployment 的 rollout、VM 状态、CPI 和 CNI。
[4/4] ClusterView 未推进平台 ClusterView、registry API 和 provider manager 日志。

先收集状态。在 ac 已登录平台的机器上运行以下命令:

ac config use-cluster global
ac -n cpaas-system describe clusters.cluster.x-k8s.io <cluster-name>
ac -n cpaas-system describe vspherecluster <cluster-name>
ac -n cpaas-system describe kubeadmcontrolplane <cluster-name>-control-plane
ac -n cpaas-system describe machinedeployment <cluster-name>-<group>
ac -n cpaas-system get clusters.cluster.x-k8s.io,vspherecluster,kubeadmcontrolplane,machinedeployment,machine,vspheremachine,vspherevm
ac -n cpaas-system logs deploy/capi-controller-manager

如果尚未安装网络插件,还要检查平台网络控制器和集群生命周期控制器的日志。

常见原因

结果操作
CPI 资源未交付检查 ClusterResourceSet 及其 ClusterResourceSetBinding 是否存在,参见 CPI 和池。如果 ClusterResourceSet 存在但没有任何内容被应用,请联系技术支持。
存在 ClusterResourceSet,但未创建任何 ClusterResourceSetBinding检查控制器是否对所引用的 ConfigMap 和 Secret 具有删除权限。
未安装网络插件检查集群注解是否存在,以及平台控制器是否已处理这些注解。
缺少或错误的 cpaas.io/registry-address 注解将其设置为永久的 <registry_address>,不要包含 scheme 或 /v2/。然后检查 cpaas-system/public-registry-credential。
某个机器卡在 Provisioning读取该 VSphereMachine 的 MachineConfigPoolReady 条件。然后读取池条件 MembersValid、MembersUnique、PersistentDisksReady、ClusterRefReady 和 VCenterAvailable。
某个机器始终无法引导;BootstrapReady 为 False,并带有 BootstrapSecretGetFailed 或 BootstrapSecretContentInvalid在查看 vCenter 之前,检查该 Machine 的 KubeadmConfig 及其引导数据 Secret。
某个节点在 vCenter 中被关闭,并且一直处于关闭状态在 vCenter 中启动该 VM。对于首次启动后被关闭的 VM,provider 不会将其启动。无需执行 rollout。
VSphereMachine 在没有明显原因的情况下清除 Ready读取 VSphereVM 条件。当 VM、其 providerID 或其网络信息不可用时,Ready 会被清除。
某个 VM 等待 IP 地址检查 VMware Tools、静态 IP 设置和 VSphereVM.status.addresses。
业务 Node 对象没有 spec.providerID首先检查 CPI 交付情况。然后查找同一数据中心中具有相同 guest hostname 的旧 VM。修复或移除重复项,然后按照此表下方所示重启 CPI Pod。
数据存储空间耗尽列出每个 VSphereMachineConfigPool,包括正在终止的对象。每个池拥有自己的持久磁盘,因此重复部署会累积多组磁盘。读取 status.configStatuses[]、status.persistentDiskStatuses[](phase、lastError、retryAfter、taskRef)以及池 Events。不要删除 VMDK、移除池 finalizer 或手动编辑 status.persistentDiskStatuses[]。如果回收没有进展,请联系技术支持。参见持久磁盘生命周期。
即使设置了 rootDisk.sizeGiB,系统磁盘仍保持模板的大小该 VM 是链接克隆,只有当模板没有快照时(即完整克隆),rootDisk.sizeGiB 才会生效。参见 global 集群模板。
控制平面端点未启动检查 TCP 6443 直通、所有控制平面后端、HTTPS /healthz、DNS 和证书 SAN,以及从 global 集群和控制平面节点到它们的可达性。
与 vCenter 的 TLS 连接失败检查指纹、vCenter 地址和任何代理设置。

修复重复的 hostname 后,重启 CPI Pod:

ac config sync
ac config use-cluster <cluster-name>
ac -n kube-system delete pod -l k8s-app=vsphere-cloud-controller-manager
ac config use-cluster global

自建 VIP

读取 VSphereCluster 上的 SelfBuiltLoadBalancerReady 条件,操作方法参见验证自建 VIP。然后在下表中查找结果:

结果操作
False,原因 SelfBuiltLoadBalancerReconcilingVIP 仍在配置中。稍后再检查。
False,原因 SelfBuiltLoadBalancerNotReady检查 kube-system 中的 Alive 插件 Pod,以及业务集群 cpaas-system 中的 alive AppRelease。还要检查 VIP 是否位于控制平面二层域中、vrid 是否唯一,以及是否允许 VRRP 和免费 ARP。
False,原因 InvalidSelfBuiltLoadBalancerConfigurationloadBalancer 值无效。无法在现有集群上更改这些值。请删除集群,然后使用更正后的值重新创建。
通过 VIP 访问 healthz 时未显示 ok,且无法通过 VIP 访问集群检查 VIP 是否位于控制平面二层域中、vrid 是否唯一,以及是否允许 VRRP 和无故请求 ARP。然后检查 Alive 插件 Pod。
没有 Alive 插件 Pod,也没有 alive AppRelease使用以下命令检查 global 集群上的 Alive 插件。
ac config use-cluster global
ac get clustermodule global -o jsonpath='{.spec.version}{"\n"}'
ac get moduleplugin alive -o jsonpath='{.status.targetClusterVersions}{"\n"}'
ac get moduleplugin alive -o jsonpath='{.status.latestVersion}{"\n"}'
ac get moduleconfig alive-<alive-version> -o jsonpath='{.status.readyForDeploy}{"\n"}'

将 <alive-version> 替换为第一条命令输出的版本对应的 targetClusterVersions 条目。如果没有这样的条目,请使用 latestVersion。当最后一条命令输出 true 时继续。否则,此平台上的 Core Package 不完整;请导入适用于此平台版本的完整 Core Package。

Admission Rejections

Provider 可以在创建任何资源之前拒绝 apply 或 edit。在下表第一列中查找拒绝消息中的片段。有关规则,请参见Provider Requirements。

拒绝消息包含原因和修复
maxSurge must be 0 when the infrastructure template references a machineConfigPoolRef在 KubeadmControlPlane 或 MachineDeployment 上,将 maxSurge 设置为整数 0。如果不设置,则使用 Cluster API 默认值 1。
maxUnavailable must be at least 1在 MachineDeployment 上,将 maxUnavailable 设置为 1 或更大值。如果不设置,则使用 Cluster API 默认值 0。
must have 1 or at least 3 replicas控制平面有 2 个副本。使用 1,或将其设置为 3 或更大值,并使用 maxSurge: 0。
also used by pool另一个池中的某个 slot 已使用主机名或主 IP,且该池在此命名空间中绑定到相同的 Cluster。
allocated slotslot 为 InUse 或 Released。消息会指出被冻结的内容:主 IP 或 IPv6,或持久性磁盘的 sizeGiB 或 mountPath。消息还可能报告无法移除 slot 或其持久性磁盘之一。请参见已分配 slot 的限制。
cannot delete pool while池仍拥有 InUse 个 slot。请先删除持有这些 slot 的 Machine。
is already referenced by 或 is bound to两个控制器引用了同一个池。为每个 KubeadmControlPlane 和 MachineDeployment 分别提供一个池。
cannot change clusterRef while consumerRef is set池已绑定到控制器。请创建新池,而不要更改此池所引用的集群。
VSphereMachineTemplate spec.template.spec field is immutable使用新名称创建新模板,而不要编辑现有模板。请参见推出更新后的工作节点配置。
is immutable once controlPlaneLoadBalancer is setspec.controlPlaneLoadBalancer 只能写入一次。请参见controlPlaneLoadBalancer 字段。
cannot be set after the cluster is created集群创建时未设置 spec.controlPlaneLoadBalancer。省略该字段本身就表示使用外部 LoadBalancer。端点在创建集群时即已固定,因此之后无法再添加该字段。