Velero 镜像标签策略全解：从 Ark 到 Velero 的 `＜SemVer＞`、`latest` 与 `main` 标签规范

Velero 镜像标签策略全解：从 Ark 到 Velero 的<SemVer>、latest与main标签规范

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

导读

本文基于仓库内 site/content/docs/v0.10.0/image-tagging.md 展开，系统讲解 Velero（早期名为 Ark）官方发布容器镜像时的标签命名约定：语义化版本号<SemVer>、跟随最新稳定版的latest、以及跟随开发主线的main。读完本文，你将掌握 Velero 镜像的三个标签类别及其适用场景，理解默认镜像名在源码中如何被构造、安装命令如何覆盖它，以及镜像拉取策略（PullAlways/PullIfNotPresent）随标签自动变化的底层逻辑，从而在生产与开发环境中正确选择镜像版本。

一、镜像标签策略概述：三类标签的定位

Velero 的镜像标签策略遵循一套简单而明确的规则，共覆盖三种场景：

这套策略的核心目标很清晰：让用户既能锁定某个确定版本用于生产，也能用latest跟随稳定演进，还能用main体验每日最新的开发成果。三类标签互不冲突，分别服务于生产部署、稳定跟随与开发测试三类人群。

二、历史沿革：从 Ark 到 Velero，镜像名与仓库的变迁

本文的关联文档 site/content/docs/v0.10.0/image-tagging.md 记录的是项目早期（v0.10.0 时代）的镜像策略。当时项目名称为Ark，镜像托管在 Google 的容器仓库上，文档中给出的镜像约定为：

gcr.io/heptio-images/ark:<SemVer> gcr.io/heptio-images/ark:latest gcr.io/heptio-images/ark:main

例如每个 git 标签都有对应镜像，如gcr.io/heptio-images/ark:v0.8.0。

此后项目更名为Velero，镜像同步迁移至 Docker Hub 的velero组织下。以仓库内最新的文档版本 site/content/docs/main/image-tagging.md 及 site/content/docs/v1.18/image-tagging.md 为准，当前约定为：

velero/velero:<SemVer> velero/velero:latest velero/velero:main

即正式版本的镜像形如velero/velero:v1.0.0。这一命名约定同样体现在各版本的发布说明中，例如 changelogs/CHANGELOG-1.18.md 开头即写明velero/velero:v1.18.0，changelogs/CHANGELOG-1.2.md 中也记录了velero/velero:v1.2.0。标签策略本身在三类标签的结构上保持了完全一致，变化的只是仓库地址与项目名。

三、<SemVer>：语义化版本标签，锁定确定性发布

3.1 语义化版本约定

发布版本的镜像使用语义化版本（Semantic Versioning）规范作为标签。版本号由主版本号.次版本号.修订号组成，例如v1.18.0。在 v0.10.0 时代，策略即规定github.com/heptio/ark仓库中的每个 git tag 都有与之匹配的镜像：

gcr.io/heptio-images/ark:<SemVer>

如今对应为：

velero/velero:<SemVer>

这意味着用户看到的 git 标签版本与可拉取的镜像版本是一一对应的，不会出现"仓库打好了标签、镜像却缺席"的情况，为依赖精确版本的回滚与排障提供了确定性保障。

3.2 为什么生产环境应优先使用 SemVer 标签

固定版本的镜像标签具有以下优势：

• 可复现：同一标签对应的镜像内容固定，多次部署行为一致；
• 可审计：可以明确追溯集群中运行的 Velero 到底是哪个版本，配合 pkg/buildinfo/buildinfo.go 中注入的版本信息排查问题；
• 可回滚：升级出现问题时，切回旧版本标签即可快速恢复。

3.3 多架构支持

从仓库发布历史看，镜像也注重多架构兼容：changelogs/CHANGELOG-1.3.md中明确说明"用户无需做任何改动，只需更新版本标签——v1.3 镜像是velero/velero:v1.3.0，Docker 会自动为主机拉取对应架构的镜像"。因此使用 SemVer 标签时，Docker 会按运行平台自动选择合适架构的镜像层。

