Velero 插件发布流程解析：从 PR 准备、语义化版本定版到镜像构建与 e2e 验证

Velero 插件发布流程解析：从 PR 准备、语义化版本定版到镜像构建与 e2e 验证

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

本文以 Velero 仓库中的插件发布操作手册 Releasing Velero plugins 为主体，完整还原由 Velero 核心维护者负责的官方插件（AWS、GCP、Azure、CSI 等）从 PR 准备、changelog 归档、打 tag 触发镜像构建，到 e2e 验证与 GitHub Release 的完整发布链路。读完本文，你可以掌握插件版本号的语义化版本（semver）决策原则、tag 触发的 CI 镜像构建机制，以及 e2e 测试中插件镜像版本的配置位置，能够独立完成一次官方插件的正式发布。

前置知识：Velero 插件只发布镜像，不发布二进制

Velero 由核心维护者维护的插件不携带任何二进制产物，只发布容器镜像，因此不需要像 Velero 主仓库那样调用 GoReleaser 脚本。容器镜像通过向插件仓库推送 git tag 触发的 CI 作业自动构建。

这一点与 Velero 主仓库的发布方式形成鲜明对比。主仓库需要构建 CLI 二进制，因此保留了完整的 GoReleaser 流程，见 hack/release-tools/goreleaser.sh：该脚本要求设置GITHUB_TOKEN、RELEASE_NOTES_FILE、REGISTRY等环境变量，先执行goreleaser check校验配置，再通过goreleaser release命令构建并（在PUBLISH=TRUE时）发布到 GitHub。而插件仓库完全没有二进制产物，发布动作被简化为"打 tag → CI 构建镜像 → 手动创建 Release"三步。

适用范围：Velero 核心团队负责的插件包括 受支持云提供商列表中的全部插件，唯独排除 vSphere 插件（vSphere 插件的发布流程独立维护）。

第一步：提交 PR 准备插件仓库

1. 更新 README 的兼容矩阵与安装说明

更新插件仓库的README.md，将兼容矩阵（compatibility matrix）和velero install --plugins安装说明中的版本号改为本次预期发布的版本号，并发起 PR。

这一步对最终用户至关重要：插件的 README 是用户判断"某版本插件对应哪个 Velero 版本"以及复制安装命令的唯一入口，版本号必须与实际 tag 保持一致。

2. 按语义化版本确定版本号

版本号的确定依据两点：

• 语义化版本（semver）：判断本次变更属于不兼容的 API 变更（major）、向后兼容的功能新增（minor）还是仅修复（patch）；
• 是否与 Velero 主仓库的接口耦合：如果插件使用了 Velero 新引入、修改或移除的方法或变量（即插件与 Velero 的pkg/plugin框架 API 发生联动变更），版本号的提升级别需要体现这一兼容性变化。

可以推断，这也解释了为什么插件版本与 Velero 版本在 e2e 测试中成对出现（如下一节的镜像矩阵所示）——插件镜像与特定 Velero 版本之间存在事实上的兼容约束。

3. 归集 changelog

将插件仓库中所有未发布的 changelog 片段（存放于unreleased/目录，每个文件以 PR 编号命名）合并为新的CHANGELOG-v<version>.md文件，删除unreleased/目录内容，并按需编辑整理新文件。

