从源码构建 Velero（Ark）：环境准备、编译、测试与部署运行全指南-酒店常州论坛

从源码构建 Velero（Ark）：环境准备、编译、测试与部署运行全指南

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

本文以仓库中 Velero（历史版本曾命名为 Heptio Ark）的《Build from source》官方文档为骨架，系统讲解从源码获取、编译二进制、构建与推送容器镜像、生成文件再生成、单元测试，到本地模式与 Deployment 模式运行 Velero 的完整链路，并结合当前仓库源码给出底层实现佐证与演进差异说明。读完本文，你将掌握在任何平台上从零构建一个可用的 Velero 二进制与镜像，并将其部署到 Kubernetes 集群中的完整实操能力。

一、文档背景：从 Ark 到 Velero 的历史脉络

本文对应的原始文档是 Velero 前身 Heptio Ark 时代（约 v0.10.0 版本）的构建指南，存放于site/content/docs/v0.10.0/build-from-scratch.md。彼时项目名称为Ark，代码库地址为github.com/heptio/ark，镜像名为ark，命名空间为heptio-ark。

随着项目从 Heptio 移交至 VMware Tanzu 并正式更名为Velero，当前仓库中的一切标识均已随之演进：

维度	历史（Ark / v0.10.0）	当前仓库（Velero）
源码导入路径	`github.com/heptio/ark`	`github.com/vmware-tanzu/velero`（见 go.mod）
二进制名	`ark`	`velero`（Makefile 中`BIN ?= velero`）
镜像名	`$REGISTRY/ark:$VERSION`	`$(REGISTRY)/$(BIN)`（Makefile）
服务命名空间	`heptio-ark`	`velero`
官方文档目录	`site/content/docs/v0.10.0/`	`site/content/docs/main/build-from-source.md`

阅读本文时请注意：原始文档中关于项目名、仓库地址、命名空间的写法均为历史事实，实操时应以当前仓库对应的新名称替换。以下各节会同时给出历史命令与当前仓库的对应实现，便于按需对照。

二、前置条件（Prerequisites）

原文列出四项构建与运行 Velero 所需的基础条件：

可访问的 Kubernetes 集群，版本 1.7 或更高；若要执行ark backup delete（现为velero backup delete），则要求集群版本不低于 1.7.5；
集群内的 DNS 服务，保证集群内服务发现正常工作；
已安装kubectl，用于向集群下发 CRD、Deployment 等资源；
已安装 Go 开发环境，最低版本要求 1.8。

需要说明的是，上述 Kubernetes 与 Go 的最低版本要求是 v0.10.0 时代的约束。现代 Velero 版本对 Kubernetes 与 Go 版本的要求更高，具体以当前 site/content/docs/main/build-from-source.md 为准。

三、获取源码（Getting the source）

历史文档推荐通过go get获取源码，并建议将 Go 的 import path 加入PATH，以便后续直接执行编译产物：

mkdir $HOME/go export GOPATH=$HOME/go go get github.com/heptio/ark

对应的现代版本（当前文档 site/content/docs/main/build-from-source.md）为：

go get github.com/velero-io/velero

此外，也可以从 Release 页面下载名为Source code的源码归档，解压到 Go import path 下的src/github.com/velero-io/velero。需要留意的是：Makefile 目标假定在 git 仓库内构建（会读取git rev-parse HEAD与工作区状态），若从归档构建，只能使用下述go build类的命令，部分依赖 git 信息的 Makefile 目标将不可用。

四、构建（Build）

4.1 构建二进制

在当前仓库根目录执行：

make build

其默认构建linux-amd64平台（Makefile 中ARCH ?= linux-amd64）。产物输出至_output/bin/<GOOS>/<GOARCH>目录，例如 Linux 平台对应_output/bin/linux/amd64/velero。

从源码看，make build实际调用的是 hack/build.sh：该脚本会强制CGO_ENABLED=0进行静态编译，并通过-ldflags注入构建元信息：

