VeleroHeptio ArkBackup Hooks 完全指南用 pre/post Hooks 实现备份前后自定义命令【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文基于 Velero 项目早期版本v0.8.0彼时项目名为 Heptio Ark的官方文档 hooks.md 编写系统讲解备份Backup过程中如何让 Velero 在被备份的 Pod 容器内执行自定义命令。你将掌握两种 hooks 声明方式Pod 注解与 Backup spec、pre/post 两类执行时机以及以fsfreeze冻结文件系统为代表的真实生产场景并结合 backup_types.go 源码理解 hooks 的底层数据模型与错误处理语义。Backup Hooks 是什么Heptio Ark现 Velero在执行备份时支持在被备份的 Pod 的容器中执行一条或多条命令这类命令称为Backup Hooks。核心价值在于你可以在对象被序列化进备份这一时刻的前后插入自定义动作为那些需要一致性保证的应用如数据库、文件系统提供数据固化能力。两类执行时机pre 与 postpre hooks备份前钩子在 Pod 被备份、且任何自定义 actionitem action处理之前执行。Ark v0.7.0 之前的版本只支持这一种 hooks。post hooks备份后钩子在所有自定义 action 完成、且自定义 action 所产生的所有附加对象additional items都已被备份之后执行。该能力自 v0.7.0 起引入。当前版本main 分支的文档 backup-hooks.md 补充了一个重要细节hooks 不会在容器的 shell 中被执行not executed within a shell。因此如果你的命令需要 shell 语法管道、环境变量、连接必须在 command 数组开头显式放入容器支持的 shell 解释器如/bin/sh。典型场景冻结文件系统文档给出的经典示例是文件系统冻结。如果你希望在磁盘快照前确保所有待处理的磁盘 I/O 已完成用pre hook执行fsfreeze --freeze冻结文件系统Ark 对磁盘拍摄快照用post hook执行fsfreeze --unfreeze解冻文件系统。方式一通过 Pod 注解指定 Hooks在 Pod 上声明注解即可让 Ark 备份该 Pod 时执行 hook。v0.8.0 文档中的注解域名为backup.ark.heptio.com在后续版本中更名为backup.velero.io见 backup-hooks.md。Pre hooks 注解注解名称说明pre.hook.backup.ark.heptio.com/container命令执行的容器。默认使用 Pod 中的第一个容器。可选。pre.hook.backup.ark.heptio.com/command要执行的命令。如需多个参数请将命令写成 JSON 数组例如[/usr/bin/uname, -a]。pre.hook.backup.ark.heptio.com/on-error命令返回非零退出码时的处理策略。默认Fail合法值为Fail与Continue。可选。pre.hook.backup.ark.heptio.com/timeout命令执行的最大等待时间超时即视为 hook 出错。默认30s。可选。Post hooks 注解v0.7.0注解名称说明post.hook.backup.ark.heptio.com/container命令执行的容器。默认使用 Pod 中的第一个容器。可选。post.hook.backup.ark.heptio.com/command要执行的命令。如需多个参数请将命令写成 JSON 数组例如[/usr/bin/uname, -a]。post.hook.backup.ark.heptio.com/on-error命令返回非零退出码时的处理策略。默认Fail合法值为Fail与Continue。可选。post.hook.backup.ark.heptio.com/timeout命令执行的最大等待时间超时即视为 hook 出错。默认30s。可选。兼容性说明重要Ark v0.7.0继续支持旧式的 pre hook 写法——即注解名不带pre.前缀例如hook.backup.ark.heptio.com/container但该写法已被标记为deprecated已弃用。实战给已有 Pod 打上 fsfreeze 注解仓库中的 examples/nginx-app/with-pv.yaml 就是一个完整的声明式示例Deployment 的 Pod 模板通过注解声明了 pre/post 两组 fsfreeze 命令并专门部署了一个名为fsfreeze的privileged: true辅助容器Ubuntu 镜像、挂载/var/log/nginx来执行冻结/解冻操作。如果要对一个已运行的 Pod 原地添加注解可参考 backup-hooks.md 中的命令注意新版注解域名kubectl 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方式二在 Backup spec 中指定 Hooks对于更精细的控制如按 namespace / resource / label 筛选 hook 的生效范围应在 Backup 自定义资源对象的spec.hooks字段中声明。v0.8.0 的 Backup API 完整示例见 site/content/docs/v0.8.0/api-types/backup.md其中 hooks 部分的骨架如下apiVersion: ark.heptio.com/v1 kind: Backup metadata: name: a namespace: heptio-ark spec: # ... 其他备份参数includedNamespaces 等 hooks: # 适用于特定资源的 hooks 数组。可选。 resources: - # hook 名称会显示在备份日志中。 name: my-hook # 该 hook 生效的 namespace 数组。不指定则应用于所有 namespace。可选。 includedNamespaces: - * # 该 hook 不生效的 namespace 数组。可选。 excludedNamespaces: - some-namespace # 该 hook 生效的资源类型数组。当前仅支持 pods。可选。 includedResources: - pods # 该 hook 不生效的资源类型数组。可选。 excludedResources: [] # 只有匹配该 label selector 的对象才生效。可选。 labelSelector: matchLabels: app: ark component: server # 在自定义 actions 执行前运行的 hooks 数组。当前仅支持 exec 类型。 # 已弃用请改用 pre。 hooks: # 内容与下面的 pre 相同。 # 在自定义 actions 执行前运行的 hooks 数组。当前仅支持 exec 类型。 pre: - # hook 类型必须为 exec。 exec: # 执行命令的容器名。不指定则使用 Pod 中的第一个容器。可选。 container: my-container # 要执行的命令以数组形式给出。必填。 command: - /bin/uname - -a # 命令执行出错时的处理方式。合法值为 Fail 和 Continue默认 Fail。可选。 onError: Fail # 等待命令执行完成的最长时间。默认 30 秒。可选。 timeout: 10s # 在所有自定义 actions 及附加对象处理完毕后运行的 hooks 数组。当前仅支持 exec 类型。 post: # 内容与上面的 pre 相同。在 spec 中使用 shell 与环境变量由于 hook 命令默认不经过 shell若需要多条命令或读取容器环境变量需要显式包装 shell。例如要对名为mysql的 Pod 使用其MYSQL_ROOT_PASSWORD环境变量执行FLUSH TABLES WITH READ LOCK该写法来自 backup-hooks.md注意当前版本使用velero.io资源pre: - exec: container: mysql command: - /bin/sh - -c - mysql --password$MYSQL_ROOT_PASSWORD -e FLUSH TABLES WITH READ LOCK onError: Fail使用多条命令时可以把目标命令包进 shell用;、等连接例如pre.hook.backup.velero.io/command[/bin/bash, -c, echo hello hello.txt echo goodbye goodbye.txt]注意容器内必须存在你所引用的 shell 解释器。源码级解析Hooks 的数据模型与错误语义从 pkg/apis/velero/v1/backup_types.go 可以看到 hooks 在 Velero API 中的完整类型定义与上面 YAML 一一对应BackupHooks仅包含Resources []BackupResourceHookSpec一个字段即针对具体资源的 hooks 数组BackupResourceHookSpec承载筛选规则includedNamespaces、excludedNamespaces、includedResources、excludedResources、labelSelector以及两类执行序列PreHooks与PostHooksBackupResourceHook目前只封装Exec *ExecHook一种实现即通过 Kubernetes Pod Exec API 在容器内执行命令这一点与 v0.8.0 文档中当前仅支持 exec 类型的描述一致ExecHook字段Container默认第一个容器、Commandkubebuilder:validation:MinItems1即命令数组至少一项、OnError、Timeoutmetav1.Duration。HookErrorModeFail 与 Continue 的真实语义HookErrorMode是 hooks 错误处理的核心枚举源码注释给出了精确语义HookErrorModeContinuehook 出错可接受备份/恢复继续执行其余 hooks最终备份状态为PartiallyFailedHookErrorModeFailhook 出错是严重问题Velero 会停止执行后续 hooks备份状态同样为PartiallyFailed。可见Fail与Continue的区别在于是否继续执行后续 hooks而非整个备份是否失败——两者最终都表现为PartiallyFailed这与很多使用者的直觉不同。Hook 执行结果的统计在 pkg/backup/backup.go 中备份完成时 Velero 会将itemBackupper.hookTracker统计的HooksAttempted尝试执行的 hook 数与HooksFailed失败的 hook 数写入备份状态updated.Status.HookStatus.HooksAttempted, updated.Status.HookStatus.HooksFailed itemBackupper.hookTracker.Stat()相应地用户可通过velero backup describe backup name查看这两项统计若存在失败详细原因会出现在Errors部分HooksAttempted: 1 HooksFailed: 0验证与排障创建备份并观察按上面的注解或 spec 配置好 hooks 后创建备份velero backup create nginx-hook-test查看备份状态velero backup get nginx-hook-test确认备份未进入PartiallyFailed/Failed状态。检查 hook 执行日志velero backup logs nginx-hook-test | grep hookCommand用于确认 pre/post hook 是否被触发且正常退出在 v0.8.0 时代日志中可通过hookCommand关键字过滤当前版本已升级为通过velero backup describe查看 HooksAttempted/HooksFailed 统计。关注状态字段备份处于PartiallyFailed时优先在备份描述与日志的 Errors 段中定位具体是哪个 hook、哪条命令出错再依据onError语义决定是修复命令还是改为Continue放行。小结Backup Hooks 是 Velero 实现应用一致性备份的关键机制pre hook 在对象备份前执行post hook 在自定义 action 及其附加对象全部备份后执行二者搭配即可覆盖冻结—快照—解冻这类完整时序。声明方式上Pod 注解适合快速、单对象的钩子注入注意ark.heptio.com旧域名及其不带pre.前缀的弃用写法Backup spec 则提供按 namespace/resource/label 筛选的精细控制。理解Fail/Continue与PartiallyFailed状态的关系以及HooksAttempted/HooksFailed统计能帮助你更准确地解读备份结果并快速定位问题。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Velero（Heptio Ark）Backup Hooks 完全指南：用 pre/post Hooks 实现备份前后自定义命令
VeleroHeptio ArkBackup Hooks 完全指南用 pre/post Hooks 实现备份前后自定义命令【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero导读本文基于 Velero 项目早期版本v0.8.0彼时项目名为 Heptio Ark的官方文档 hooks.md 编写系统讲解备份Backup过程中如何让 Velero 在被备份的 Pod 容器内执行自定义命令。你将掌握两种 hooks 声明方式Pod 注解与 Backup spec、pre/post 两类执行时机以及以fsfreeze冻结文件系统为代表的真实生产场景并结合 backup_types.go 源码理解 hooks 的底层数据模型与错误处理语义。Backup Hooks 是什么Heptio Ark现 Velero在执行备份时支持在被备份的 Pod 的容器中执行一条或多条命令这类命令称为Backup Hooks。核心价值在于你可以在对象被序列化进备份这一时刻的前后插入自定义动作为那些需要一致性保证的应用如数据库、文件系统提供数据固化能力。两类执行时机pre 与 postpre hooks备份前钩子在 Pod 被备份、且任何自定义 actionitem action处理之前执行。Ark v0.7.0 之前的版本只支持这一种 hooks。post hooks备份后钩子在所有自定义 action 完成、且自定义 action 所产生的所有附加对象additional items都已被备份之后执行。该能力自 v0.7.0 起引入。当前版本main 分支的文档 backup-hooks.md 补充了一个重要细节hooks 不会在容器的 shell 中被执行not executed within a shell。因此如果你的命令需要 shell 语法管道、环境变量、连接必须在 command 数组开头显式放入容器支持的 shell 解释器如/bin/sh。典型场景冻结文件系统文档给出的经典示例是文件系统冻结。如果你希望在磁盘快照前确保所有待处理的磁盘 I/O 已完成用pre hook执行fsfreeze --freeze冻结文件系统Ark 对磁盘拍摄快照用post hook执行fsfreeze --unfreeze解冻文件系统。方式一通过 Pod 注解指定 Hooks在 Pod 上声明注解即可让 Ark 备份该 Pod 时执行 hook。v0.8.0 文档中的注解域名为backup.ark.heptio.com在后续版本中更名为backup.velero.io见 backup-hooks.md。Pre hooks 注解注解名称说明pre.hook.backup.ark.heptio.com/container命令执行的容器。默认使用 Pod 中的第一个容器。可选。pre.hook.backup.ark.heptio.com/command要执行的命令。如需多个参数请将命令写成 JSON 数组例如[/usr/bin/uname, -a]。pre.hook.backup.ark.heptio.com/on-error命令返回非零退出码时的处理策略。默认Fail合法值为Fail与Continue。可选。pre.hook.backup.ark.heptio.com/timeout命令执行的最大等待时间超时即视为 hook 出错。默认30s。可选。Post hooks 注解v0.7.0注解名称说明post.hook.backup.ark.heptio.com/container命令执行的容器。默认使用 Pod 中的第一个容器。可选。post.hook.backup.ark.heptio.com/command要执行的命令。如需多个参数请将命令写成 JSON 数组例如[/usr/bin/uname, -a]。post.hook.backup.ark.heptio.com/on-error命令返回非零退出码时的处理策略。默认Fail合法值为Fail与Continue。可选。post.hook.backup.ark.heptio.com/timeout命令执行的最大等待时间超时即视为 hook 出错。默认30s。可选。兼容性说明重要Ark v0.7.0继续支持旧式的 pre hook 写法——即注解名不带pre.前缀例如hook.backup.ark.heptio.com/container但该写法已被标记为deprecated已弃用。实战给已有 Pod 打上 fsfreeze 注解仓库中的 examples/nginx-app/with-pv.yaml 就是一个完整的声明式示例Deployment 的 Pod 模板通过注解声明了 pre/post 两组 fsfreeze 命令并专门部署了一个名为fsfreeze的privileged: true辅助容器Ubuntu 镜像、挂载/var/log/nginx来执行冻结/解冻操作。如果要对一个已运行的 Pod 原地添加注解可参考 backup-hooks.md 中的命令注意新版注解域名kubectl 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方式二在 Backup spec 中指定 Hooks对于更精细的控制如按 namespace / resource / label 筛选 hook 的生效范围应在 Backup 自定义资源对象的spec.hooks字段中声明。v0.8.0 的 Backup API 完整示例见 site/content/docs/v0.8.0/api-types/backup.md其中 hooks 部分的骨架如下apiVersion: ark.heptio.com/v1 kind: Backup metadata: name: a namespace: heptio-ark spec: # ... 其他备份参数includedNamespaces 等 hooks: # 适用于特定资源的 hooks 数组。可选。 resources: - # hook 名称会显示在备份日志中。 name: my-hook # 该 hook 生效的 namespace 数组。不指定则应用于所有 namespace。可选。 includedNamespaces: - * # 该 hook 不生效的 namespace 数组。可选。 excludedNamespaces: - some-namespace # 该 hook 生效的资源类型数组。当前仅支持 pods。可选。 includedResources: - pods # 该 hook 不生效的资源类型数组。可选。 excludedResources: [] # 只有匹配该 label selector 的对象才生效。可选。 labelSelector: matchLabels: app: ark component: server # 在自定义 actions 执行前运行的 hooks 数组。当前仅支持 exec 类型。 # 已弃用请改用 pre。 hooks: # 内容与下面的 pre 相同。 # 在自定义 actions 执行前运行的 hooks 数组。当前仅支持 exec 类型。 pre: - # hook 类型必须为 exec。 exec: # 执行命令的容器名。不指定则使用 Pod 中的第一个容器。可选。 container: my-container # 要执行的命令以数组形式给出。必填。 command: - /bin/uname - -a # 命令执行出错时的处理方式。合法值为 Fail 和 Continue默认 Fail。可选。 onError: Fail # 等待命令执行完成的最长时间。默认 30 秒。可选。 timeout: 10s # 在所有自定义 actions 及附加对象处理完毕后运行的 hooks 数组。当前仅支持 exec 类型。 post: # 内容与上面的 pre 相同。在 spec 中使用 shell 与环境变量由于 hook 命令默认不经过 shell若需要多条命令或读取容器环境变量需要显式包装 shell。例如要对名为mysql的 Pod 使用其MYSQL_ROOT_PASSWORD环境变量执行FLUSH TABLES WITH READ LOCK该写法来自 backup-hooks.md注意当前版本使用velero.io资源pre: - exec: container: mysql command: - /bin/sh - -c - mysql --password$MYSQL_ROOT_PASSWORD -e FLUSH TABLES WITH READ LOCK onError: Fail使用多条命令时可以把目标命令包进 shell用;、等连接例如pre.hook.backup.velero.io/command[/bin/bash, -c, echo hello hello.txt echo goodbye goodbye.txt]注意容器内必须存在你所引用的 shell 解释器。源码级解析Hooks 的数据模型与错误语义从 pkg/apis/velero/v1/backup_types.go 可以看到 hooks 在 Velero API 中的完整类型定义与上面 YAML 一一对应BackupHooks仅包含Resources []BackupResourceHookSpec一个字段即针对具体资源的 hooks 数组BackupResourceHookSpec承载筛选规则includedNamespaces、excludedNamespaces、includedResources、excludedResources、labelSelector以及两类执行序列PreHooks与PostHooksBackupResourceHook目前只封装Exec *ExecHook一种实现即通过 Kubernetes Pod Exec API 在容器内执行命令这一点与 v0.8.0 文档中当前仅支持 exec 类型的描述一致ExecHook字段Container默认第一个容器、Commandkubebuilder:validation:MinItems1即命令数组至少一项、OnError、Timeoutmetav1.Duration。HookErrorModeFail 与 Continue 的真实语义HookErrorMode是 hooks 错误处理的核心枚举源码注释给出了精确语义HookErrorModeContinuehook 出错可接受备份/恢复继续执行其余 hooks最终备份状态为PartiallyFailedHookErrorModeFailhook 出错是严重问题Velero 会停止执行后续 hooks备份状态同样为PartiallyFailed。可见Fail与Continue的区别在于是否继续执行后续 hooks而非整个备份是否失败——两者最终都表现为PartiallyFailed这与很多使用者的直觉不同。Hook 执行结果的统计在 pkg/backup/backup.go 中备份完成时 Velero 会将itemBackupper.hookTracker统计的HooksAttempted尝试执行的 hook 数与HooksFailed失败的 hook 数写入备份状态updated.Status.HookStatus.HooksAttempted, updated.Status.HookStatus.HooksFailed itemBackupper.hookTracker.Stat()相应地用户可通过velero backup describe backup name查看这两项统计若存在失败详细原因会出现在Errors部分HooksAttempted: 1 HooksFailed: 0验证与排障创建备份并观察按上面的注解或 spec 配置好 hooks 后创建备份velero backup create nginx-hook-test查看备份状态velero backup get nginx-hook-test确认备份未进入PartiallyFailed/Failed状态。检查 hook 执行日志velero backup logs nginx-hook-test | grep hookCommand用于确认 pre/post hook 是否被触发且正常退出在 v0.8.0 时代日志中可通过hookCommand关键字过滤当前版本已升级为通过velero backup describe查看 HooksAttempted/HooksFailed 统计。关注状态字段备份处于PartiallyFailed时优先在备份描述与日志的 Errors 段中定位具体是哪个 hook、哪条命令出错再依据onError语义决定是修复命令还是改为Continue放行。小结Backup Hooks 是 Velero 实现应用一致性备份的关键机制pre hook 在对象备份前执行post hook 在自定义 action 及其附加对象全部备份后执行二者搭配即可覆盖冻结—快照—解冻这类完整时序。声明方式上Pod 注解适合快速、单对象的钩子注入注意ark.heptio.com旧域名及其不带pre.前缀的弃用写法Backup spec 则提供按 namespace/resource/label 筛选的精细控制。理解Fail/Continue与PartiallyFailed状态的关系以及HooksAttempted/HooksFailed统计能帮助你更准确地解读备份结果并快速定位问题。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考