四、latest：跟随最新稳定版的便捷标签

latest标签的定位是指向最近一次正式发布版本：

velero/velero:latest

在 Ark 时代对应gcr.io/heptio-images/ark:latest。

需要特别注意的是latest的语义边界：

• 它不是"随时变动的开发版"，而是始终跟随最近一次正式发布；
• 因此它比固定版本标签更"新鲜"，但不具备确定性——每次拉取得到的镜像版本可能随新版本发布而改变；
• 适用于测试环境、快速体验新功能的场景；对于生产环境，建议仍以显式的 SemVer 标签为准，避免新版本发布后集群在重建或扩容时无意间滚动到新版本。

五、main：开发主线镜像，紧跟每日提交

main标签服务于开发与预发布验证：

velero/velero:main

它的语义是跟随main分支上最新落地的提交。每有新的代码合入main分支，CI 构建出的镜像就会更新main标签，因此它反映的是尚未正式发布的最新代码状态。

main标签适合以下人群：

• 想要提前验证新特性的开发者；
• 需要针对最新代码复现问题的贡献者；
• 希望基于最新上游代码做集成测试的团队。

同时需要意识到它的风险：main分支的镜像可能包含未经完整发布验证的改动，不应直接用于生产环境。

六、源码级原理：默认镜像名如何被构造与使用

理解了标签语义后，再从源码层面看 Velero 是如何把镜像名落实到部署资源上的。

6.1 默认镜像名的构造

默认镜像名的核心实现在 internal/velero/images.go：

// Use Dockerhub as the default registry if the build process didn't supply a registry func imageRegistry() string { if buildinfo.ImageRegistry == "" { return "velero" } return buildinfo.ImageRegistry } // ImageTag returns the image tag that should be used by Velero images. // It uses the Version from the buildinfo or "latest" if the build process didn't supply a version. func ImageTag() string { if buildinfo.Version == "" { return "latest" } return buildinfo.Version } // DefaultVeleroImage returns the default container image to use for this version of Velero. func DefaultVeleroImage() string { return fmt.Sprintf("%s/%s:%s", imageRegistry(), "velero", ImageTag()) }

从实现可以清晰地看到两个要点：

1. 默认仓库：未显式注入ImageRegistry时，默认指向 Docker Hub 的velero组织，即velero/velero；
2. 默认标签：未显式注入Version时，回退为latest；正式构建时则注入当前版本号，得到velero/velero:vX.Y.Z这样的镜像名。

6.2 版本与仓库信息如何注入

imageRegistry与ImageTag依赖的buildinfo包（见 pkg/buildinfo/buildinfo.go）中定义了两个关键字段：

// Version is the current version of Velero, set by the go linker's -X flag at build time. Version string // ImageRegistry is the image registry that this build of Velero should use by default to pull the // Velero images. ImageRegistry string

注释明确指出：这两个字段由go linker 的-X标志在构建时注入。也就是说，镜像名中的版本号与仓库地址不是硬编码，而是构建流程的一部分——这与文档中"每个 git tag 都有匹配镜像"的约定相互印证：发布流水线在打 tag 时，把对应版本号注入构建，从而产出velero/velero:<SemVer>的镜像。

6.3 安装时如何应用默认镜像

DefaultVeleroImage()在安装流程中被多处使用：

• pkg/install/deployment.go#L275-L289 中，构造 Velero Deployment 时以velero.DefaultVeleroImage()作为默认镜像，并根据标签动态决定拉取策略：

func Deployment(namespace string, opts ...podTemplateOption) *appsv1api.Deployment { c := &podTemplateConfig{ image: velero.DefaultVeleroImage(), } ... pullPolicy := corev1api.PullAlways imageParts := strings.Split(c.image, ":") if len(imageParts) == 2 && imageParts[1] != "latest" { pullPolicy = corev1api.PullIfNotPresent } ... }

