#排查卡在 Deleting 中的 DCSMachine

当 Huawei DCS workload cluster 上的 DCSMachine 长时间停留在 Phase: Deleting（超过预期的 ~60 秒）时，请使用本指南。这种情况会在缩容、滚动升级或整个集群拆除期间阻塞节点轮换。

#范围

本指南涵盖的是阻止 cluster-api-provider-dcs 在某个节点上完成 reconcileDelete 流程的 DCS 侧故障模式。该 provider 的正常删除顺序如下：

running VM  →  safe StopVm  →  stopped  →  (detach persistent disks if any)  →  DeleteVm  →  VM gone in DCS

每一步都依赖 DCS 平台有响应。当 DCS 无响应或拒绝某一步时，controller 会在 DCSMachine.Status.Conditions.VMStopPending 中暴露等待原因。优先读取该 condition，通常无需访问 controller 日志就能定位问题。

本指南不涵盖正常的删除前门控（例如 CAPI Machine 的 drain 超时、被其他 controller 持有的 finalizer）——这些属于上游 Cluster API 的排查范围。

#症状

如果 VMStopPending 不存在，而 Machine.status.phase 仍长时间处于 Deleting，则问题更可能发生在 reconcileDelete 之前（例如 CAPI drain、kubeadm pre-delete hooks）。这种情况下请参阅 CAPI troubleshooting docs。

#读取 VMStopPending Condition

VMStopPending condition 是本指南的主要信号。

kubectl -n <ns> describe dcsmachine <name>

查看如下内容：

Conditions:
  Type:               VMStopPending
  Status:             False
  Severity:           Warning
  Reason:             VMMidTransition
  Message:            VM stuck in stopping; awaiting transition to stopped

Reason 字段是诊断依据：

#诊断流程

#卡在 stopping 中的 VM

controller 已发出正常的 StopVm（调用 DCS API /action/stop?mode=safe），VM 也已确认接收，但从未收敛完成。

常见原因：

1. VM 的 pvDriverStatus 不是 running —— graceful shutdown 所需的 guest tools（vmtools / pvdriver）没有响应。请在 DCS portal 上验证：打开 VM 详情页，检查 pvDriverStatus 字段。如果其值不是 running，则该 VM 无法接受安全停止。
2. VM template 早于 4.2.1 —— 较旧的 DCS VM templates 缺少安全停止所需的 guest tools。请确认 DCSMachine 中的 vmTemplateName 是否匹配 4.2.1+ template（查看 cpaas-system/<release>-dcs-vm-template ConfigMap 上的 cpaas.io/dcs-vm-template label，参见 Resolving Placeholder Values）。
3. Guest OS 卡死 —— VM kernel 卡住，未处理 ACPI shutdown。

解决路径：

• 对于 (1) 和 (3)：在 DCS portal 中手动执行 force 停止（VM detail → Operations → Stop → Force）。一旦 VM 达到 stopped，controller 的下一次 reconcile 会拾取新状态，并继续执行 DeleteVm。
• 对于 (2)：该 provider 不能在该 template 上安全删除该 VM；请先将 workload 从该节点上迁出，手动关闭 VM，然后 使用 cpaas.io/retain-vm 作为跳出手段。

#卡在中间过渡状态的 VM

Message 显示 migrating、starting、paused 或 hibernated 之类的状态。controller 不会对处于这些状态的 VM 执行任何操作（DCS 会拒绝），并会一直等待 VM 收敛到 running 或 stopped。

#controller 无法访问 DCS API

如果 VMStopPending condition 不存在，但 Machine.status.phase 长时间仍为 Deleting，则 controller 可能根本无法与 DCS 通信。请检查 controller 日志：

kubectl -n cpaas-system logs deployment/cluster-api-provider-dcs-manager --tail=50

重点查找以下内容之一：

#DCS Account Lockout

errorCode: 10100116 表示集群的 credential Secret 中所配置的 DCS portal account 正处于暴力破解锁定窗口。DCS portal 的锁定策略会随着每次失败登录而重置，因此如果 controller 卡在重试循环中，会无限延长锁定时间。

要打破这个循环：

# 1. Scale the manager to 0 so it stops retrying
kubectl -n cpaas-system scale deployment cluster-api-provider-dcs-manager --replicas=0

