Velero EnableAPIGroupVersions 特性：多 API 组版本备份与优先级恢复，实现跨版本 Kubernetes 集群迁移-酒店常州论坛

Velero EnableAPIGroupVersions 特性：多 API 组版本备份与优先级恢复，实现跨版本 Kubernetes 集群迁移

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

本文基于 Velero 官方文档enable-api-group-versions-feature.md（v1.11 版），结合仓库源码深入解析 EnableAPIGroupVersions 特性：它让 Velero 在备份时捕获源集群上所有受支持的 API 组版本，并在恢复时按“目标集群偏好版本 > 源集群偏好版本 > 公共支持版本”的优先级链（以及可选的 ConfigMap 用户覆盖）自动选择可恢复的版本，使源、目标集群之间跨多个 Kubernetes API 版本的迁移成为可能。读完后你将掌握该特性的启用方式、版本选择算法的源码实现、自定义版本优先级的 ConfigMap 配置方法及故障排查手段。

背景：为什么迁移时需要处理 API 组版本差异

Velero 既用于备份与恢复，也用于 Kubernetes 应用及其持久卷的跨集群迁移。日常的备份/恢复通常不涉及 Kubernetes API 组版本（API group version）的升级；但在从源集群迁移到目标集群时，两个集群的 API 组版本经常不一致。

先明确概念：Kubernetes 应用由多种资源组成，常见资源如 Pod、Job、Deployment；自定义资源则通过 CRD（Custom Resource Definitions）创建。每一种资源（无论是否自定义）都属于某个 group，每个 group 有若干版本，即 API 组版本。

Kubernetes 默认只允许跨集群变更 API 组版本且“只跳一个版本”，例如 v1 -> v2beta1；而跨多个版本（如 v1 -> v3）是不被原生支持的。EnableAPIGroupVersions 特性正是为了在升级、迁移或恢复过程中缓解这类兼容性问题而设计的。

适用前提：该特性目前处于 beta 阶段，需要通过 Velero 安装时的 feature flag--features=EnableAPIGroupVersions启用。开始升级/迁移前，应查阅源与目标集群对应 Kubernetes 版本的发行说明，确认 API 版本兼容矩阵；若存在差异，即应启用本特性。

特性工作原理

备份侧：不仅备份偏好版本，还备份所有受支持版本

在源集群启用该特性后，Velero 不仅备份 Kubernetes 的preferred（偏好）API 组版本，还会备份集群上所有受支持的版本。

以horizontalpodautoscalers（属于autoscaling组）为例：未启用 flag 时，只备份autoscaling组的偏好版本v2；启用后，其余受支持版本如v1也会一并备份。这些版本存入备份 tarball 后，即可在目标集群上按需选择恢复。

从源码结构看，这一行为发生在 discovery 层。discovery/helper.go 中，当 flag 启用时改用ServerGroupsAndResources（返回全部 APIGroup 与 APIResourceList，而非仅偏好版本），否则调用ServerPreferredResources：