• pkg/install/daemonset.go#L35 中，node agent 的 DaemonSet 同样以默认镜像构造；
• pkg/cmd/cli/install/install.go#L235 中，velero install命令也将默认镜像写入安装选项。

这段代码揭示了两个值得注意的行为细节：

1. latest标签会触发PullAlways：只要镜像标签是latest（或没有显式 tag），Pod 每次启动都会尝试重新拉取，保证能拿到最新的latest指向；
2. 固定 SemVer 标签使用PullIfNotPresent：一旦本机已有该版本镜像，就不会重复拉取，减少不必要的网络请求与启动时间。

这从实现层面再次印证了文档中的语义划分：latest是"易变、需随时更新"的，而 SemVer 标签是"确定、稳定"的。

6.4 命令行覆盖：--image参数

虽然默认镜像已能覆盖绝大多数场景，但 Velero 也允许用户显式覆盖。在 pkg/cmd/cli/install/install.go#L110 中：

flags.StringVar(&o.Image, "image", o.Image, "Image to use for the Velero and node agent pods. Optional.")

即执行velero install时可通过--image指定自定义镜像，例如：

velero install \ --image velero/velero:v1.18.0 \ --provider aws \ --bucket my-bucket \ --secret-file ./credentials-velero

该值随后被写入安装选项（pkg/cmd/cli/install/install.go#L309），并最终应用到 Deployment 与 DaemonSet 的容器镜像上。这为私有镜像仓库、离线环境或内网镜像同步场景提供了灵活性——你可以把官方镜像同步到自己的仓库后，用--image指向内部地址（配合 6.2 中提到的ImageRegistry注入，构建产物也可直接面向自定义仓库）。

七、构建视角：Makefile 中的镜像标签规则

为了让"标签如何产生"更加具象，再看构建侧的默认参数。Makefile 中与镜像命名相关的变量如下：

BIN ?= velero REGISTRY ?= velero IMAGE ?= $(REGISTRY)/$(BIN) VERSION ?= main TAG_LATEST ?= false ifeq ($(TAG_LATEST), true) IMAGE_TAGS ?= $(IMAGE):$(VERSION) $(IMAGE):latest else IMAGE_TAGS ?= $(IMAGE):$(VERSION) endif

从这段构建配置可以推断出镜像标签的生成规则：

• 默认仓库/项目为velero、velero，默认镜像全名即velero/velero；
• 默认版本变量是main——这正对应文档中"main标签跟随main分支最新提交"的策略：日常开发构建默认产出velero/velero:main；
• 发布时设置VERSION=<SemVer>即可产出velero/velero:vX.Y.Z；
• 当TAG_LATEST=true时，构建会同时打上latest标签，与"latest跟随最近一次正式发布"的语义精确对应——发布流水线在发布新版本时额外加打latest，保证该标签始终指向最新稳定版。

八、实践建议：如何按场景选择镜像标签

综合文档约定与源码实现，给出如下选型建议：

同时记住两条与拉取行为相关的提醒：

• 使用latest时，Pod 的拉取策略为PullAlways，镜像变更后新 Pod 会自动拉到最新内容（pkg/install/deployment.go#L285-L289）；
• 使用固定 SemVer 标签时，拉取策略为PullIfNotPresent，如需强制刷新需手动删除本地镜像或临时改用latest。

结语

Velero 的镜像标签策略用三个标签覆盖了完整的使用周期：<SemVer>提供确定性发布、latest跟随最新稳定版、main紧跟开发主线。这套约定自 Ark 时代延续至今（镜像地址由gcr.io/heptio-images/ark演进为velero/velero），并在源码（internal/velero/images.go、pkg/install/deployment.go）与构建配置（Makefile）中得到了完整实现。理解并遵循这套标签约定，是安全、可维护地运行 Velero 的第一步。

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