Velero 备份钩子Backup Hooks完全指南在 Pod 容器中执行备份前后命令【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文围绕 Velero 的 Backup Hooks 机制展开介绍如何在备份 Pod 时于容器内部执行自定义命令用于在数据快照前完成文件系统冻结fsfreeze、数据库锁表FLUSH TABLES WITH READ LOCK等一致性保障操作。文章完整覆盖两种钩子定义方式Pod 注解与 Backup spec、pre/post 两种执行时机、命令编写技巧与执行结果查看方法并结合仓库源码剖析钩子底层执行链路pkg/podexec、internal/hook与 ItemBlock 分组执行语义帮助读者在真实集群中正确设计、调试和验证备份钩子。Backup Hooks 是什么Velero 在执行备份时支持在正在被备份的 Pod 的容器内执行一个或多个命令这类命令称为 Backup Hooks备份钩子。通过钩子你可以在快照/数据上传的关键时刻点执行应用级的一致性操作让备份出来的数据在逻辑上保持一致。钩子有两种执行时机见 pkg/apis/velero/v1/backup_types.go 中BackupResourceHook的pre/post定义与 internal/hook/item_hook_handler.go 中的PhasePre/PhasePost常量pre 钩子在任何自定义操作BackupItemAction处理之前执行post 钩子在所有自定义操作完成、且自定义操作产生的附加资源additional items都已备份完成之后执行。重要限制钩子不会在容器的 shell 中执行。命令由 Velero 通过 Kubernetes Pod Exec API 直接投递到容器进程因此如果需要 shell 能力如环境变量展开、串联必须显式在命令开头携带容器内受支持的 shell如/bin/sh、/bin/bash需要多个参数时命令必须写成 JSON 数组形式如[/usr/bin/uname, -a]。与 ItemBlock 的配合Velero 1.15自 Velero 1.15 起必须一起备份的相关资源被组织为ItemBlock见 pkg/itemblock/itemblock.go 与 pkg/backup/item_backupper.goPod 钩子的执行时机与 ItemBlock 的生命周期绑定pre 钩子在 ItemBlock 被备份之前运行post 钩子在 ItemBlock 备份完成之后运行。这意味着当某个 ItemBlock 包含多个 Pod例如一个 RWX 卷被多个 Pod 同时挂载时执行顺序为对 ItemBlock 内所有Pod 依次执行 pre 钩子备份 ItemBlock 内的各项资源对所有Pod 依次执行 post 钩子。这种先全部冻结、再统一备份、最后统一解冻的语义保证了同一共享卷在备份过程中处于一致状态。方式一通过 Pod 注解指定钩子在 Pod 上添加注解即可让 Velero 在备份该 Pod 时执行对应钩子。注解解析逻辑位于 internal/hook/item_hook_handler.go 的getPodExecHookFromAnnotations其关键点在于只要存在command注解即视为定义了钩子timeout解析失败时会告警并回退到默认值30s非法的on-error值会被忽略。Pre 钩子注解注解 Key说明默认值pre.hook.backup.velero.io/container命令执行的目标容器名Pod 中第一个容器可选pre.hook.backup.velero.io/command要执行的命令。默认不经 shell 执行需要 shell 时在命令开头带上容器支持的 shell如/bin/sh多参数时写为 JSON 数组如[/usr/bin/uname, -a]可选pre.hook.backup.velero.io/on-error命令返回非零退出码时的处理方式合法值为Fail和ContinueFail可选pre.hook.backup.velero.io/timeout命令执行等待时长超时视为钩子出错30s可选Post 钩子注解注解 Key说明默认值post.hook.backup.velero.io/container命令执行的目标容器名Pod 中第一个容器可选post.hook.backup.velero.io/command要执行的命令规则同 pre可选post.hook.backup.velero.io/on-error非零退出码处理方式合法值Fail/ContinueFail可选post.hook.backup.velero.io/timeout命令执行等待时长30s可选注解优先级源码中DefaultItemHookHandler.HandleHooksinternal/hook/item_hook_handler.go明确实现了一个优先级规则Pod 注解中定义的钩子优先于 Backup spec 中的钩子。若 Pod 没有command注解且该 Pod 也未被备份 spec 中的钩子选择器命中则该 Pod 不执行任何备份钩子。方式二在 Backup spec 中指定钩子除了注解还可以在Backup对象的spec.hooks.resources中声明资源级钩子。完整字段说明见 Backup API 类型文档其spec.hooks段定义了pre/post下仅支持exec类型钩子。核心 YAML 结构如下apiVersion: velero.io/v1 kind: Backup metadata: name: my-backup namespace: velero spec: includedNamespaces: - my-app hooks: resources: - name: my-hook includedNamespaces: - * excludedNamespaces: - kube-system includedResources: - pods excludedResources: [] labelSelector: matchLabels: app: my-app pre: - exec: container: my-container command: - /bin/uname - -a onError: Fail timeout: 10s post: - exec: container: my-container command: - /bin/sh - -c - echo backup done /tmp/backup-done.txt onError: Continue timeout: 30s字段说明name钩子名称会出现在备份日志中includedNamespaces/excludedNamespaces钩子适用的命名空间集合不指定则对所有命名空间生效includedResources目前仅支持podslabelSelector仅对匹配该标签选择器的对象生效pre/post数组中的每个execcontainer缺省时使用 Pod 第一个容器command必填onError缺省Failtimeout缺省 30s。源码侧GetBackupHooksFromSpecpkg/backup/backup.go会把Backup.spec.hooks转换为ResourceHook列表执行时由ResourceHookSelector.applicableTointernal/hook/item_hook_handler.go依次按命名空间、资源、标签选择器判断钩子是否适用于当前 Pod。实战示例使用 fsfreeze 冻结文件系统冻结文件系统可以确保快照前所有挂起的磁盘 I/O 已落盘是保证卷快照数据一致性的经典做法。本示例参考仓库自带样例 examples/nginx-app/with-pv.yaml。场景说明该样例部署了一个带 PVC 的 nginx 应用nginx 容器把日志写入 PVC 挂载的/var/log/nginx同 Pod 内还有一个特权容器fsfreeze基于ubuntu:bionicsecurityContext.privileged: true通过sleep infinity常驻其模板注解中已声明了 pre/post 钩子annotations: pre.hook.backup.velero.io/container: fsfreeze pre.hook.backup.velero.io/command: [/sbin/fsfreeze, --freeze, /var/log/nginx] post.hook.backup.velero.io/container: fsfreeze post.hook.backup.velero.io/command: [/sbin/fsfreeze, --unfreeze, /var/log/nginx]方式 A对已运行 Pod 就地添加注解如果不修改 Deployment 声明可以直接用kubectl annotate对运行中的 Pod 打注解注意直接修改 Pod 注解不会被 Deployment 回滚覆盖但 Pod 重建后注解会丢失生产环境更推荐方式 Bkubectl annotate pod -n nginx-example -l appnginx \ pre.hook.backup.velero.io/command[/sbin/fsfreeze, --freeze, /var/log/nginx] \ pre.hook.backup.velero.io/containerfsfreeze \ post.hook.backup.velero.io/command[/sbin/fsfreeze, --unfreeze, /var/log/nginx] \ post.hook.backup.velero.io/containerfsfreeze方式 B在 Deployment 模板中声明推荐把注解写进 Deployment 的spec.template.metadata.annotations即 examples/nginx-app/with-pv.yaml 中的写法这样 Pod 重建后钩子依然存在与声明式部署理念一致。验证钩子创建备份并检查执行情况velero backup create nginx-hook-test velero backup get nginx-hook-test velero backup logs nginx-hook-test | grep hookCommandvelero backup logs的输出来自执行器打出的结构化日志字段hookName、hookContainer、hookCommand、hookOnError、hookTimeout见 pkg/podexec/pod_command_executor.go从中可以看到 pre 钩子fsfreeze与 post 钩子unfreeze是否依次执行且无错误退出。钩子命令编写技巧多条命令钩子不经 shell 执行若要串联多条命令把整条命令包裹进 shell 并用;、等条件结构分隔pre.hook.backup.velero.io/command[/bin/bash, -c, echo hello hello.txt echo goodbye goodbye.txt]注意Pod 内必须存在/bin/bash或你选用的 shell否则命令无法执行。使用环境变量可以直接在钩子命令中引用 Pod 的环境变量但必须先用 shell 启动。例如 MySQL 容器中定义了MYSQL_ROOT_PASSWORD环境变量pre 钩子先启动/bin/sh再引用该变量pre: - exec: container: mysql command: - /bin/sh - -c - mysql --password$MYSQL_ROOT_PASSWORD -e FLUSH TABLES WITH READ LOCK onError: Fail该命令在备份前对 MySQL 施加全局只读锁FLUSH TABLES WITH READ LOCK保证后续卷快照中的数据一致对应的解锁动作应放在 post 钩子中执行如UNLOCK TABLES。同样容器必须支持你使用的 shell 命令。命令行注解的两种形态从源码parseStringToCommandinternal/hook/item_hook_handler.go可以看到注解值的解析规则以[开头时按 JSON 数组解析如[/usr/bin/uname, -a]否则整体作为单元素命令含空格也作为一个命令项。因此在注解中定义多参数命令时务必使用合法的 JSON 数组字符串。钩子执行结果的查看Velero 会记录钩子的执行结果并通过velero backup describe展示$ velero backup describe backup name输出中会包含如下两类统计若适用详细失败原因位于Errors段HooksAttempted: 1 HooksFailed: 0这两项指标在底层由HookTracker.Stat()计算并写入 Backup 状态见 pkg/backup/backup.go 中updated.Status.HookStatus.HooksAttempted, ... itemBackupper.hookTracker.Stat()最终渲染在 pkg/cmd/util/output/backup_describer.go 与 pkg/cmd/util/output/backup_structured_describer.go 中字段定义位于 pkg/apis/velero/v1/backup_types.go 的HookStatus。底层执行原理与源码走读1. 钩子调度ItemHookHandler备份过程中pkg/backup/item_backupper.go 通过itemHookHandler类型为hook.ItemHookHandler在每个 Pod 备份时按 pre/post 阶段调用HandleHooks。DefaultItemHookHandler.HandleHooksinternal/hook/item_hook_handler.go的核心逻辑仅对pods资源生效其他资源直接跳过优先读取 Pod 注解钩子pre 阶段还会兼容不带阶段前缀的旧版注解 key即hook.backup.velero.io/*若注解不存在则遍历 Backup spec 中的ResourceHook用ResourceHookSelector按命名空间/资源/标签选择器匹配每个钩子执行前调用hookTracker.Add执行后调用hookTracker.Recordinternal/hook/hook_tracker.go记录成败并累加HooksAttempted/HooksFailed计数当某钩子失败且其onError为Fail时记录modeFailError并停止执行后续钩子Continue则继续执行。2. 命令执行PodCommandExecutor真正的容器内命令执行由 pkg/podexec/pod_command_executor.go 完成其实现细节值得注意通过 Kubernetes Pod Exec APIPOST /api/v1/namespaces/{ns}/pods/{name}/execPodExecOptions指定容器与命令并同时捕获 stdout/stderr执行容器缺省规则hook.Container为空时取 Pod 第一个普通容器setDefaultHookContainer若显式指定的容器不存在会返回no such container错误支持普通容器与重启策略为Always的 sidecar 容器超时与上限timeout 0时回退默认值 30s同时存在硬上限maxHookTimeout 4h源码常量防止单个注解来源的钩子无限拖住备份超时通过context.WithTimeout真正取消 exec 流OnError 兜底非法的onError值统一按Fail处理Pod 已进入Succeeded/Failed阶段时跳过执行并记录日志不会报错执行日志通过hookCommand等结构化字段输出这正是velero backup logs ... | grep hookCommand能过滤到钩子记录的原因。3. 结果统计与展示HookTrackerinternal/hook/hook_tracker.go是并发安全的统计器Add增加尝试计数Record增加执行/失败计数并收集HookErrInfo。备份完成后pkg/backup/backup.go将统计写入Backup.Status.HookStatus随后velero backup describepkg/cmd/util/output/backup_describer.go将其渲染为HooksAttempted/HooksFailed两行输出。常见问题与注意事项钩子不经过 shell不要在注解里直接写echo $VAR这类依赖 shell 的语法必须显式携带/bin/sh -c或/bin/bash -c容器必须存在且支持命令指定的容器不存在会直接报no such container容器镜像里没有/bin/sh时 shell 形态的命令也会失败fsfreeze 需要特权容器如示例所示执行fsfreeze的容器需要securityContext.privileged: true并挂载目标卷onError 与备份成败pre 钩子失败且onError: Fail会终止该 Pod 的备份流程并产生错误Continue则只记录失败不中断备份注解 vs spec 的取舍注解适合少数 Pod 的快速定制spec 中的资源级钩子适合按命名空间/标签批量管理、且配置随 Backup 对象走超时上限单个钩子超时上限为 4 小时超时后钩子被判定为失败HooksFailed相应累加结果查询HooksAttempted/HooksFailed之外详细的失败原因需查看velero backup describe的Errors段或velero backup logs。小结Backup Hooks 是 Velero 保证应用级备份一致性的关键机制。通过 Pod 注解或 Backup spec 两种方式你可以精确地在快照/上传前后于容器内执行冻结、锁表等命令结合 ItemBlockVelero 1.15的分组语义多 Pod 共享卷场景也能获得统一冻结—统一备份—统一解冻的一致体验。配合velero backup describe中的HooksAttempted/HooksFailed统计与velero backup logs中的hookCommand日志你可以快速验证钩子是否按预期执行从而构建出生产级的数据保护流程。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
