CAPIcluster or RKEControlPlane is paused

本文永久链接: https://www.xtplayer.cn/rancher/capi-cluster-or-rkecontrolplane-is-paused/

当 CAPI Cluster 或 RKEControlPlane 处于 paused 状态时，通常意味着集群或控制平面组件处于“暂停”状态，CAPI 控制器不会对其进行调和(Reconcile)操作，解决方法是找到并移除 spec.paused 标志。

“暂停”状态的含义

在 CAPI 中，.spec.paused: true 是一个维护标志——当集群被暂停时，控制器不会对其执行任何调和操作。这意味着：

创建、更新、删除等操作都不会被处理
集群状态会“卡住”，无法继续推进
这常用于故障排查或维护期间防止自动化操作干扰

paused 状态的常见原因

设置 paused: true 是一种防止控制器对集群进行更改的保护机制。了解其触发原因，有助于避免问题复发。

常见原因	说明
1.ETCD 快照恢复失败	在执行 etcd 快照恢复等 DR 操作时，如果流程意外中断或失败，集群可能卡在 paused 状态。通常按上述步骤手动`unpause`后，重新执行 DR 流程即可。
2. 维护或调试后忘记恢复	管理员在进行某些敏感操作（如手动编辑 etcd 或调试控制平面）时，可能会主动设置 `paused: true` 以暂停控制器，但结束后忘记恢复。
3. 自动化系统设置后未清除	某些自动化脚本或上层编排系统在特定场景下会自动设置该标志，若系统逻辑存在缺陷或任务异常退出，可能导致标志未被重置。

如何确认是否是这些原因？

检查事件与日志：通过查看集群事件或相关控制器的日志，可以定位是哪个操作触发了暂停。

# 查看集群相关事件
kubectl get events -n <命名空间> --field-selector involvedObject.name=<集群名称>

# 查看 CAPI 控制器日志
kubectl logs -n cattle-capi-system -l control-plane=controller-manager --tail=50[citation:1]

检查灾备操作状态：确认是否有备份或恢复操作正在进行或已失败

执行 unpause 操作后，控制器将恢复对集群的调和，集群状态应会逐步恢复正常。

如何检查是否处于暂停状态

在 Rancher 环境中，下游 RKE2 集群的 CAPI 资源位于 local 集群的 fleet-default 命名空间中。

# 查看集群的暂停状态
kubectl get clusters.cluster.x-k8s.io <集群名> -n fleet-default -o yaml | grep -i paused

# 或直接查看完整的 YAML
kubectl get clusters.cluster.x-k8s.io <集群名> -n fleet-default -o yaml

如何解除暂停状态

如果是简单的暂停状态，可以通过 patch 命令解除：

# 解除 CAPI Cluster 的暂停
kubectl patch cluster <集群名> -n <命名空间> --type merge -p '{"spec":{"paused": false}}'

对于 Rancher 管理的集群，具体路径为:

kubectl patch cluster <集群名> -n fleet-default --type merge -p '{"spec":{"paused": false}}'

附：CAPI 资源常用查询命令

为了方便排查，这里列出一些实用的查询命令：

# 查看所有 CAPI Cluster 及其暂停状态
kubectl get clusters.cluster.x-k8s.io -A -o wide

# 查看特定命名空间下的所有相关资源（集群、机器、部署）
kubectl get clusters,machines,machinedeployments -n <命名空间>[citation:1]

# 获取 CAPI 集群的详细状态（用于排查深层问题）
clusterctl describe cluster <集群名称> --namespace <命名空间> --show-conditions all[citation:1]