Velero 开发指南生成文件、单元测试与依赖管理实战【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/veleroVeleroVMware Tanzu Velero是 Kubernetes 生态中用于备份、恢复与迁移集群应用及持久化卷的开源工具其仓库同时托管着 CLI、server、插件 gRPC 接口与 CRD 定义等多类代码资产。本文基于 site/content/docs/v1.1.0/development.md 展开系统梳理 Velero 开发工作流中生成文件Generated Files— 单元测试 — 依赖管理三条核心主线何时必须重新生成代码、如何一键更新、如何用make verify校验产物一致性、如何跑通make test以及如何正确增删改第三方依赖。读完本文你将能快速上手 Velero 的本地开发闭环并在提交 PR 前准确执行仓库约定的检查流程。一、为什么 Velero 需要生成文件Velero 是一个典型的 Kubernetes Go 项目大量代码不是手写的而是由工具从单一事实来源source of truth自动生成clientset / listers / shared informers由 Kubernetes 代码生成器code-generator根据pkg/apis/velero/v1、pkg/apis/velero/v2alpha1等 API 类型定义生成是访问 Velero 自定义资源Backup、Restore、Schedule、BackupStorageLocation 等的类型安全客户端文档CLI 命令帮助与站点文档中的一部分内容由源码生成Protobuf / gRPC 类型插件系统pkg/plugin/proto下的BackupItemAction.proto、RestoreItemAction.proto、ObjectStore.proto、VolumeSnapshotter.proto、PluginLister.proto、Shared.proto等的消息与服务定义通过 protoc 编译为pkg/plugin/generated下的 Go 代码。因此改动这些事实来源后必须同步重新生成产物否则客户端、文档与 gRPC 代码会与实际类型定义脱节。开发文档在 site/content/docs/v1.1.0/development.md 中明确给出了需要触发重新生成的三种情形。二、何时需要运行make update按开发文档约定当你做出以下任意一类改动后必须运行make update重新生成文件改动类型示例新增 / 修改 / 删除命令行 flag 及其帮助文本为velero backup create增加一个新参数新增 / 修改 / 删除命令或子命令新增一个子命令或调整cmd/cli下的命令结构新增 API 类型在pkg/apis/velero/v1或v2alpha1中新增自定义资源类型及字段make update内部到底做了什么从仓库根目录 Makefile 看update目标实际是在构建容器内执行 hack/update-all.shupdate: ## Run all update scripts $(MAKE) shell CMD-c hack/update-all.sh而 hack/update-all.sh 会依次执行hack/下所有update-*.sh脚本当前仓库包含hack/update-1fmt.sh对所有 Go 文件执行gofmt -s并用goimports -local github.com/vmware-tanzu/velero统一 import 分组hack/update-2proto.sh调用 protoc将pkg/plugin/proto下的.proto定义编译到pkg/plugin/generated含--go_out与--go-grpc_out两路输出hack/update-3generated-crd-code.sh使用controller-gen生成 v1、v2alpha1 两套 CRD 到config/crd/v1/bases、config/crd/v2alpha1/bases并生成 RBACrbac:roleNamevelero-permshack/update-4generated-issue-template.sh编译 hack/issue-template-gen/main.go 并生成 GitHub issue 模板。其中 proto 脚本对工具链版本有明确要求需要 protocProtocol Buffers 编译器以及protoc-gen-go插件 v1.0.0。开发文档特别强调只有当你新增 / 修改 / 删除 protobuf 消息或服务定义时才需要走这条独立的 generate-proto.sh 流程该脚本已被封装进update-*.sh链路。实用提示仓库还提供了make update-crd快捷目标仅执行 hack/update-3generated-crd-code.sh用于只改 CRD 时快速迭代见 Makefile 中注释for development purpose only。与当前源码结构的印证从当前仓库结构看生成产物的输入与输出清晰对应输入API 类型定义位于 pkg/apis/velerov1/、v2alpha1/、shared/插件 proto 定义位于 pkg/plugin/proto输出CRD 清单位于 config/crdv1/、v2alpha1/下的bases生成代码位于 pkg/plugin/generated 等目录。这些生成目录在 hack/update-1fmt.sh 中被显式排除-not -path */generated/* -not -name zz_generated* -not -path */mocks/*说明格式化脚本只处理手写代码生成代码保持工具输出原样进一步印证了生成物不得手改的工程约定。三、用make verify校验生成产物是否最新如果担心本地改动后忘记重新生成或者想检查一份补丁里生成文件是否与源码一致开发文档给出的答案是make verifymake verify在构建容器内执行 hack/verify-all.sh该脚本会运行hack/下所有verify-*.sh当前仓库的核心校验包括hack/verify-fmt.sh以--verify模式调用update-1fmt.sh即gofmt -d与goimports -d做差异比对而非写入对应的 CRD 一致性校验通过重新生成后与仓库中现有产物 diff确保 clientset、listers、shared informers、CRD 与文档全部处于最新状态。一旦校验失败脚本会提示Please run make update参见 hack/update-1fmt.sh 中的失败分支。这也是 Velero CI 的守门环节之一——Makefile 中的ci目标依次执行verify-modules、verify、all、test将生成物一致性检查放在测试之前。四、运行单元测试make test开发文档给出的测试命令极其简洁make test但背后是一条完整、可复现的测试链路。从 Makefile 看test: build-dirs ## Run unit tests ifneq ($(SKIP_TESTS), 1) $(MAKE) shell CMD-c hack/test.sh $(WHAT) endif其中make shell会以当前用户身份-u $$(id -u):$$(id -g)在 Velero 构建镜像中挂载仓库目录运行隔离了宿主机 Go 工具链差异$(WHAT)变量可传参限定测试范围。实际执行 hack/test.sh 时设置CGO_ENABLED0保证静态编译、测试环境纯净默认收集./pkg/...、./internal/...与./cmd/...下所有包并排除pkg/builder、pkg/apis、pkg/test、pkg/generated、pkg/plugin/generated、mocks、internal/restartabletest等纯辅助/生成目录执行go test -vetatomic,bool,buildtags,directive,errorsas,ifaceassert,nilfunc,stringintconv,tests -installsuffix static -short -timeout 1200s -coverprofilecoverage.out即短模式测试 1200 秒超时 覆盖率输出到coverage.out。脚本注释中还记录了一个有价值的工程细节升级 controller-runtime 后在容器内以非 root 用户跑 envtest 会因/目录不可写而 panic因此通过XDG_CACHE_HOME/tmp/规避缓存目录权限问题。这解释了为什么测试必须通过构建镜像执行而不是直接go test ./...。本地测试变体make test WHAT./pkg/controller/...把WHAT传给hack/test.sh仅测试指定包例如只跑 backup controller 相关测试make test-local不经容器、直接在宿主机调用hack/test.sh $(WHAT)适合已配置好 Go 环境的机器make lint/make local-lint执行 hack/lint.sh与测试互补。仓库中每个核心包都配有同名_test.go例如 pkg/controller/backup_controller_test.go、pkg/backup/backup_test.go、pkg/restore 下的测试文件覆盖了 Backup/Restore 状态机、item 收集与插件调用等核心逻辑可作为理解什么行为算被测试覆盖的参考样例。五、Vendor 依赖管理开发文档将依赖管理单列一节指向 v1.1.0 时代的配套文档 vendoring-dependencies.md。该文档说明当时 Velero 使用depgolang/dep管理 vendor 依赖新增依赖运行dep ensure可加-v查看详细输出更新既有依赖运行dep ensure -update pkg [pkg ...]可同时更新一个或多个包。需要说明的是这是 v1.1.0 文档所对应的历史事实。从当前仓库根目录 go.mod 与 go.sum 的存在可以推断项目后续已迁移到 Go Modules 体系现在由make modules即go mod tidy整理依赖Makefile 中的verify-modules目标会校验go.mod、go.sum是否有未提交的变更。因此在当前版本上开发时应优先使用 Go Modules 工作流历史文档中的dep命令仅作版本演进参考。六、一条完整的本地开发闭环综合开发文档与 Makefile一次典型的 Velero 本地开发与提交流程如下# 1. 修改代码API 类型 / CLI flag / 命令 / proto 定义 # 2. 重新生成所有派生文件 make update # 3. 校验生成产物、格式与依赖是否一致 make verify make verify-modules # 4. 运行单元测试 make test # 5. 可选在构建容器内执行完整 CI 检查 make ci这套流程与make civerify-modules verify all test的顺序一一对应保证提交前所有自动生成的文件、格式、依赖与测试均处于绿色状态。对只改了 CRD 的快速迭代可先用make update-crd缩小范围对只需本地快速验证格式的场景可用make local-lint跳过容器。七、结语Velero 的development.md用四段话定义了生成、校验、测试与依赖四条开发纪律make update负责把 API/CLI/proto 的改动同步到生成代码make verify负责守门make test提供可复现的单元测试环境依赖管理则由dep演进为 Go Modules。理解这四条纪律背后的脚本链路hack/update-all.sh、hack/verify-all.sh、hack/test.sh就等于掌握了 Velero 仓库协作的隐性约定无论是提交新功能还是修复 Bug都能以最小摩擦通过 CI 检查。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Velero 开发指南：生成文件、单元测试与依赖管理实战
Velero 开发指南生成文件、单元测试与依赖管理实战【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/veleroVeleroVMware Tanzu Velero是 Kubernetes 生态中用于备份、恢复与迁移集群应用及持久化卷的开源工具其仓库同时托管着 CLI、server、插件 gRPC 接口与 CRD 定义等多类代码资产。本文基于 site/content/docs/v1.1.0/development.md 展开系统梳理 Velero 开发工作流中生成文件Generated Files— 单元测试 — 依赖管理三条核心主线何时必须重新生成代码、如何一键更新、如何用make verify校验产物一致性、如何跑通make test以及如何正确增删改第三方依赖。读完本文你将能快速上手 Velero 的本地开发闭环并在提交 PR 前准确执行仓库约定的检查流程。一、为什么 Velero 需要生成文件Velero 是一个典型的 Kubernetes Go 项目大量代码不是手写的而是由工具从单一事实来源source of truth自动生成clientset / listers / shared informers由 Kubernetes 代码生成器code-generator根据pkg/apis/velero/v1、pkg/apis/velero/v2alpha1等 API 类型定义生成是访问 Velero 自定义资源Backup、Restore、Schedule、BackupStorageLocation 等的类型安全客户端文档CLI 命令帮助与站点文档中的一部分内容由源码生成Protobuf / gRPC 类型插件系统pkg/plugin/proto下的BackupItemAction.proto、RestoreItemAction.proto、ObjectStore.proto、VolumeSnapshotter.proto、PluginLister.proto、Shared.proto等的消息与服务定义通过 protoc 编译为pkg/plugin/generated下的 Go 代码。因此改动这些事实来源后必须同步重新生成产物否则客户端、文档与 gRPC 代码会与实际类型定义脱节。开发文档在 site/content/docs/v1.1.0/development.md 中明确给出了需要触发重新生成的三种情形。二、何时需要运行make update按开发文档约定当你做出以下任意一类改动后必须运行make update重新生成文件改动类型示例新增 / 修改 / 删除命令行 flag 及其帮助文本为velero backup create增加一个新参数新增 / 修改 / 删除命令或子命令新增一个子命令或调整cmd/cli下的命令结构新增 API 类型在pkg/apis/velero/v1或v2alpha1中新增自定义资源类型及字段make update内部到底做了什么从仓库根目录 Makefile 看update目标实际是在构建容器内执行 hack/update-all.shupdate: ## Run all update scripts $(MAKE) shell CMD-c hack/update-all.sh而 hack/update-all.sh 会依次执行hack/下所有update-*.sh脚本当前仓库包含hack/update-1fmt.sh对所有 Go 文件执行gofmt -s并用goimports -local github.com/vmware-tanzu/velero统一 import 分组hack/update-2proto.sh调用 protoc将pkg/plugin/proto下的.proto定义编译到pkg/plugin/generated含--go_out与--go-grpc_out两路输出hack/update-3generated-crd-code.sh使用controller-gen生成 v1、v2alpha1 两套 CRD 到config/crd/v1/bases、config/crd/v2alpha1/bases并生成 RBACrbac:roleNamevelero-permshack/update-4generated-issue-template.sh编译 hack/issue-template-gen/main.go 并生成 GitHub issue 模板。其中 proto 脚本对工具链版本有明确要求需要 protocProtocol Buffers 编译器以及protoc-gen-go插件 v1.0.0。开发文档特别强调只有当你新增 / 修改 / 删除 protobuf 消息或服务定义时才需要走这条独立的 generate-proto.sh 流程该脚本已被封装进update-*.sh链路。实用提示仓库还提供了make update-crd快捷目标仅执行 hack/update-3generated-crd-code.sh用于只改 CRD 时快速迭代见 Makefile 中注释for development purpose only。与当前源码结构的印证从当前仓库结构看生成产物的输入与输出清晰对应输入API 类型定义位于 pkg/apis/velerov1/、v2alpha1/、shared/插件 proto 定义位于 pkg/plugin/proto输出CRD 清单位于 config/crdv1/、v2alpha1/下的bases生成代码位于 pkg/plugin/generated 等目录。这些生成目录在 hack/update-1fmt.sh 中被显式排除-not -path */generated/* -not -name zz_generated* -not -path */mocks/*说明格式化脚本只处理手写代码生成代码保持工具输出原样进一步印证了生成物不得手改的工程约定。三、用make verify校验生成产物是否最新如果担心本地改动后忘记重新生成或者想检查一份补丁里生成文件是否与源码一致开发文档给出的答案是make verifymake verify在构建容器内执行 hack/verify-all.sh该脚本会运行hack/下所有verify-*.sh当前仓库的核心校验包括hack/verify-fmt.sh以--verify模式调用update-1fmt.sh即gofmt -d与goimports -d做差异比对而非写入对应的 CRD 一致性校验通过重新生成后与仓库中现有产物 diff确保 clientset、listers、shared informers、CRD 与文档全部处于最新状态。一旦校验失败脚本会提示Please run make update参见 hack/update-1fmt.sh 中的失败分支。这也是 Velero CI 的守门环节之一——Makefile 中的ci目标依次执行verify-modules、verify、all、test将生成物一致性检查放在测试之前。四、运行单元测试make test开发文档给出的测试命令极其简洁make test但背后是一条完整、可复现的测试链路。从 Makefile 看test: build-dirs ## Run unit tests ifneq ($(SKIP_TESTS), 1) $(MAKE) shell CMD-c hack/test.sh $(WHAT) endif其中make shell会以当前用户身份-u $$(id -u):$$(id -g)在 Velero 构建镜像中挂载仓库目录运行隔离了宿主机 Go 工具链差异$(WHAT)变量可传参限定测试范围。实际执行 hack/test.sh 时设置CGO_ENABLED0保证静态编译、测试环境纯净默认收集./pkg/...、./internal/...与./cmd/...下所有包并排除pkg/builder、pkg/apis、pkg/test、pkg/generated、pkg/plugin/generated、mocks、internal/restartabletest等纯辅助/生成目录执行go test -vetatomic,bool,buildtags,directive,errorsas,ifaceassert,nilfunc,stringintconv,tests -installsuffix static -short -timeout 1200s -coverprofilecoverage.out即短模式测试 1200 秒超时 覆盖率输出到coverage.out。脚本注释中还记录了一个有价值的工程细节升级 controller-runtime 后在容器内以非 root 用户跑 envtest 会因/目录不可写而 panic因此通过XDG_CACHE_HOME/tmp/规避缓存目录权限问题。这解释了为什么测试必须通过构建镜像执行而不是直接go test ./...。本地测试变体make test WHAT./pkg/controller/...把WHAT传给hack/test.sh仅测试指定包例如只跑 backup controller 相关测试make test-local不经容器、直接在宿主机调用hack/test.sh $(WHAT)适合已配置好 Go 环境的机器make lint/make local-lint执行 hack/lint.sh与测试互补。仓库中每个核心包都配有同名_test.go例如 pkg/controller/backup_controller_test.go、pkg/backup/backup_test.go、pkg/restore 下的测试文件覆盖了 Backup/Restore 状态机、item 收集与插件调用等核心逻辑可作为理解什么行为算被测试覆盖的参考样例。五、Vendor 依赖管理开发文档将依赖管理单列一节指向 v1.1.0 时代的配套文档 vendoring-dependencies.md。该文档说明当时 Velero 使用depgolang/dep管理 vendor 依赖新增依赖运行dep ensure可加-v查看详细输出更新既有依赖运行dep ensure -update pkg [pkg ...]可同时更新一个或多个包。需要说明的是这是 v1.1.0 文档所对应的历史事实。从当前仓库根目录 go.mod 与 go.sum 的存在可以推断项目后续已迁移到 Go Modules 体系现在由make modules即go mod tidy整理依赖Makefile 中的verify-modules目标会校验go.mod、go.sum是否有未提交的变更。因此在当前版本上开发时应优先使用 Go Modules 工作流历史文档中的dep命令仅作版本演进参考。六、一条完整的本地开发闭环综合开发文档与 Makefile一次典型的 Velero 本地开发与提交流程如下# 1. 修改代码API 类型 / CLI flag / 命令 / proto 定义 # 2. 重新生成所有派生文件 make update # 3. 校验生成产物、格式与依赖是否一致 make verify make verify-modules # 4. 运行单元测试 make test # 5. 可选在构建容器内执行完整 CI 检查 make ci这套流程与make civerify-modules verify all test的顺序一一对应保证提交前所有自动生成的文件、格式、依赖与测试均处于绿色状态。对只改了 CRD 的快速迭代可先用make update-crd缩小范围对只需本地快速验证格式的场景可用make local-lint跳过容器。七、结语Velero 的development.md用四段话定义了生成、校验、测试与依赖四条开发纪律make update负责把 API/CLI/proto 的改动同步到生成代码make verify负责守门make test提供可复现的单元测试环境依赖管理则由dep演进为 Go Modules。理解这四条纪律背后的脚本链路hack/update-all.sh、hack/verify-all.sh、hack/test.sh就等于掌握了 Velero 仓库协作的隐性约定无论是提交新功能还是修复 Bug都能以最小摩擦通过 CI 检查。【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考