# 2. Wait 5 minutes for the DCS lockout window to expire naturally
sleep 300

# 3. Restore the manager
kubectl -n cpaas-system scale deployment cluster-api-provider-dcs-manager --replicas=1

# 4. Verify the controller is happy
kubectl -n cpaas-system logs deployment/cluster-api-provider-dcs-manager --tail=20

生产环境中不要将 DCS portal 的 admin account 直接用于 provider 的 Secret。 请配置一个专用的 DCS account（interconnect 或 domain user，参见 Credential User Types），并放宽锁定策略，这样临时的 controller 故障就不会把平台整体锁死。

#FC Site Policy “仅能删除已停止虚拟机” (errorCode 102212808)

如果 workload cluster 运行在某个 DCS site 上，而其底层 FusionCompute 平台启用了“delete-only-when-stopped”安全策略，那么当 VM 仍处于 running 时，DeleteVm 会被拒绝。截至 cluster-api-provider-dcs v1.0.18，provider 的正常删除流程会在 DeleteVm 之前自动发出安全的 StopVm，但在极少数竞态条件下，外部 actor（例如 DCS portal 上的人工操作，或其他 automation）可能会在 controller 的 stop 检查与 DeleteVm 调用之间重新启动 VM。controller 会将该竞态暴露为：

Controller log:
  INFO  DeleteVm rejected by FC site policy, requeuing
        vmUrn=urn:sites:<site>:vms:<vm-id>
        errorCode=102212808

这不是错误——controller 会把 errorCode 102212808 视为可恢复并重新排队。下一次 reconcile 会重新检查 VM 状态；如果 VM 又变成 running，controller 会重新发出 StopVm(safe) 并继续执行。正常恢复时间约为 ~30 秒。

如果您反复看到该 errorCode（超过 3 次循环），说明有外部 actor 正在与 controller 争抢。请暂停外部 automation，或者应用 cpaas.io/retain-vm，将 VM 生命周期完全移交到 controller 之外管理。

#使用 cpaas.io/retain-vm 作为跳出手段

当 controller 因任何原因无法完成 reconcileDelete，且您需要释放 Machine finalizer 以便 workload cluster 继续推进（缩容、升级、移除）时，请为 Machine 或 DCSMachine 添加注解：

kubectl -n <ns> annotate machine <machine-name> cpaas.io/retain-vm=true

效果：

• controller 的 reconcileDelete 会识别该注解，跳过 ensureVmStopped 和 DeleteVm，并释放 DCSMachine finalizer。
• 随后 Machine 会退出 Deleting，Cluster API 可以完成其父级操作。

副作用——重要：

• VM 不会从 DCS 中删除——它仍保留在 DCS platform 上，继续占用计算和存储资源，不在 Cluster API 的生命周期管理范围内。
• DCSIpHostnamePool 中的 IP / hostname 槽位也不会释放——池条目会一直显示为仍在使用，直到您手动释放为止。

应用 retain-vm 之后，请计划手动执行以下操作：

1. 在 DCS portal 上停止并删除该 VM（或通过 DCS API 执行）。
2. 从对应的 DCSIpHostnamePool 中释放 IP / hostname 条目。
3. （可选）清理任何已挂载的 persistent disks。

#验证恢复

在应用上述任一解决方案后，请观察 DCSMachine，直到该 condition 消失：

kubectl -n <ns> describe dcsmachine <name>
# Look for: Conditions: VMStopPending  Status: True
#           (or the condition disappears as the resource is deleted)

kubectl -n <ns> get machines | grep <machine-name>
# Phase should transition: Deleting → (Machine gone within ~30s)

如果 Machine 已完全消失，且 VM 不再出现在 DCS portal 中，则表示恢复完成。

#另请参阅

• 在 Huawei DCS 上创建集群 — 完整的 cluster manifest 参考
• Huawei DCS 的 Cloud Credentials — Secret 格式和 User Types
• 排查卡在 Provisioned 中的 workload cluster — 与集群拉起问题相关的症状指南
• 排查卡在 Deleting 中的 cluster — 当所有 child machine 都消失后，顶层 Cluster CR 仍卡在 Deleting 中