VeleroArk备份删除卡死问题排查命名空间 Terminating 与 finalizer 清理实战【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文基于 Velero 仓库中 v0.8.0 时代遗留的官方排障文档site/content/docs/v0.8.0/debugging-deletes.md展开讲解 Kubernetes 备份工具 ArkVelero 前身在引入备份删除能力后暴露的命名空间无法销毁、备份无法删除的经典问题给出可直接复制的jq批量修复命令并结合当前仓库源码剖析 finalizer、删除控制器与命名空间隔离设计帮助你理解并彻底规避这类“删除卡死”故障。问题背景v0.7.0 引入的备份删除能力与它的副作用Ark 在v0.7.0 版本首次提供了删除备份的能力。实现方式是为每个 Backup 对象添加一个finalizer终结器。此后当你尝试删除整个heptio-ark命名空间时可能遭遇以下两类连锁故障命名空间进入Terminating状态后永远卡住无法被销毁卡住的命名空间内所有 Backup 资源无法被删除。要理解为什么“删除命名空间”会导致“备份也删不掉”需要先掌握 Kubernetes 的 finalizer 语义——这正是本文后续所有修复手段的理论基础。根因分析为什么命名空间会卡在 TerminatingKubernetes finalizer 的删除协议Kubernetes 对带 finalizer 的对象采用延迟删除机制官方文档对此的说明是当你请求删除一个带有至少一个 finalizer 的对象时Kubernetes 会为该对象设置deletionTimestamp表示“已标记删除”但对象不会立即消失——只有所有 finalizer 都被移除后对象才会真正被删除因此必须有一个“清理者”在 Ark 的场景里就是 Ark server来处理备份、执行清理然后移除 Ark 添加的 finalizer。换句话说Backup 对象的存在被 finalizer 显式“钉住”了删除必须由 Ark server 配合完成。触发条件Server 与备份资源同命名空间Arkv0.7.1 之前的版本将 Ark server Pod 与 backups、restores、schedules、Ark 配置放在同一个命名空间即heptio-ark中。当你执行kubectl delete namespace/heptio-ark时命名空间内所有对象的删除顺序是任意的arbitrary。Ark server Pod 完全可能在备份对象之前就被删除。一旦 server Pod 消失再没有任何进程去移除备份上的 Ark finalizer剩余的备份便永久停留在deleting状态而命名空间因仍含带 finalizer 的残留对象同样卡死在Terminating。这正是文档中“命名空间卡住、备份删不掉”这一现象的确切成因。修复方案用 jq 批量移除备份上的 finalizer文档给出的修复思路非常直接绕过已失效的 Ark server手动把每个 Backup 对象上的 Ark finalizer 摘掉让 Kubernetes 完成剩余的删除流程。借助jq可以用一条命令完成“查询 → 生成补丁 → 执行补丁”的全流程。前置条件安装 jq如果你的环境中还没有jq请先安装例如 Debian/Ubuntu 使用apt-get install jqmacOS 使用brew install jq。文档原文以链接形式引用了 jq 官方站点。核心命令bash (kubectl -n heptio-ark get backup -o json | jq -c -r $.items[] | kubectl -n heptio-ark patch backup/ .metadata.name -p \ (({metadata: {finalizers: ( (.metadata.finalizers // []) - [gc.ark.heptio.com]), resourceVersion: .metadata.resourceVersion}}) | tostring) \ --typemerge)命令逐段拆解片段作用kubectl -n heptio-ark get backup -o json以 JSON 形式拉取命名空间内全部 Backup 对象jq -c -r $ .items[] \| ...遍历每个备份压缩输出-c并去除引号-r逐条生成kubectl patch命令字符串.metadata.finalizers // []读取该备份现有的 finalizers 数组若字段缺失null则回退为空数组[]- [gc.ark.heptio.com]从数组中剔除Ark 的 GC finalizer——即保留除gc.ark.heptio.com外的其余 finalizerresourceVersion: .metadata.resourceVersion在补丁中携带当前resourceVersion确保以最新版本执行 merge patch--typemerge使用 JSON Merge Patch 策略合并元数据bash (...)将 jq 生成的命令列表直接交给 bash 执行命令实际生成的效果上述命令会先生成并运行一组形如以下的kubectl patch指令kubectl -n heptio-ark patch backup/my-backup -p {metadata:{finalizers:[],resourceVersion:461343}} --typemerge kubectl -n heptio-ark patch backup/some-other-backup -p {metadata:{finalizers:[],resourceVersion:461718}} --typemerge可以看到my-backup的 finalizers 数组被清空为[]resourceVersion取自查询时对象的最新版本。由于gc.ark.heptio.com是唯一被 Ark 添加的 finalizer清空后对象不再有任何阻止删除的因素Kubernetes 会将其彻底移除命名空间也能随之正常完成Terminating。手动检查与验证执行修复前可以先单独查询确认问题确实由 finalizer 引起kubectl -n heptio-ark get backup -o jsonpath{range .items[*]}{.metadata.name}{\t}{.metadata.finalizers}{\n}{end}若输出中存在gc.ark.heptio.com即印证了卡死原因。修复后再次执行应看到 finalizers 已为空数组kubectl get namespace heptio-ark也会从Terminating变为已删除。补充场景报错 “patching backups is not allowed” 怎么办文档特别提示了一种衍生情况如果执行 patch 时报错“patching backups is not allowed”说明 Ark 的CustomResourceDefinitionsCRDs可能已被删除——例如命名空间删除过程连带把 CRD 一并清理了导致 Kubernetes API 不再接受对backup资源的 patch 请求。此时需要先用官方提供的预置清单重建 CRDexamples/common/00-prereqs.yaml恢复 CRD 后再按上面的步骤重新执行批量 patch 即可。缓解措施v0.7.1 起强制命名空间隔离针对上述根因Arkv0.7.1 及以后版本修改了默认部署拓扑Ark server 运行在独立命名空间与 backups、schedules、restores 及 Ark 配置所在的命名空间分离。文档明确强烈建议保持该配置不变。这样设计的原因是即使你删除了存放备份数据的命名空间Ark server 依然存活仍有能力处理残留备份的 finalizer删除的“清理者”与“被清理对象”不再同生共死从架构上规避了“清理者先死 → 对象永久卡死”的死锁路径。这一隔离思路延续至今现代 Velero 默认将 server以及后来的 node-agent部署在velero命名空间而用户的备份数据则位于按需创建的其它命名空间中。源码视角现代 Velero 的删除与终结机制演进虽然gc.ark.heptio.com这个旧 finalizer 早已随历史版本更迭但“finalizer 延迟删除 专用清理控制器”的设计思想在当前仓库中得到了更完整的工程化落地可以通过源码进一步印证。1. 删除入口GC 控制器生成 DeleteBackupRequest过期备份的删除不再由用户直接触发而是由 pkg/controller/gc_controller.go 统一驱动gcReconciler专门“为过期备份创建 DeleteBackupRequest”// gcReconciler creates DeleteBackupRequests for expired backups.并复用event.DeleteEvent等事件机制来感知删除动作。2. 删除执行backup-deletion 控制器真正的删除逻辑集中在 pkg/controller/backup_deletion_controller.go 的backupDeletionReconciler中其Reconcile流程完整覆盖了各种边界情况忽略过期或重复的DeleteBackupRequest校验spec.backupName非空缺失即记录错误清理同名备份的既有删除请求保证同一时刻只有一个请求在处理通过backupTracker.Contains(...)拒绝删除仍在进行中的备份“backup is still in progress”备份不存在时将请求状态标记为 Processed 并记录 “backup not found”检查备份所属的BackupStorageLocation处于 read-only 模式的存储位置禁止删除备份。而DeleteBackupRequest对象的构造与查询工具位于 pkg/backup/delete_helpers.goNewDeleteBackupRequest(name, uid)负责按名称与 UID 创建删除请求NewDeleteBackupRequestListOptions(name, uid)则生成带标签选择器的查询参数。请求的相位常量如DeleteBackupRequestPhaseNew、InProgress、Processed定义了删除任务的状态机。3. 终结阶段backup-finalizer 控制器与旧版“server 顺手摘 finalizer”不同现代 Velero 将删除动作拆成独立阶段。备份在BackupPhaseFinalizing/BackupPhaseFinalizingPartiallyFailed阶段时由 pkg/controller/backup_finalizer_controller.go 的backupFinalizerReconciler接管它重新拉取 backup store 中的异步操作列表执行FinalizeBackup完成异步插件操作的收尾再把备份推进到Completed或PartiallyFailed。控制器名称注册在 pkg/constant/constant.goControllerBackupFinalizer backup-finalizer、ControllerBackupDeletion等并在 pkg/cmd/server/server.go 中按特性开关装配。4. 旧 finalizer 的彻底退役可以佐证的一点是changelogs/CHANGELOG-1.0.md 明确记录了“remove code that strips the gc.ark.heptio.com finalizer from backups”——即从 Velero 1.0 起旧版用于手工摘除该 finalizer 的兼容代码已被移除。这说明旧问题已在架构层面根治当前仓库的备份删除链路基于DeleteBackupRequest与专门的控制循环不再依赖“server 与数据同命名空间 顺手摘 finalizer”的脆弱设计。总结与最佳实践层面要点故障现象v0.7.0 起删除heptio-ark命名空间后卡在Terminating备份无法删除根因Backup 带 finalizerserver 与备份同命名空间时可能先于备份被删无人摘除 finalizer应急修复用jq批量生成kubectl patch剔除gc.ark.heptio.comfinalizer 并携带resourceVersion衍生故障“patching backups is not allowed” → 用examples/common/00-prereqs.yaml重建 CRD架构缓解v0.7.1 将 server 与备份数据分置于不同命名空间并沿用至今现代演进删除由gc_controller→DeleteBackupRequest→backup_deletion_controller驱动终结阶段由backup_finalizer_controller处理对仍在使用旧版 Arkv0.7.x的存量集群本文的jq修复命令是最稳妥的应急手段而对升级到现代 Velero 的用户理解这条删除链路GC 控制器 → 删除请求 → 删除/终结控制器有助于在遇到备份清理异常时快速定位到正确的控制器日志与DeleteBackupRequest状态避免再次陷入“删不掉”的困境。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考