LDFLAGS="-X ${PKG}/pkg/buildinfo.Version=${VERSION}" LDFLAGS="${LDFLAGS} -X ${PKG}/pkg/buildinfo.ImageRegistry=${REGISTRY}" LDFLAGS="${LDFLAGS} -X ${PKG}/pkg/buildinfo.GitSHA=${GIT_SHA}" LDFLAGS="${LDFLAGS} -X ${PKG}/pkg/buildinfo.GitTreeState=${GIT_TREE_STATE}"

这些信息会被 pkg/buildinfo/buildinfo.go 引用，最终呈现在velero version命令的输出中；同时velero install也会依据版本信息决定部署时使用的镜像 Tag。若需要覆盖部署镜像，可在安装时使用--image参数。

如果只想在本地快速构建本机平台的二进制（不进入构建容器），可执行：

go build ./cmd/velero # 或 make local

其中make local会以go env GOOS-GOARCH自动探测当前平台（Makefile）。CLI 入口位于 cmd/velero/velero.go，其主函数调用velero.NewCommand(baseName).Execute()完成命令行解析。

4.2 交叉编译（Cross compiling）

历史文档中，为其他平台构建的方法是make build-<GOOS>-<GOARCH>，例如为 macOS 构建：

make build-darwin-amd64

所有二进制统一放入_output/bin/<GOOS>/<GOARCH>，例如_output/bin/darwin/amd64/ark（现代为velero）。这一机制在当前 Makefile 中依然保留（build-%目标，见 Makefile）。

Makefile 还提供了一次性构建多平台的便利目标all-build。历史版本覆盖五个平台：

linux-amd64
linux-arm
linux-arm64
darwin-amd64
windows-amd64

现代版本通过CLI_PLATFORMS变量扩展了更多平台（Makefile）：

linux-amd64 linux-arm linux-arm64 darwin-amd64 darwin-arm64 windows-amd64 linux-ppc64le linux-s390x

4.3 构建并推送容器镜像

构建容器镜像需要先将$REGISTRY环境变量指向你自己的镜像仓库，这样集群中的任意节点都能拉取到本地构建的镜像。设置方式：

export REGISTRY=myregistry.example.com/team

然后在仓库根目录以 Tag$REGISTRY/ark:$VERSION构建镜像：

make container

推送镜像到仓库：

make push

对应现代版本，镜像名为$(REGISTRY)/velero，Tag 由$VERSION决定（默认main，见 Makefile）。原文同时提到用kubectl将自定义镜像注入已有 Deployment：

kubectl --namespace=heptio-ark set image deployment/ark ark=$REGISTRY/ark:$VERSION

现代对应命令为：

kubectl -n velero set image deploy/velero velero=myimagerepo/velero:$VERSION

现代构建方式的额外要求：Buildx

值得注意的演进点：现代 Makefile 的container目标依赖Docker Buildx。在 Makefile 中，如果CONTAINER_TOOL不是 docker，或BUILDX_ENABLED不为 true，目标会直接报错并提示先启用 buildx。构建本地镜像（与宿主机同架构）时可直接：

make container

若需构建多架构的混合镜像（hybrid image，例如同时支持linux/amd64与linux/arm64），则需先完成以下一次性准备：

# 1. 若需跨平台构建容器镜像，注册 QEMU 模拟器 docker run --rm --privileged multiarch/qemu-user-static --reset -p yes # 2. 创建并引导 buildx builder docker buildx create --use --name builder docker buildx inspect --bootstrap

之后将BUILDX_OUTPUT_TYPE设为registry构建并直接推送（混合镜像必须推送到 registry，因为本地无法承载全部平台的 manifest）：

REGISTRY=myrepo BUILDX_OUTPUT_TYPE=registry make container # linux/amd64 REGISTRY=myrepo BUILDX_OUTPUT_TYPE=registry BUILD_ARCH=amd64,arm64 make container # linux/amd64 + linux/arm64

镜像构建完成后，若希望 Kubernetes 重新拉取同名新镜像，可删除 Velero 相关 Pod 触发重建：

kubectl -n velero delete pods -l deploy=velero

4.4 更新生成文件（Update generated files）

以下文件由源码自动生成，不建议手工维护：

