彻底解决 k8s xxx 命名空间卡在 Terminating 的问题

前言

在 Kubernetes 集群管理中，命名空间（Namespace）卡在 Terminating 状态是一个常见但棘手的问题。这种状态通常由资源残留、Finalizers 未完成清理或控制器异常导致。本文将结合实践案例和底层原理，提供一套完整的解决方案，彻底解决此类问题。

一。问题现场

问题截图如下

在这里插入图片描述

另外 k8s中命名空间（Namespace）卡在 Terminating 状态可能还会导致以下问题

1. 集群网络功能异常

若卡在 Terminating 的命名空间属于网络插件（如 Calico），可能导致：

Pod 网络中断：新创建的 Pod 无法分配 IP 地址，跨节点通信失败。
网络策略失效：安全策略（如 NetworkPolicy）无法生效，集群暴露于未授权的访问风险中。
服务发现异常：依赖网络的服务（如 CoreDNS）无法正常工作，导致服务间无法解析域名。

2. 资源泄漏与控制器冲突

资源占用：残留的 CRD（自定义资源）、ServiceAccount 等资源持续占用集群资源（如 IP 池、存储卷）。
控制器逻辑混乱：重新部署同类组件时，新旧资源可能因同名 CRD 冲突，触发控制器崩溃或死锁。
Finalizers 死锁：命名空间的 finalizers 字段未释放，可能阻塞其他资源的删除操作（如 PV/PVC）。

3. 集群维护与升级受阻

运维复杂性增加：残留命名空间可能干扰后续组件的升级或迁移流程，导致部署失败。
监控误报：监控系统（如 Prometheus）可能因残留的指标端点持续告警，干扰运维判断。
依赖链断裂：若其他组件（如 Istio）依赖该命名空间的资源，可能引发级联故障。

4. 存储与持久化卷问题

PV/PVC 清理失败：存储控制器（如 Rook）依赖 Finalizers 确保数据安全，命名空间状态异常可能导致存储资源无法释放。
存储策略冲突：残留的存储配置可能影响新存储资源的分配策略

二、问题根源分析

Finalizers 未释放
Kubernetes 通过 finalizers 字段确保资源删除前的清理逻辑（如释放存储卷、级联删除关联资源）。若 Finalizers 中的控制器未响应或资源依赖未解除，删除流程会被阻塞。
残留资源未清理
命名空间内可能残留 ServiceAccount、CRD 自定义资源、Pod 等未被完全删除的组件，尤其是通过 Operator 或 Helm 安装的复杂应用（如 Calico、Prometheus）。
API 通信或控制器故障
集群组件（如 kube-controller-manager）异常或网络问题可能导致 Finalizers 清理失败。

三、解决方案详解

步骤 1：强制删除命名空间

通过 --force 参数跳过优雅终止期，直接触发删除逻辑：

kubectl delete ns <NAMESPACE_NAME> --force --grace-period=0

若失败，通常是由于残留资源或 Finalizers 未解除，需进入下一步。

步骤 2：手动清理残留资源

通过以下命令列出命名空间内所有资源并强制删除：

# 列出所有命名空间内资源类型
kubectl api-resources --verbs=list --namespaced -o name | xargs -n 1 kubectl get --show-kind --ignore-not-found -n <NAMESPACE_NAME># 强制删除残留资源（例如 ServiceAccount）
kubectl delete serviceaccount/<NAME> -n <NAMESPACE_NAME> --force --grace-period=0

关键点：
• 若资源删除失败，需手动移除其 Finalizers（参考步骤 3 对命名空间的操作）。

步骤 3：移除命名空间的 Finalizers

方法 1：通过 API 直接操作

# 查看命名空间下是否存在资源
kubectl get -n <NAMESPACE_NAME> -- all
# 导出命名空间配置
kubectl get ns <NAMESPACE_NAME> -o json > ns.json

# 删除 finalizers 字段（编辑 JSON 文件，移除 "finalizers": [...] 部分）

删除前
在这里插入图片描述
删除后

# 新建一个窗口执行
kubectl proxy# 当前服务器窗口执行
# calico-ns.json 替换为自己的json 文件 
# calico-system 替换为自己的namespace
curl -k -H Content-Type: application/json -X PUT --data-binary @calico-ns.json http://127.0.0.1:8001/api/v1/namespaces/calico-system/finalize# 执行完成后 关闭另一个窗口的代理
# 再次检查命名空间
kubectl get ns

在这里插入图片描述
发现之前命名空间 calico-system 一直在Terminating的状态现在已经正常了

作用：绕过控制器逻辑，直接解除 Finalizers 阻塞。

方法 2：使用 kubectl patch

kubectl patch namespace <NAMESPACE_NAME> -p '{"metadata":{"finalizers":[]}}' --type='merge'

此方法适用于未完全卡死的场景。

步骤 4：检查 Etcd 数据残留（可选）

若上述步骤无效，可能是 Etcd 中残留了命名空间的元数据：

# 进入 Etcd Pod 操作（假设使用默认部署）
kubectl exec -it -n kube-system etcd-<NODE_NAME> -- sh# 查询并删除残留数据
ETCDCTL_API=3 etcdctl get /registry/namespaces/<NAMESPACE_NAME>
ETCDCTL_API=3 etcdctl del /registry/namespaces/<NAMESPACE_NAME>

注意：直接操作 Etcd 存在风险，需谨慎执行。

三、进阶排查与修复

检查控制器日志
查看 kube-controller-manager 日志，定位 Finalizers 阻塞原因：

kubectl logs -n kube-system kube-controller-manager-<NODE_NAME> | grep "namespace/<NAMESPACE_NAME>"

修复 RBAC 权限问题
若匿名用户（如通过 kubectl proxy 调用 API）因权限不足导致删除失败，需绑定 ClusterRole：
```
kubectl create clusterrolebinding cluster-system-anonymous --clusterrole=cluster-admin --user=system:anonymous
```
此操作需评估安全风险。

四、总结与预防建议

预防措施
• 删除命名空间前，确保其内资源已清理。
• 避免直接删除由 Operator 管理的 CRD 资源（需先卸载 Operator）。
快速恢复流程
工具推荐
• 使用 kubectl-neat 插件清理资源 Finalizers。
• 通过 k9s 可视化工具快速定位残留资源。

通过以上步骤，可彻底解决命名空间卡在 Terminating 状态的问题。若仍存在异常，建议结合集群日志和组件健康状态进一步排查。