if features.IsEnabled(velerov1api.APIGroupVersionsFeatureFlag) { // ServerGroupsAndResources returns all APIGroup and APIResouceList - not only preferred versions _, serverAllResources, err := refreshServerGroupsAndResources(h.discoveryClient, h.logger) ... } else { // ServerPreferredResources() returns only preferred APIGroup - this is the default serverPreferredResources, err := refreshServerPreferredResources(h.discoveryClient, h.logger) ... }

备份落盘时，多版本写入 tarball 的目录结构中。item_backupper.go 中，偏好版本会额外写入一份不带版本子目录的文件（向后兼容旧格式），并在版本目录路径后追加-preferredversion后缀（常量PreferredVersionDir定义于 constants.go）：

if versionPath == preferredGVR.Version { // backing up preferred version backup without API Group version - for backward compatibility fileForArchive, err := getFileForArchive(namespace, name, groupResource.String(), "", itemBytes) ... versionPath = versionPath + velerov1api.PreferredVersionDir }

因此 tarball 内同一资源可能同时存在resources/horizontalpodautoscalers.autoscaling/v1/...、resources/horizontalpodautoscalers.autoscaling/v2/...与resources/horizontalpodautoscalers.autoscaling/v2-preferredversion/...等目录。恢复侧正是通过解析这些目录名来获取“源集群备份了哪些版本”——实现见 parser.go 的ParseGroupVersions方法：

// ParseGroupVersions extracts the versions for each API Group from the backup // directory names and stores them in a metav1 APIGroup object. func (p *Parser) ParseGroupVersions(dir string) (map[string]metav1.APIGroup, error) { resourcesDir := filepath.Join(dir, velerov1api.ResourcesDir) ... }

此外还有一个联动细节：当 flag 启用时，内置的velero.io/crd-remap-version备份插件不会被注册，以保证 v1 版 CRD 也能被备份（见 plugin.go 中的注释 "Do not register crd-remap-version BIA if the API Group feature flag is enabled, so that the v1 CRD can be backed up"）。

恢复侧：按优先级顺序选择版本

在目标集群启用该特性后，Velero 恢复时会依据如下优先级（从高到低）选择 API 组版本：

Priority 1：目标集群的 preferred 版本；
Priority 2：源集群的 preferred 版本（前提是目标集群支持它）；
Priority 3：非偏好但双方共同支持的版本中，Kubernetes 版本优先级最高的一个。

其中 Priority 3 涉及对 Kubernetes 版本优先级顺序的理解：Kubernetes 将最新、最稳定的版本置于最高优先级（preferred 版本即排序第一者）。一个来自 Kubernetes 官方文档的排序示例：

v10
v2
v1
v11beta2
v10beta3
v3beta1
v12alpha1
v11alpha2
foo1
foo10

若存在多个非偏好公共支持版本，则选取该排序中优先级最高者（见上文的 Priority 3 Case D 图）。

上述三条规则在实际代码中的落地非常清晰，核心方法是 prioritize_group_version.go 的chooseAPIVersionsToRestore：

默认值先取源集群偏好版本（sg.PreferredVersion.Version），即未启用该特性时的行为；
Priority 1：若源集群备份版本列表sg.Versions中包含目标集群偏好版本，则选用目标偏好版本；
Priority 2：若目标集群支持源集群偏好版本，则选用源偏好版本；
Priority 3：遍历目标集群非偏好版本（tg.Versions[1:]），找到同时出现在源集群非偏好版本（sg.Versions[1:]）中的第一个——由于两个列表都已按 Kubernetes 版本优先级降序排序，第一个交集即“最高公共支持版本”；
全部落空时，回退到源偏好版本继续恢复（与未启用特性时行为一致，保证向后兼容）。

每个决策都会输出 Debug 日志（如APIGroupVersionsFeatureFlag Priority 1: Cluster preferred API group version %s found in backup for %s），便于审计选择了哪个版本。

版本排序本身复用了 Kubernetes 的排序函数：

// k8sPrioritySort sorts slices using Kubernetes' version prioritization. func k8sPrioritySort(gvs []metav1.GroupVersionForDiscovery) { sort.SliceStable(gvs, func(i, j int) bool { return version.CompareKubeAwareVersionStrings(gvs[i].Version, gvs[j].Version) > 0 }) }

该特性生效有两个前置条件，均在 restore.go 中检查：restore 进程上启用了 flag，且备份对象的Status.FormatVersion >= "1.1.0"（1.1.0 格式从 Velero 1.4 开始使用，旧格式目录结构无法识别多版本，因此不做版本选择）。

选定版本后，恢复路径会被改写：restore.go 中，若ctx.chosenGrpVersToRestore命中该 resource.group，则资源路径从horizontalpodautoscalers.autoscaling变为horizontalpodautoscalers.autoscaling/v2beta1（或对应目录名），从而从 tarball 中取出对应版本的资源文件继续正常恢复：

cgv, ok := ctx.chosenGrpVersToRestore[resource] if ok { resourceForPath = filepath.Join(resource, cgv.Dir) }

使用步骤

在源集群上安装 Velero 并启用 feature flag--features=EnableAPIGroupVersions。注意：要让该特性生效，源集群和目标集群两侧的 Velero 安装都必须带上该 flag。flag 的启用方式参见 customize-installation.md 中“Enable Server-Side Features”一节；安装基础步骤参见 basic-install.md。
按照 migration-case.md 中的迁移案例流程执行备份与恢复。其中“Cluster 1”指源集群，“Cluster 2”指目标集群。

高级用法：用 ConfigMap 自定义版本优先级

可选地，用户可以在目标集群上创建一个 ConfigMap，覆盖部分或全部被迁移资源的默认版本优先级。规则是：对用户指定的每个 resource.group，Velero 会到备份 tarball 与目标集群中查找该版本——若匹配，则使用用户指定的 API 组版本恢复；若用户列出的版本在任一侧都不存在/不支持，则回退到默认优先级链。

步骤（须在目标集群上、发起 Velero restore 之前完成）：

创建文件restoreResourcesVersionPriority（文件名会成为 ConfigMapdata字段的 key）。文件中每行写一个要覆盖的 resource.group，格式为<resource>.<group>=<用户最高优先级版本>,<次高版本>：group 与版本之间用单个等号（=）分隔，多个版本按用户优先级顺序用逗号分隔。示例内容：
```
rockbands.music.example.io=v2beta1,v2beta2 orchestras.music.example.io=v2,v3alpha1 subscriptions.operators.coreos.com=v2,v1
```

创建 ConfigMap：

kubectl create configmap enableapigroupversions --from-file=<absolute path>/restoreResourcesVersionPriority -n velero

查看 ConfigMap：

kubectl describe configmap enableapigroupversions -n velero

预期输出：

Name: enableapigroupversions Namespace: velero Labels: <none> Annotations: <none> Data ==== restoreResourcesVersionPriority: ---- rockbands.music.example.io=v2beta1,v2beta2 orchestras.music.example.io=v2,v3alpha1 subscriptions.operators.coreos.com=v2,v1 Events: <none>

从源码看，用户自定义版本对应优先级链中的Priority 0：chooseAPIVersionsToRestore会优先调用findSupportedUserVersion，取用户列表中第一个同时被目标集群和源集群备份支持的版本；找不到时输出Cannot find user defined version in both the cluster and backup cluster. Ignoring version ...并继续走默认优先级。ConfigMap 由userPriorityConfigMap函数从 Velero 所在命名空间（默认velero）读取，名为enableapigroupversions、数据键为restoreResourcesVersionPriority（见 prioritize_group_version.go）。

配置解析对格式有严格校验（validateUserPriority）：每行有且仅有一个等号、等号两侧至少各一个字符、行内不能含空格（解析前会先做 CRLF/CR 换行归一化与去空格预处理）。不符合规则的整行会被丢弃并记录 Debug 日志，因此编写该文件时务必避免多余空格与注释。

故障排查

通用排查手段同样适用，参见 troubleshooting.md。
Velero 的 debug 日志中会记录每个资源最终选择了哪个版本（APIGroupVersionsFeatureFlag Priority N: ...系列日志），这是定位版本选择问题的第一手信息。
若没有任何 API 组版本既存在于备份 tarball 又被目标集群支持，恢复将记录如下错误（无需开启 debug 日志级别即可看到）：
```
"error restoring rockbands.music.example.io/rockstars/beatles: the server could not find the requested resource"
```

局限性与注意事项

结合设计文档 restore-with-EnableAPIGroupVersions-feature.md 中的“Non Goals”一节，该特性有以下边界：

只支持向前跳版本：仅允许恢复到比源集群更新的 Kubernetes 版本，不支持恢复到比源集群更旧的集群；
仅支持 Velero 1.4+ 的备份：备份Status.FormatVersion必须为 1.1.0，旧格式备份不会做版本选择；
不修改备份 tarball：避免对压缩备份做任何改写，防止数据损坏；
无插件兜底：若目标集群完全不支持源集群的任一 API 组版本，当前不会尝试用插件转换资源，恢复会继续按源偏好版本处理（通常会失败并产生上文“could not find the requested resource”类错误）。

小结

EnableAPIGroupVersions 通过“备份侧全量版本捕获 + 恢复侧多级优先级选择 + 可选用户覆盖”的组合，解决了跨多个 Kubernetes API 版本迁移时的兼容性难题。启用只需在源、目标两集群的安装参数中加上--features=EnableAPIGroupVersions；需要精细控制时，再为目标集群创建enableapigroupversionsConfigMap。相关实现集中在 pkg/restore/prioritize_group_version.go（版本选择与 ConfigMap 解析）、pkg/discovery/helper.go（多版本 discovery）、pkg/backup/item_backupper.go（多版本落盘）以及 pkg/restore/restore.go（恢复路径改写），对应的单元/集成测试可见 prioritize_group_version_test.go 与 test/e2e/basic/api-group/enable_api_group_versions.go，可供进一步深入。

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

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

企业官网建设流程全解析