Velero DeleteItemAction 插件:为备份删除流程扩展清理能力的设计与实现
Velero DeleteItemAction 插件为备份删除流程扩展清理能力的设计与实现【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读在 Kubernetes 备份恢复领域Velero 的备份/恢复插件体系BackupItemAction、RestoreItemAction早已为备份与恢复过程提供了自定义扩展点但备份删除这一生命周期环节长期缺乏对应的插件机制当用户删除一个备份时那些由自定义插件创建在 Kubernetes 集群之外如云厂商对象存储、外部服务的资源将无人清理。本篇技术指南以 delete-item-action.md 设计文档为核心结合当前仓库的实际源码实现完整讲解 DeleteItemAction 插件 API 的定义、备份删除流程的改造方案、插件编写与注册方式以及 Velero 内置的 VolumeSnapshotContent 删除插件如何运用该机制帮助读者掌握通过 DeleteItemAction 在备份删除时安全、有序地清理外部资源的完整方案。DeleteItemAction 的设计动机与背景从 CSI 快照支持说起Velero 在引入 Container Storage InterfaceCSI快照支持时新增了通过 BackupItemAction 与 RestoreItemAction 插件来备份和恢复快照的模式。但社区开发者很快发现这套模式存在一个明显的缺口Velero 没有在备份删除阶段暴露任何扩展点导致这些 ItemAction 插件在备份/恢复期间创建的资源尤其是存在于 Kubernetes 集群之外的外部资源在备份被删除时无从清理。设计文档 delete-item-action.md 明确指出了这一痛点这些插件的核心诉求就是删除存在于 Kubernetes 之外的外部资源而当前设计正是要补齐备份删除时无扩展点的缺失环节。设计目标与非目标设计文档给出了清晰的范围界定Goals目标提供可供插件实现的 DeleteItemAction API修改 Velero 备份删除逻辑使其能够调用已注册的 DeleteItemAction 插件。Non Goals非目标不提供 DeleteItemAction API 的具体业务实现测试用例除外不提供 DeleteItemAction 执行的回滚机制。最后一点尤为关键由于备份删除是不可逆流程一旦备份中的卷快照、restic/Kopia 存储库快照或其他 DeleteItemAction 管理的资源已被删除没有任何途径可以恢复它们因此 DeleteItemAction 插件无法回滚其操作。整体架构备份删除流程如何与插件协同高层设计DeleteItemAction 插件 API 的设计与 RestoreItemAction 高度相似插件会接收到正在被删除的 VeleroBackupGo 结构体以及从备份 tarball 中解压出的、与之匹配的 Kubernetes 资源。备份删除流程的改造要点如下若存在任何已注册的 DeleteItemAction 插件则先从备份存储BackupStorageLocation下载备份 tarball 并解压这与现有恢复restore逻辑的处理方式一致遍历备份 tarball 中的每一个条目检查是否有 DeleteItemAction 插件与其匹配若匹配则将Backup对象与该条目一同传给 DeleteItemAction 插件执行。执行顺序与语义保证优先执行DeleteItemAction 插件在备份删除流程中最先运行先于从存储中删除快照、以及从 Kubernetes API Server 删除Restore对象等操作确定顺序多个 DeleteItemAction 插件按照其注册名称的字母数字顺序alphanumeric order执行错误容忍从源码看单个插件的 Execute 失败并不会中断整个删除流程错误会被收集聚合后返回使删除流程失败可重试从而避免插件管理的私有制品如数据移动仓库快照被永久孤立的风险见 delete_item_action_handler.go 中的deleteErrs收集逻辑。与备份删除控制器Deletion Controller的衔接实际实现位于 backup_deletion_controller.go。在processRequest中控制器会先通过插件管理器获取全部 DeleteItemAction 插件actions, err : pluginManager.GetDeleteItemActions()若没有插件len(actions) 0则按原有逻辑继续删除流程若存在一个或多个插件则先通过downloadToTempFile下载备份 tarball下载失败时若属于 tarball 不存在的永久性错误HTTP 404/not found则跳过插件直接继续删除若是瞬时错误限流、鉴权失败、网络问题则记录错误使删除失败以便重试下载成功后构造delete.Context包含 Backup、BackupReader、Actions、DiscoveryHelper 等调用delete.InvokeDeleteActions(deleteCtx)完成插件调用。DeleteItemAction API 详解Go 接口定义设计文档给出了接口原型最终落地的实现位于 pkg/plugin/velero/delete_item_action.go与设计基本一致仅输入结构体名称由设计稿的DeleteItemActionInput演进为DeleteItemActionExecuteInput// DeleteItemAction is an actor that performs an operation on an individual item being restored. type DeleteItemAction interface { // AppliesTo returns information about which resources this action should be invoked for. // A DeleteItemActions Execute function will only be invoked on items that match the returned // selector. A zero-valued ResourceSelector matches all resources. AppliesTo() (ResourceSelector, error) // Execute allows the ItemAction to perform arbitrary logic with the item being deleted. // An error should be returned if there were problems with the deletion process, but the // overall deletion process cannot be stopped. // Returned errors are logged. Execute(input *DeleteItemActionExecuteInput) error }两个方法的职责非常明确AppliesTo()声明该插件适用于哪些资源。Execute只会被那些与返回的选择器匹配的条目触发返回零值ResourceSelector表示匹配所有资源Execute(input)针对正在被删除的条目执行任意清理逻辑。输入结构体定义如下// DeleteItemActionExecuteInput contains the input parameters for the ItemActions Execute function. type DeleteItemActionExecuteInput struct { // Item is the item taken from the pristine backed up version of resource. Item runtime.Unstructured // Backup is the representation of the restore resource processed by Velero. Backup *velerov1api.Backup }其中Item取自备份 tarball 中原始备份版本pristine backed up version的runtime.Unstructured资源即不含任何恢复时修改的原始形态BackupVelero 正在处理并删除的*velerov1api.Backup结构体指针。ResourceSelector 字段AppliesTo()返回的ResourceSelector与 BackupItemAction / RestoreItemAction 共用同一类型支持以下过滤维度字段作用IncludedNamespaces仅匹配列出的命名空间ExcludedNamespaces排除列出的命名空间IncludedResources仅匹配列出的资源如volumesnapshotcontents.snapshot.storage.k8s.ioExcludedResources排除列出的资源LabelSelector通过标签选择器进一步过滤条目gRPC 通信层Protobuf 定义与客户端/服务端DeleteItemAction 插件采用与 BackupItemAction / RestoreItemAction 完全相同的 HashiCorp go-plugin gRPC 通信模型。Protobuf 定义设计文档规划的pkg/plugin/proto/DeleteItemAction.proto已落地见 DeleteItemAction.protomessage DeleteItemActionExecuteRequest { string plugin 1; bytes item 2; bytes backup 3; } message DeleteItemActionAppliesToRequest { string plugin 1; } message DeleteItemActionAppliesToResponse { ResourceSelector ResourceSelector 1; } service DeleteItemAction { rpc AppliesTo(DeleteItemActionAppliesToRequest) returns (DeleteItemActionAppliesToResponse); rpc Execute(DeleteItemActionExecuteRequest) returns (Empty); }注意ExecuteRPC 的返回类型是Empty与设计文档的DeleteItemActionExecuteResponse相比落地实现做了简化——因为Execute没有返回值需要传递错误直接通过 gRPC error 通道返回。服务端实现服务端位于 delete_item_action_server.go。其核心逻辑是通过getImpl(req.Plugin)从ServerMux中按插件名解析出实际的velero.DeleteItemAction实现AppliesTo调用将插件返回的ResourceSelector各字段映射为 proto 消息中的ResourceSelectorExecute调用将请求中的item与backupJSON 字节流分别反序列化为unstructured.Unstructured与api.Backup构造velero.DeleteItemActionExecuteInput后转发给插件实现两个方法都通过common.HandlePanic捕获插件 panic 并转换为 gRPC 错误。客户端实现客户端位于 delete_item_action_client.go实现了velero.DeleteItemAction接口AppliesTo()向 gRPC server 发起调用并还原ResourceSelectorExecute(input)将input.Item.UnstructuredContent()与input.Backup分别 JSON 序列化为字节流构造DeleteItemActionExecuteRequest发送返回的响应是空结构体实际错误通过 gRPC error 传递。插件框架的接线位于 server.go// RegisterDeleteItemAction registers a delete item action. Accepted format RegisterDeleteItemAction(pluginName string, initializer common.HandlerInitializer) Server RegisterDeleteItemActions(map[string]common.HandlerInitializer) Server可重启插件进程restartableDeleteItemAction与 RestoreItemAction / BackupItemAction 一样DeleteItemAction 也实现了可重启restartable的进程包装代码位于 restartable_delete_item_action.go// restartableDeleteItemAction is a delete item action for a given implementation (such as pod). It is associated with // a restartableProcess, which may be shared and used to run multiple plugins. At the beginning of each method // call, the restartableDeleteItemAction asks its restartableProcess to restart itself if needed (e.g. if the // process terminated for any reason), then it proceeds with the actual call. type restartableDeleteItemAction struct { key process.KindAndName sharedPluginProcess process.RestartableProcess } func NewRestartableDeleteItemAction(name string, sharedPluginProcess process.RestartableProcess) *restartableDeleteItemAction其方法语义如下方法行为getDeleteItemAction()返回当前插件进程中的 DeleteItemAction 实现不触发进程重启getDelegate()先通过ResetIfNeeded()在必要时重启插件进程再返回插件实现AppliesTo()/Execute()均先经getDelegate()确保进程健康再委托给实际实现这种设计保证了当插件进程因任何原因崩溃后后续调用能够自动拉起新进程继续工作。插件的插件种类标识PluginKindDeleteItemAction字符串值为DeleteItemAction定义于 plugin_kinds.go。插件管理器扩展设计文档规划的Manager接口扩展已落地于 manager.go// GetDeleteItemActions returns all delete item action plugins. GetDeleteItemActions() ([]velero.DeleteItemAction, error) // GetDeleteItemAction returns the delete item action plugin for name. GetDeleteItemAction(name string) (velero.DeleteItemAction, error)其实现要点包括GetDeleteItemActions遍历注册表中所有PluginKindDeleteItemAction种类的插件逐个通过GetDeleteItemAction(id.Name)获取并聚合GetDeleteItemAction按名称获取restartableProcess并包装为restartableDeleteItemAction与其它插件类型一致二者对velero.io/前缀的命名空间插件有相同的例外处理逻辑源码注释提及DeleteItemActions 引入时插件体系已经是命名空间化的因此旧的非命名空间插件中不包含 DeleteItemAction。备份 tarball 解析与插件分发InvokeDeleteActions设计文档描述的核心流程——下载 tarball、解压、逐条匹配并调用插件——在 delete_item_action_handler.go 中完整实现func InvokeDeleteActions(ctx *Context) error其中Context提供了插件执行所需的全部环境type Context struct { Backup *velerov1api.Backup BackupReader io.Reader Actions []velero.DeleteItemAction Filesystem filesystem.Interface Log logrus.FieldLogger DiscoveryHelper discovery.Helper resolvedActions []framework.DeleteItemResolvedAction }整体执行流程分五个阶段解析动作通过framework.NewDeleteItemActionResolver(ctx.Actions)构造解析器调用ResolveActions(helper, log)借助 discovery helper 将每个插件的AppliesTo()声明解析为DeleteItemResolvedAction内部组合了resolvedAction包含资源 Include/Exclude、命名空间 Include/Exclude 与标签选择器若没有任何已解析动作且无错误直接返回 nil按原流程继续删除解压 tarball通过archive.NewExtractor(...).UnzipAndExtractBackup(ctx.BackupReader)将备份解压到临时目录defer中清理临时目录解析备份内容通过archive.NewParser(...).Parse(dir)解析出backupResources按 group/resource → namespace → items 组织若备份中无资源目录archive.ErrNotExist则忽略插件直接返回逐资源分发外层遍历每个 groupResource已处理过的跳过内层按命名空间分组先通过ctx.getApplicableActions(groupResource, namespace)一次性过滤出适用于该组/资源与命名空间的动作列表再遍历每个条目通过archive.GetItemFilePath与archive.Unmarshal从 tarball 恢复出unstructured.Unstructured对象对每个动作先检查action.Selector.Matches(labels.Set(obj.GetLabels()))标签选择器匹配才触发匹配后调用action.DeleteItemAction.Execute(...)聚合错误单个插件执行失败不会终止循环保证剩余条目的清理不被阻塞但错误会被收集进deleteErrs最终通过kubeerrs.NewAggregate(deleteErrs)返回——若返回非 nil 错误控制器会让删除失败以便后续重试避免插件管理的私有制品被永久孤立。编写并注册一个 DeleteItemAction 插件注册 API插件进程内通过 framework server 注册见 server.gos.RegisterDeleteItemAction(example.io/delete-item-action, newDeleteItemAction)或批量注册s.RegisterDeleteItemActions(map[string]common.HandlerInitializer{ example.io/foo: fooInitializer, example.io/bar: barInitializer, })仓库中的示例examples_test.go展示了完整的实现骨架func newDeleteItemAction(logger logrus.FieldLogger) (any, error) { return DeleteItemAction{FieldLogger: logger}, nil } type DeleteItemAction struct { FieldLogger logrus.FieldLogger } func (d *DeleteItemAction) AppliesTo() (velero.ResourceSelector, error) { d.FieldLogger.Infof(AppliesTo called) // ... return velero.ResourceSelector{}, nil } func (d *DeleteItemAction) Execute(input *velero.DeleteItemActionExecuteInput) error { d.FieldLogger.Infof(Execute called) // ... return nil }实战编写要点基于源码语义编写插件时应遵循以下要点AppliesTo尽量收窄只声明本插件负责的资源类型与命名空间范围避免零值选择器匹配全部带来的不必要开销与误清理风险在Execute中做幂等与防御性判断由于删除流程可能因瞬时错误重试Execute应具备幂等性。可参考内置插件通过input.Backup.Name与资源标签判断该资源是否由本次备份创建的方式见下文内置插件善用input.Item与input.Backupinput.Item是备份时的原始资源形态input.Backup提供备份的名称、命名空间、标签等信息可用于关联判断错误处理Execute返回错误会导致整个删除流程失败可重试因此要区分永久性错误返回错误与无需处理的正常跳过返回 nil。内置参考实现VolumeSnapshotContent 删除插件设计文档明确指出Specific implementations of the DeleteItemAction API beyond test cases不在目标范围内但当前仓库的 CSI 删除动作已内置了一个真实的生产级实现——volumesnapshotcontent_action.go 中的volumeSnapshotContentDeleteItemAction。它是理解 DeleteItemAction 最佳实践的绝佳范本。AppliesTo 声明func (p *volumeSnapshotContentDeleteItemAction) AppliesTo() (velero.ResourceSelector, error) { return velero.ResourceSelector{ IncludedResources: []string{volumesnapshotcontents.snapshot.storage.k8s.io}, }, nil }该插件只处理volumesnapshotcontents.snapshot.storage.k8s.io资源。Execute 的防御性逻辑Execute内部体现了前面提到的关键实践将input.Item.UnstructuredContent()通过runtime.DefaultUnstructuredConverter.FromUnstructured转换为强类型的snapshotv1api.VolumeSnapshotContent关键防御通过kubeutil.HasBackupLabel(snapCont.ObjectMeta, input.Backup.Name)检查 VolumeSnapshotContent 是否带有本次备份名称的标签——若没有说明该快照并非由 Velero 创建直接跳过删除避免误删用户手工创建的快照if !kubeutil.HasBackupLabel(snapCont.ObjectMeta, input.Backup.Name) { p.log.Infof( VolumeSnapshotContent %s was not taken by backup %s, skipping deletion, snapCont.Name, input.Backup.Name, ) return nil }兼容性处理优先尝试从集群删除原始 VSC兼容 1.15 之前DeletionPolicyRetain的旧备份遗留场景若原始 VSC 已不在集群中则创建一个临时 VSCvsc-uuid并将DeletionPolicy置为VolumeSnapshotContentDelete以触发云侧底层快照的删除删除后再清理临时 VSC。其单元测试 volumesnapshotcontent_action_test.go 覆盖了AppliesTo、Execute的各类分支以及创建-睡眠-删除的时序场景可作为编写与验证自定义 DeleteItemAction 插件的测试范式参考。备选方案回顾为什么不是别的方式设计文档对曾考虑过的备选方案做了记录更高级别的 DeleteItemActions 提案最初曾考虑过更高层的 DeleteItemAction需要实现者自行下载备份 tarball。虽然长期看可能有用但每个插件都要重复实现大量样板代码与当前目标不匹配该备选方案详见 deletion-plugins.mdVolumeSnapshotter 接口该接口专门用于对块设备拍摄快照通用性不足以满足本需求。安全性考量DeleteItemAction插件的本质是删除数据这通常属于安全敏感操作。设计文档给出的安全论证是这类插件只会在两种场景下被触发——一是用户通过veleroCLI 或其他管理系统发起BackupDeleteRequest二是 VeleroBackup因超过 TTL 而过期被自动清理。由于触发路径都是受控的管理操作数据删除风险是可控的。兼容性向后兼容性方面该设计对大多数升级中的 Velero 安装是兼容的若未安装任何 DeleteItemAction 插件备份删除流程与引入插件之前完全一致。这一保证在实现层面得到双重印证——控制器中len(actions) 0时直接走原流程InvokeDeleteActions中无已解析动作且无错误时直接返回 nil。实现顺序与扩展建议设计文档建议的实现依赖顺序与 Detailed Design 章节的叙述顺序一致落地实现也遵循了这条路径API 类型pkg/plugin/velero→ Protobuf 与 gRPC 客户端/服务端pkg/plugin/proto、pkg/plugin/framework→ 可重启包装pkg/plugin/clientmgmt→ 插件管理器manager.go→ 删除控制器改造pkg/controller→ tarball 解析与分发internal/delete。对于希望为 Velero 补充外部资源清理能力的开发者推荐按以下路径深入当前仓库阅读 delete-item-action.md 设计文档掌握全貌阅读 delete_item_action.go 与 DeleteItemAction.proto 理解 API 契约对照 delete_item_action_handler.go 理解分发语义参照 volumesnapshotcontent_action.go 编写首个插件实现与测试。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