clientset（客户端集合）
Listers
Shared informers（共享 informer）
文档
Protobuf/gRPC 类型

当发生下列变更时，需要运行make update重新生成：

新增/修改/删除命令行 flag 或帮助文本
新增/修改/删除命令或子命令
新增 API 类型

从源码看，make update实际执行 hack/update-all.sh，该脚本会遍历执行hack/update-*.sh系列脚本，包括：

hack/update-1fmt.sh：代码格式化
hack/update-2proto.sh：Protobuf/gRPC 代码生成
hack/update-3generated-crd-code.sh：CRD 代码生成
hack/update-4generated-issue-template.sh：Issue 模板生成

其中 hack/update-2proto.sh 会调用protoc编译器，以pkg/plugin/proto/下的.proto文件为输入（pkg/plugin/proto 目录），输出到pkg/plugin/generated/。因此，当你增删改 Protobuf 消息或服务定义时，需要：

安装 Protocol Buffers v3 编译器（protoc）；
运行对应 proto 生成脚本完成再生成。

五、测试与校验（Test）

运行单元测试：

make test

执行生成文件一致性校验（确保 clientset、listers、shared informers、文档等生成产物与源码保持同步）：

make verify

当前仓库中，make test会通过构建容器执行 hack/test.sh，make verify对应执行 hack/verify-all.sh（见 Makefile）。除此之外，现代 Makefile 还提供了make lint（运行 hack/lint.sh）、make ci（依次执行 modules 校验、verify、all、test）等更完整的质量门禁（Makefile）。

六、运行（Run）

6.1 运行前置条件

无论以哪种方式运行，都需要为 Velero 准备以下权限与资源（这些内容通常都已封装在 examples 目录的清单文件中）：

集群内合适的 RBAC 权限：
- 对源集群与命名空间内全部数据的读权限；
- 对目标集群与命名空间的写权限；
云厂商凭据：
- 对卷（volume）的读写权限；
- 对对象存储中备份数据的读写权限；
一个BackupStorageLocation对象定义，供 Velero server 使用；
（可选）一个VolumeSnapshotLocation对象定义，用于对 PV 创建快照。

6.2 创建集群（以 AWS 为例）

原文给出了两个在 AWS 上快速搭建 Kubernetes 集群的途径：

使用 Amazon 官方的 CloudFormation 模板（EC2 Quick Start for Kubernetes）；
使用 eksctl，即 Amazon EKS 的官方 CLI。

6.3 方式一：在本地运行 Velero server

本地运行可以显著加速迭代开发——每次代码变更无需重新构建并重新部署 server 镜像，直接重启本地进程即可生效。

第一步：设置云厂商凭据环境变量

AWS：AWS_SHARED_CREDENTIALS_FILE（指向共享凭据文件）
GCP：GOOGLE_APPLICATION_CREDENTIALS
Azure 需要以下七个变量：
1. AZURE_CLIENT_ID
2. AZURE_CLIENT_SECRET
3. AZURE_SUBSCRIPTION_ID
4. AZURE_TENANT_ID
5. AZURE_STORAGE_ACCOUNT_ID
6. AZURE_STORAGE_KEY
7. AZURE_RESOURCE_GROUP

第二步：在集群中创建资源

可以使用 examples 目录提供的示例配置。以 AWS 现有集群为例，在仓库根目录执行：

编辑examples/aws/05-ark-backupstoragelocation.yaml，将其指向你的 S3 bucket 与 region（可用aws s3api list-buckets查看全部 bucket 名称）；
（可选）编辑examples/aws/06-ark-volumesnapshotlocation.yaml，指定 AWS region。

00-prereqs.yaml包含全部自定义资源定义（CRDs），用于对 backup、restore、schedule 等资源执行增删改查；同时还包含heptio-ark命名空间、arkServiceAccount，以及将arkServiceAccount 授予 cluster-admin 角色的 ClusterRoleBinding：

kubectl apply -f examples/common/00-prereqs.yaml

10-deployment.yaml是面向 AWS 的 Ark server 示例配置：

kubectl apply -f examples/aws/10-deployment.yaml