Velero 主仓库有一套对应的自动化工具可作参考：hack/release-tools/changelog.sh 会遍历changelogs/unreleased下的条目，按<PR号>-<用户名>的文件命名解析出 PR 编号与作者，生成形如* <变更描述> (#<PR>, @<作者>)的列表，提示维护者粘贴到对应 CHANGELOG 文件后执行git rm changelogs/unreleased/*。主仓库的成品格式可参考 changelogs/CHANGELOG-1.17.md，其结构为## v<版本>下依次列出 Download、Container Image（如velero/velero:v1.17.0）、Documentation、Upgrading 与 Highlights 章节——插件仓库的 changelog 归档思路与之相同，只是插件没有二进制下载链接，核心信息集中在镜像 tag 上。

第二步：打 tag 触发镜像构建

PR 合并后，按以下顺序操作（<upstream-name>可能是upstream或origin，取决于本地仓库配置）：

# 1. 检出上游 main 分支 git checkout <upstream-name>/main # 2. 打版本 tag git tag v<version> # 3. 推送 tag，触发镜像构建 git push --tags <upstream-name>

推送 tag 后，插件仓库的 GitHub Actions 工作流会被触发并自动构建容器镜像。构建进度可在插件仓库自身的 Actions 页面查看。

构建完成后需要做两项验证：

1. 镜像可用性：确认新 tag 的镜像已出现在 Docker Hub 的velero/<plugin-name>仓库中；
2. 功能正确性：使用新镜像运行 Velero 的 e2e 测试。

深入 e2e 验证：插件版本在哪里配置

操作手册特别指出："在插件版本被做成可配置之前，你必须在测试中手动编辑插件版本。"这句提示直接对应本仓库 e2e 框架中的一处硬编码实现。

在 test/util/velero/velero_utils.go 中，ImagesMatrix是一个以 Velero 版本为一级键、以云厂商（aws、azure、gcp、vsphere、csi、datamover）为二级键的镜像映射表，明确固化了各版本 Velero 所搭配的各插件镜像 tag，例如：

var ImagesMatrix = map[string]map[string][]string{ "v1.16": { "aws": {"velero/velero-plugin-for-aws:v1.12.2"}, "azure": {"velero/velero-plugin-for-microsoft-azure:v1.12.2"}, "gcp": {"velero/velero-plugin-for-gcp:v1.12.2"}, "datamover": {"velero/velero-plugin-for-aws:v1.12.2"}, "velero": {"velero/velero:v1.16.2"}, ... }, "main": { "aws": {"velero/velero-plugin-for-aws:main"}, "gcp": {"velero/velero-plugin-for-gcp:main"}, ... }, }

发布新插件版本时的操作含义是：如果要针对某个已发布 Velero 版本验证新插件镜像，就需要把ImagesMatrix中对应厂商条目的插件 tag 改为新发布的版本（如velero/velero-plugin-for-aws:v1.12.2改为新版本），这正是"手动编辑测试中插件版本"的出处。main条目则指向各插件仓库的main分支构建镜像，用于日常主干联动测试。

e2e 测试的完整执行方式参见 test/e2e/README.md。以 kind 集群 + AWS（或 MinIO）存储为例，基本命令为：

BSL_PREFIX=<PREFIX_UNDER_BUCKET> \ BSL_BUCKET=<BUCKET_FOR_E2E_TEST_BACKUP> \ CREDS_FILE=/path/to/aws-creds \ CLOUD_PROVIDER=kind \ OBJECT_STORE_PROVIDER=aws \ PLUGINS=velero/velero-plugin-for-aws:<新插件版本> \ make test-e2e

其中PLUGINS变量对应-plugins命令行参数，用于显式指定被测插件镜像——发布验证场景下可借此绕过ImagesMatrix的硬编码矩阵直接注入新镜像；BSL_CONFIG（如BSL_CONFIG="region=us-east-1"）用于传递 BackupStorageLocation 配置，README 的故障排查章节也提到，若 Velero 日志出现Failed to get bucket region错误，即为缺少region配置所致。

此外需注意 e2e 测试的几项限制：同一轮执行只支持单一云厂商凭据（即一次只能测一个厂商的插件）；迁移类场景需要双集群。这些限制意味着多厂商插件虽然可以共用同一套流程，但需要分别安排 e2e 执行。

第三步：创建正式发布

当全部 e2e 测试通过后，到插件仓库的 GitHub Releases 页面，为新 tag手动创建 Release（插件发布没有自动化 Release 步骤，这一步由人完成），并将新 changelog 文件的内容完整粘贴进 Release 的描述字段，作为面向用户的版本说明。

全流程速查

阶段	动作	关键产物/验证点
PR 准备	更新 README 兼容矩阵与velero install说明；按 semver + Velero 接口变更情况定版；unreleased/changelog 合并为CHANGELOG-v<version>.md并清空unreleased/	一个合并后的 PR
打 tag	git checkout <upstream>/main→git tag v<version>→git push --tags <upstream>	CI 作业自动构建镜像
镜像验证	检查 CI Actions 进度；确认 Docker Hubvelero/<plugin-name>中出现新 tag 镜像	镜像可拉取
e2e 验证	将 test/util/velero/velero_utils.go 中ImagesMatrix的插件 tag 改为新版本，按 test/e2e/README.md 的make test-e2e流程执行	全量 e2e 通过
发布	在插件仓库 Releases 页面手动创建 Release，粘贴新 changelog 内容作为描述	公开可用的版本 Release

要点回顾

• Velero 官方插件只发布容器镜像，发布链路为"PR 准备 → 打 tag 触发 CI 构建 → e2e 验证 → 手动创建 Release"，不经过 GoReleaser；
• 版本号决策同时受 semver 变更级别和与 Velero 主仓库pkg/plugin接口联动情况双重约束；
• e2e 验证前必须处理 test/util/velero/velero_utils.go 中ImagesMatrix的插件版本硬编码（或改用PLUGINS变量注入镜像）；
• 该流程适用于受支持列表中除 vSphere 插件外的全部 Velero 核心团队插件。

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero