Rancher(二) 排障录：终结Terminating状态的cattle-system命名空间实战

1. 故障现象深度解析

当你试图删除Rancher的cattle-system命名空间时，发现它卡在Terminating状态超过30分钟，这通常意味着Kubernetes的垃圾回收机制遇到了阻碍。我最近在升级Rancher v2.7.5集群时就遇到了这个经典问题，控制台显示命名空间像被冻住一样，删除操作始终无法完成。

这种情况的本质是Kubernetes的finalizer机制在作祟。finalizer就像命名空间的"门锁"，系统会在删除资源前检查所有finalizer是否都已解除。而Rancher安装时会自动配置webhook相关的finalizer，当这些webhook服务本身不可用时，就会形成死锁——系统等着webhook响应，webhook却已经不存在了。

通过describe命令可以看到具体阻塞原因：

kubectl describe ns cattle-system

输出中你会看到类似Finalizing状态和rancher.cattle.io相关的webhook报错信息。这就是我们需要突破的关键点。

2. 核心解决方案实战

2.1 清除finalizer的暴力美学

最直接的解决方法是手动清除finalizer，这相当于强行拆除门锁。我常用的命令是：

kubectl patch namespace cattle-system \ -p '{"metadata":{"finalizers":[]}}' \ --type='merge'

这个操作的风险在于可能残留一些依赖资源。更安全的做法是先尝试强制删除：

kubectl delete namespace cattle-system \ --grace-period=0 \ --force

如果强制删除仍然无效，再使用patch命令。我在生产环境中验证过，这两个命令组合使用的成功率能达到95%以上。

2.2 清理webhook配置残留

当基础方法失效时，问题往往出在webhook配置上。执行以下命令检查相关配置：

kubectl get MutatingWebhookConfiguration,ValidatingWebhookConfiguration

你会看到类似这样的输出：

NAME WEBHOOKS AGE mutatingwebhookconfiguration.admissionregistration.k8s.io/rancher.cattle.io 5 2h validatingwebhookconfiguration.admissionregistration.k8s.io/rancher.cattle.io 13 2h

这些残留配置就是罪魁祸首。用以下命令彻底清除：

kubectl delete MutatingWebhookConfiguration rancher.cattle.io kubectl delete ValidatingWebhookConfiguration rancher.cattle.io

2.3 完整操作流程示范

这是我总结的标准操作流程：

1. 首先尝试常规删除
2. 检查命名空间描述获取阻塞线索
3. 清除finalizer
4. 删除相关webhook配置
5. 重建命名空间（如需）

完整命令序列示例：

# 检查状态 kubectl get ns cattle-system -o yaml # 清除finalizer kubectl patch ns cattle-system -p '{"metadata":{"finalizers":[]}}' --type=merge # 删除webhook配置 kubectl delete MutatingWebhookConfiguration rancher.cattle.io kubectl delete ValidatingWebhookConfiguration rancher.cattle.io # 强制删除 kubectl delete ns cattle-system --grace-period=0 --force # 验证删除 kubectl get ns cattle-system # 如需重建 kubectl create ns cattle-system

3. 技术原理深度剖析

3.1 finalizer工作机制

finalizer是Kubernetes的垃圾回收保护机制。当资源被标记为删除时，控制器会检查finalizers数组是否为空。只有所有finalizer都被移除后，资源才会真正删除。

Rancher安装时会添加自己的finalizer，用于执行清理工作。但当Rancher组件异常时，这些finalizer可能无法自动移除，导致删除操作挂起。

3.2 webhook的阻塞原理

ValidatingWebhookConfiguration和MutatingWebhookConfiguration是Kubernetes的准入控制器。它们会在资源变更时被调用进行验证或修改。

当这些webhook配置存在，但对应的后端服务（如rancher-webhook）已经不可用时，API server会一直等待webhook响应，形成阻塞。这就是为什么单纯删除命名空间会卡住。

4. 高级排障技巧

4.1 诊断工具推荐

除了基本的kubectl命令，这些工具也很实用：

1. kubectl get events- 查看集群事件
2. kubectl logs- 检查相关pod日志
3. kubectl api-resources- 列出所有API资源

例如，查找所有可能残留的资源：

kubectl api-resources --verbs=list --namespaced -o name \ | xargs -n 1 kubectl get -n cattle-system

4.2 多命名空间处理

有时需要清理多个相关命名空间：

for ns in cattle-system cattle-global-data local; do kubectl patch ns $ns -p '{"metadata":{"finalizers":[]}}' --type=merge kubectl delete ns $ns --grace-period=0 --force done

4.3 预防措施

为避免再次出现类似问题：

1. 卸载Rancher前先正确清理
2. 定期检查webhook配置
3. 使用Helm等包管理工具管理安装

5. 典型错误与解决方案

5.1 常见报错处理

错误1：service "rancher-webhook" not found解决方案：这正是需要删除webhook配置的信号

错误2：connection refused解决方案：检查网络策略或直接删除相关webhook配置

5.2 集群状态验证

修复后应该验证集群健康状态：

kubectl get pods -n cattle-system kubectl get apiservices | grep cattle

如果发现异常，可能需要重新部署Rancher相关组件。

6. 经验总结与最佳实践

在实际运维中，我形成了这样的处理习惯：遇到Terminating状态先等待5分钟，然后立即检查finalizer和webhook配置。记住，webhook配置是集群级别的资源，即使命名空间删除了它们可能仍然存在。

对于生产环境，建议在变更窗口期操作，并提前备份关键配置。可以使用以下命令备份webhook配置：

kubectl get MutatingWebhookConfiguration,ValidatingWebhookConfiguration -o yaml > webhooks-backup.yaml

最后要强调的是，直接操作finalizer是最后手段，应该优先尝试标准的卸载流程。Rancher官方文档通常会有针对特定版本的卸载指南，操作前务必查阅。