05-ark-backupstoragelocation.yaml用于指定备份存储位置，可单独应用，也可连同可选的06-ark-volumesnapshotlocation.yaml一起应用：

kubectl apply -f examples/aws/05-ark-backupstoragelocation.yaml

或

kubectl apply -f examples/aws/05-ark-backupstoragelocation.yaml examples/aws/06-ark-volumesnapshotlocation.yaml

第三步：启动 Ark server

确保ark已在PATH中，或使用完整路径调用；
按需设置以下变量（既可导出为环境变量，也可作为命令行 flag 传入）：
- --kubeconfig：指定 Ark server 与 Kubernetes apiserver 通信所用的 kubeconfig 文件路径；
- --namespace：Ark server 查找 backup、schedule、restore 资源所在的命名空间；
- --log-level：设置 Ark server 的日志级别；
- --plugin-dir：设置 Ark server 查找插件的目录；
- --metrics-address：设置 Prometheus 指标暴露的绑定地址与端口；
启动命令：ark server（现代版本对应velero server）。

6.4 方式二：以 Deployment 方式运行

使用 Deployment 安装 Ark：各云厂商的 Deployment 示例位于examples/<cloud-provider>/10-deployment.yaml；
将 Deployment 的默认镜像替换为本地构建的镜像：

kubectl --namespace=heptio-ark set image deployment/ark ark=$REGISTRY/ark:$VERSION

其中$REGISTRY与$VERSION即构建镜像时使用的取值。

6.5 关于 examples 目录的现状说明

需要说明的是：历史文档引用的examples/aws/、examples/common/等云厂商专属清单在当前仓库的 examples 目录中已不复存在，现存的示例为通用场景，包括：

examples/minio/00-minio-deployment.yaml：基于 MinIO 的对象存储部署（适合本地/离线验证）；
examples/nginx-app/base.yaml 与 examples/nginx-app/with-pv.yaml：带/不带 PV 的 nginx 应用示例，常用于备份恢复演练；
examples/default-resource-modifier-cni.yaml：默认资源修改器示例。

具体云厂商的安装清单可参考对应版本的官方安装文档与 Release 资源。

七、依赖 vendoring

若需新增或升级被 vendor 的第三方依赖，原文档指引读者参考《Vendoring dependencies》专文（历史路径为同目录下vendoring-dependencies.md，链接定义见原始文档 [11]）。这一机制在现代仓库中已演进为 Go Modules 管理：依赖锁定在 go.mod 与 go.sum 中，新增/更新依赖后执行go mod tidy，并通过make verify-modules校验模块文件与提交状态的一致性（Makefile）。

八、构建流程速查表

目标	历史命令（Ark）	现代命令（Velero）	说明
构建默认二进制（linux-amd64）	`make build`	`make build`	产物在`_output/bin/linux/amd64/`
交叉编译	`make build-darwin-amd64`	`make build-darwin-amd64`	平台格式`build-<GOOS>-<GOARCH>`
构建全部平台	`make all-build`	`make all-build`	平台列表见`CLI_PLATFORMS`
构建容器镜像	`make container`	`make container`	现代版本需启用 docker buildx
推送镜像	`make push`	`docker push`	现代默认输出类型为 docker
单元测试	`make test`	`make test`	在构建容器内执行
生成文件校验	`make verify`	`make verify`	执行`hack/verify-all.sh`
再生成文件	`make update`	`make update`	执行`hack/update-all.sh`
本地运行 server	`ark server`	`velero server`	支持`--kubeconfig`等 flag

结语

从 Ark 到 Velero，从go get到 Go Modules、从make push到 buildx 多架构构建，本文以 v0.10.0 时代的构建文档为主线，完整还原了「前置条件 → 获取源码 → 编译 → 测试 → 运行」的全流程，并逐一映射到当前仓库的 Makefile、hack 脚本体系与 cmd/velero/velero.go 入口实现。无论是想要快速迭代的本地开发模式，还是面向生产的多平台镜像交付，上述流程都构成了可复用的基线。更详细的现代构建说明可继续阅读 site/content/docs/main/build-from-source.md。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析