Velero 发布流程完整实战指南版本打标签、Changelog 与文档站点生成及多渠道发布【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero本文基于 Velero 仓库内的 发布说明文档 及其配套脚本完整讲解一次 Velero 版本从 RC 候选到 GA 发布的标准流程版本字符串如何被脚本校验、release 分支与 git tag 如何由 tag-release.sh 自动化处理、changelog 与版本化文档站点如何通过 Makefile 目标生成以及发布后 Homebrew、Helm Chart、插件与博客公告的配套动作。读完后你可以独立执行一次完整的 Velero 发布并理解每个环节背后脚本的校验逻辑与失败原因。发布模型与版本号规范Velero 采用“火车离站”train leaves the station发布模型在预定时间点生成发布候选版本RC期间若测试发现缺陷会生成多个 RC测试全部通过后才会生成正式发布构建。版本分为三类GA 发布仅指 major 与 minor 版本例如 1.0major、1.5minor预发布Pre-releaseGA 之前的所有版本例如1.4.0-beta.1、1.5.0-rc.1RC 发布Release Candidate包含计划随 GA 交付的全部内容本质上仍属于预发布。版本号格式并非随意约定发布脚本会强制校验。chk_version.go 中定义了唯一的合法版本正则var releaseRegex regexp.MustCompile(^v(?Pmajor[[:digit:]])\.(?Pminor[[:digit:]])\.(?Ppatch[[:digit:]])(-{1}(?Pprerelease(alpha|beta|rc)\.[[:digit:]]))*)该正则有四个具名捕获组major/minor/patch/prerelease同时匹配 GA 格式如v1.4.3和预发布格式如v1.2.4-beta.2、v1.5.0-rc.1。脚本以--verify模式运行时只做合法性校验不带该参数时会把解析结果以 bash 变量形式输出VELERO_MAJOR...、VELERO_MINOR...等供上层脚本eval使用。之所以用一个小 Go 程序而不是 bash 完成这件事注释中说明得直白版本号规则在 bash 里既难写也难验证正确性见 chk_version.go 第 34 行 的注释。RC 候选标准进入 RC 的提交必须满足无未解决的重大 bug单元测试通过针对最新 Kubernetes 版本在 AWS、vSphere 和 kind 上的 E2E 测试通过。RC 一旦确定即进入代码冻结code freeze此后只允许合入“发布所必需”的变更。GA 发布标准一个 RC 要成为正式发布必须满足单元测试通过E2E 测试在 Azure、vSphere、Kind、AWS、GCP 上针对“最新受支持 K8S 版本”与“最早受支持 K8S 版本”均通过手工测试通过文档同时注明手工测试会逐步转化为自动化测试。上述任何环节发现的 bug 会被评估是否为 release blocker若是则修复后重新生成一个 RC测试周期从头开始。发布前的准备工作发布博客仅 GA每个 major/minor 版本发布时应撰写并公布一篇博客说明新特性。具体写作要求见本文最后“撰写与发布博客”一节。Changelog 与文档 PR这是发布前工作量最大的一步产出物是一个同时包含 changelog 和版本化文档的 PR且必须先于打 tag 合入否则 release tag 不包含 changelog 内容。常见问题运行make serve-docs时若报You dont have enough free space in /var/cache/apt/archives/执行docker system prune清理 Docker 缓存空间即可。操作步骤如下创建版本 changelog 文件若changelogs/CHANGELOG-major.minor.md尚不存在在分支上复制最近一个版本的 changelog 文件来创建它。填充本版本变更列表运行make changelog生成所有未发布变更的列表把输出粘贴到CHANGELOG-major.minor.md的 “All Changes” 区域可对格式做人工调整如为某些条目补代码块更新文件顶部链接使其指向新版本。make changelog对应 Makefile 中的 changelog 目标底层执行 changelog.sh。该脚本的逻辑是遍历changelogs/unreleased/目录下的所有条目每条条目是PR号-用户名命名的纯文本文件例如 10000-shubham-pampattiwar内容为一行变更描述脚本将其格式化为* 描述 (#PR, 用户)并输出。脚本末尾还会提醒执行者git rm changelogs/unreleased/*清空目录——注意 GA 发布才需要清空见第 5 步。更新主 CHANGELOG.md“Current release” 区只保留当前 GA 版本“Development release” 区只保留最新的预发布版本更早的预发布版本移入 “Older releases”。仅 GA清空changelogs/unreleased/目录下的所有 changelog 文件。生成版本化文档运行make gen-docs并传入相应变量预发布VELERO_VERSIONv1.5.0-rc.1 NEW_DOCS_VERSIONv1.5.0-rc.1 make gen-docsGAVELERO_VERSIONv1.5.0 NEW_DOCS_VERSIONv1.5 make gen-docs两个变量容易混淆区别在于VELERO_VERSION可以是同一 major.minor 下的任意小版本v1.5.0、v1.5.1…而NEW_DOCS_VERSION在文档不需要更新时可以沿用同一值始终为v1.5。PREVIOUS_DOCS_VERSIONdoc-version-to-copy-from可选未设置时默认为最新的文档版本。对应 gen-docs.sh其完整流程为六步把最近一次打 tag 的文档目录复制为新版本目录作为 diff 基线git add已复制的旧版内容使后续git diff能直观展示自上个版本以来的文档变化用main分支文档site/content/docs/main覆盖新目录内容并将其中版本相关链接如指向特定分支的源码链接替换为VELERO_VERSION复制上一版本的 ToC 文件site/data/docs/version-toc.yml并git add用main的 ToC 覆盖新版本 ToC更新 site/config.yaml 的latest字段与版本列表并在 site/data/docs/toc-mapping.yml 中追加新版本: 新版本-toc映射见 gen-docs.sh 第 100-134 行 中按 macOS/Linux 分别处理 sed 语法的实现。 脚本执行前会检查目标文档目录是否已存在已存在则直接报错退出gen-docs.sh 第 57-61 行。清理同一大版本下旧的预发布文档如果存在。例如已有site/content/docs/v1.5.0-beta.1而你要发布v1.5.0-rc.1或v1.5需要删除预发布文档目录site/content/docs/pre-release-version删除其目录清单文件site/data/docs/pre-release-version-toc.yml从site/data/docs/toc-mapping.yml中移除该预发布版本的映射条目从site/config.yaml中移除所有对该预发布文档的引用。创建或更新 “Upgrade to $major.minor” 页面若不存在则新建可参照 v1.11 的升级指南若已存在则把其中旧版本字符串全部替换为新版本。注意这一步要在版本化目录和main目录两处都做。Review 并提交 PR按 site/README-HUGO.md 中“Adding a New Docs Version”一节的补充说明完成文档生成收尾其中提到预发布版本需要把site/config.yaml中latest字段的改动回退避免预发布文档成为站点默认版本人工 review diff或运行make serve-docs本地起站Makefile 中该目标会拉起 Hugo 容器并把 1313 端口映射到本地见 Makefile 第 496-502 行检查站点效果最后提交包含 changelog 与版本化文档的 PR。固定基础镜像Pin the base image为可复现性RC 打 tag 之前必须确认 release 分支上的 Dockerfile 中基础镜像以 digest 方式引用即imagesha256:...形式。发布文档中给出的示例指向 release-1.7 分支的 Dockerfile。作为对照当前main分支的 Dockerfile 使用的是 tag 引用如 Dockerfile 第 52 行 的FROM paketobuildpacks/ubuntu-noble-run-tiny:latest这正说明为什么发布前必须在 release 分支上完成 digest 固定——否则同一 tag 在不同时间构建可能得到不同的基础镜像破坏发布可复现性。执行 Velero 发布前提changelog 与文档 PR 已合入保证包含在 release tag 中。预发布与 GA 的操作流程完全一致。通用注意事项每个脚本开头的注释变量说明都要读理解各变量的用途与取值格式需要配置名为upstream的远端可用git remote -v检查发布脚本在未通过环境变量REMOTE指定时默认使用upstream。常见问题dry-run 出现随机错误时直接重试一次即可。步骤 1手动创建 release 分支在 GitHub 上手动创建形如release-$major.$minor的分支。步骤 2dry-run 模式打 tag此步骤不会向 GitHub 推送任何内容VELERO_VERSIONv1.9.0-rc.1 REMOTEupstream-remote GITHUB_TOKENREDACTED ON_RELEASE_BRANCHTRUE \ ./hack/release-tools/tag-release.sh步骤 3正式发布打 tag 并推送VELERO_VERSIONv1.9.0-rc.1 REMOTEupstream-remote GITHUB_TOKENREDACTED ON_RELEASE_BRANCHTRUE \ ./hack/release-tools/tag-release.sh publishtag-release.sh 的内部执行链tag-release.sh 的定位是“可执行文档”其执行链值得逐段理解出问题时才知道卡在哪一环环境校验VELERO_VERSION、GITHUB_TOKEN必须设置否则直接退出第 71-80 行工作区必须干净git status --short非空即报错退出第 83-86 行。版本解析与推断先go run chk_version.go --verify校验格式再解析出VELERO_PATCH与VELERO_PRERELEASE。若 patch 号非 0补丁版或无预发布后缀GA脚本自动设置ON_RELEASE_BRANCHTRUE并打印推断出的 release 分支名release-$MAJOR.$MINOR提示确认该分支已创建第 99-119 行。确认交互打印所有推断后要求按回车继续Ctrl-C可随时取消。分支切换先git fetch $remote --tags若涉及 release 分支脚本检查远端分支必须存在不存在则退出本地不存在则git checkout --track跟踪它已存在则 checkout 后git pull同步第 136-160 行不涉及 release 分支时非补丁的预发布直接在远端main上操作。打 tag 与推送tag_and_push函数先git tag仅当publish TRUE时才git push $remote tag第 53-61 行dry-run 不会推送。调用 goreleaser以RELEASE_NOTES_FILEchangelogs/CHANGELOG-$MAJOR.$MINOR.md PUBLISH$publish make release收尾第 163-166 行。dry-run 清理dry-run 完成后切回原分支并git tag -d删除本地 tag避免与正式运行冲突第 168-174 行。Makefile 的 release 目标 会在构建容器内执行 goreleaser.sh该脚本要求GITHUB_TOKEN、RELEASE_NOTES_FILE、REGISTRY三者齐备并根据git status --porcelain设置GIT_TREE_STATE。随后先goreleaser check校验配置格式PUBLISH不为TRUE时执行goreleaser release --snapshot生成未发布的快照构建跳过发布/通告/校验为TRUE时执行完整的goreleaser release以--release-notes注入 changelog 文件内容goreleaser.sh 第 44-63 行。步骤 4发布 GitHub Release打开 velero 仓库的 GitHub releases 页面编辑 goreleaser 生成的draft release补丁版本特别注意release body 会包含完整CHANGELOG-major.minor.md的内容需要删除前序版本如v1.9.0的 changelog只保留最新补丁版本的条目快速检查格式goreleaser 会自动识别预发布版本并在 GitHub release 页面勾选 “pre-release” 选项但仍值得二次确认确认 GitHub Actions 已构建并推送所有镜像耗时较长确认 Docker Hub 上镜像标签齐全确认 release 页面资产CLI 二进制等已生成点击发布。步骤 5冒烟测试此时 Docker 镜像应已发布做一次冒烟测试从 GitHub release 下载 CLI用它把 Velero 安装进一个集群或手动把现有部署更新到新镜像确认velero version输出符合预期执行一次备份/恢复确认流程正常。Homebrew 与 Chocolatey 更新仅 GA更新 Homebrew 公式的步骤若没有 token先创建一个 scope 包含gist和public_repo的 GitHub access token用于 Homebrew执行export HOMEBREW_GITHUB_API_TOKENyour_token_here使 brew 能以你的身份操作 GitHub运行hack/release-tools/brew-update.sh脚本会下载所需文件、执行检查并调用 brew 助手提交 PR完成后在浏览器中打开。从 brew-update.sh 可以看到它依赖外部注入的VELERO_VERSION与HOMEBREW_GITHUB_API_TOKEN两个环境变量先brew update确保拿到最新 velero formula再执行brew bump-formula-pr velero --url版本 tarball 地址第 16-22 行Windows 侧在 Windows 机器上按 velero-choco 项目 README 的说明创建 Velero CLI 的 Chocolatey 包并更新版本。插件发布由 Velero 团队维护的插件遵循 插件发布说明 执行。插件镜像构建完成后务必同步更新使用这些插件的 E2E 测试对应仓库中的 test/e2e 目录。Helm Chart 更新仅 GA按当前 Velero GA 版本更新 helm chart 仓库中crds目录下的 CRD并为 helm chart 的 CRD 添加相应 label提升Chart.yaml中 Chart 的version提升Chart.yaml的appVersion以及values.yaml中镜像的tag必要时提升values.yaml中的插件版本更新该 chart 仓库README.md中的升级说明与相关 tag。撰写与发布博客发布博客应包含感谢所有贡献者参与本次发布尽量点名致谢或特别关注新晋维护者突出本次发布的主题或重点方向如安全性、bug 修复、功能改进可参考历次 Velero 发布博客概述发布中引入的新特性或新工作流也可以包含项目层面的新举措例如行为准则更新如有必要为具体新特性另写多篇深入博客计划在主发布博客之后陆续公布不必一次性全部发出。博客 PR 要求准备包含发布博客的 PR。写作方法见 网站写作指南最省事的做法是复制最近一篇博客再替换内容同步更新site/index.html使 “Latest Release Information” 区域链接到这篇新博客博客计划与发布同日上线。发布公告发布完成后通过以下渠道告知社区仅 GA合入博客 PRVelero 的 Twitter 账号。鼓励维护者在各自社交媒体转发扩散社区 Slack 频道Google 群组消息。公告内容应包含感谢所有贡献者、本版本亮点简述、发布博客/发布说明/GitHub release 页面的链接。小结Velero 的一次发布由四条主线构成changelog 与文档 PRmake changelogmake gen-docs保证 tag 内含完整变更记录和版本化文档、release 分支上固定基础镜像 digest保证构建可复现、tag-release.sh的 dry-run 与 publish 两段式打 tag配合 goreleaser 产出 draft release 与构建产物、以及发布后的多渠道动作Homebrew/Chocolatey、Helm Chart、插件 E2E 同步、博客与公告。所有环节的校验逻辑版本正则、脏工作区检查、release 分支推断、dry-run 后删 tag都有明确的脚本实现与错误提示排障时直接对照 hack/release-tools/ 下对应脚本即可。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考