IoT-For-Beginners 实战:用传感器与执行器构建光控夜灯(Wio Terminal / Raspberry Pi / 虚拟设备)

IoT-For-Beginners 实战:用传感器与执行器构建光控夜灯(Wio Terminal / Raspberry Pi / 虚拟设备)

IoT-For-Beginners 实战:用传感器与执行器构建光控夜灯(Wio Terminal / Raspberry Pi / 虚拟设备) 【免费下载链接】IoT-For-Beginners 12 Weeks, 24 Lessons, IoT for All! 项目地址: https://gitcode.com/GitHub_Trending/io/IoT-For-Beg…

2026/11/12 2:00:05 阅读更多 →
拆解无JS电商静态页:多CSS文件与纯CSS交互方案

拆解无JS电商静态页:多CSS文件与纯CSS交互方案

简介:一套源自一号店早期官网的静态HTML源代码,面向前端入门者、网页设计人员及电商平台研究者,用于学习纯HTMLCSS构建电商页面的经典方式。压缩包共330个文件,约2.97MB,图片素材占绝大多数,包括189个JPG、…

2026/11/17 4:51:17 阅读更多 →
AKAZE特征提取详解:OpenCV实现与匹配调优指南

AKAZE特征提取详解:OpenCV实现与匹配调优指南

简介:这是一份基于MATLAB实现的AKAZE特征提取源码,面向计算机视觉初学者、图像处理研究者以及需要快速特征匹配的开发者。AKAZE算法通过非线性尺度空间构建与局部梯度极值检测定位关键点,并生成具有旋转、尺度及光照不变性的二进制描述符&…

2026/11/9 18:42:10 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/16 8:22:12 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/16 6:41:34 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/16 8:22:12 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/16 8:22:12 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/16 7:30:18 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/16 8:22:12 阅读更多 →

日新闻

周新闻

月新闻