Velero node-agent 节点亲和性(loadAffinity)设计解析:为 Volume Snapshot Data Movement 备份精确约束 VGDP 运行节点
Velero node-agent 节点亲和性(loadAffinity)设计解析:为 Volume Snapshot Data Movement 备份精确约束 VGDP 运行节点
导读
在 Kubernetes 环境下,Velero 通过 node-agent(DaemonSet)承载数据面(VGDP)实例来完成卷快照数据移动(Volume Snapshot Data Movement)备份,而数据面实例可以调度到任意允许调度的节点上运行。本文基于仓库中的《Node-agent Load Affinity Design》设计文档(design/Implemented/node-agent-affinity.md),完整解析其提出的 loadAffinity 配置机制:如何通过一个 ConfigMap 为卷快照数据移动备份的 VGDP 实例指定亲和性(affinity)与反亲和性(anti-affinity)规则,并结合源码验证从配置解析、按 StorageClass 匹配到翻译为 Pod 亲和性的完整实现链路。读完本文,你将掌握 node-agent 节点亲和性的设计动机、配置语法、创建方法以及调度失败时的排障思路。
背景:为什么 VGDP 实例需要节点亲和性
相关概念(Glossary)
- Velero Generic Data Path(VGDP):VGDP 是 Unified Repository 设计 中引入的一组模块集合。Velero 使用这些模块完成各类数据搬运任务(如 PodVolume 备份/恢复、Volume Snapshot Data Movement),包括 uploader 以及备份存储库(backup repository)。
- Exposer:Exposer 是 Volume Snapshot Data Movement 设计 中引入的模块。Velero 使用它将卷快照暴露给 node-agent Pod(或其关联 Pod),以便从快照完成数据移动。
node-agent 与 VGDP 的运行模型
Velero node-agent 是一个以 DaemonSet 方式运行的组件,承载控制器与 VGDP 模块,完成备份/恢复的具体工作,包括 PodVolume 备份/恢复和 Volume Snapshot Data Movement 备份/恢复。具体来说:
- node-agent 在每个节点上各运行一个 DataUpload 控制器实例,监听 DataUpload CR;
- 某个控制器实例接管一个 DataUpload CR 后,会在本节点启动一个 VGDP 实例,该实例初始化 uploader 与备份存储库连接,完成数据搬运;
- VGDP 实例运行在 node-agent Pod 内部,或运行在与该节点上 node-agent Pod 关联的 Pod(backupPod)中。
受数据量、数据复杂度、可用资源等因素影响,VGDP 可能耗时较长并消耗可观的 CPU、内存、网络带宽等资源。从技术上来说,VGDP 实例可以运行在任何允许 Pod 调度的节点上,但用户可能出于多种原因希望约束其运行节点:
- 某些节点上运行着更关键的业务负载,希望 VGDP 实例不要抢占这些节点;
- 某些节点资源更充裕,希望将 VGDP 实例集中调度到这些节点;
- 存储仅在特定节点上支持卷/快照的供给,希望 VGDP 实例只在这些节点运行。
因此,为了让数据面适应更广泛的部署拓扑,有必要为 VGDP 实例配置节点亲和性——尤其是对于 VGDP 实例运行频繁且集中的备份场景。
设计目标与边界(Goals / Non-Goals)
设计文档明确了如下目标:
- Goal 1:定义 node-agent 中卷快照数据移动备份场景下 VGDP 实例的节点亲和性行为;
- Goal 2:建立一套让用户为卷快照数据移动备份指定 VGDP 实例节点亲和性的机制。
同时,设计文档也明确划定了不做(Non-Goals)的边界,避免功能被盲目扩展:
- 不支持 PodVolume 备份/恢复的亲和性:因为 PodVolume 备份/恢复的 VGDP 实例必须运行在源/目标 Pod 所在的节点,无法迁移到其他节点;
- 不支持数据移动恢复(restore)的亲和性:例如当 StorageClass 的
volumeBindingMode为WaitForFirstConsumer时,恢复卷必须挂载到目标 Pod 被调度的节点,VGDP 实例必须与目标 Pod 同节点;同时考虑到恢复场景通常不会频繁、集中地运行,因此暂不支持; - 当前实现仅考虑 Exposer 的 backupPod 暴露方式:如 Volume Snapshot Data Movement 设计 所述,Exposer 可能以不同方式暴露快照,当前只支持通过 backupPod 这一种方式。未来若引入新的暴露方式,亲和性配置的定义与行为仍然有效,但可能需要新的实现。
配置载体:node-agent ConfigMap
通过 --node-agent-configmap 指定
亲和性配置存放在由 velero node-agent CLI 参数 --node-agent-configmap 指定的 ConfigMap 中。该参数在 pkg/cmd/cli/nodeagent/server.go 中注册:
command.Flags().StringVar(&config.nodeAgentConfig, "node-agent-configmap", config.nodeAgentConfig, "The name of ConfigMap containing node-agent configurations.")
需要说明的约束条件:
- 该 ConfigMap 不是 Velero 自动创建的,用户需要按需手动创建;
- ConfigMap 必须位于 Velero 安装的同一命名空间;
- 若在不同命名空间中安装了多个 Velero 实例,则每个命名空间各有一个 ConfigMap,且只作用于该命名空间内的 node-agent;
- node-agent 服务端在启动时检查这些配置并用于初始化相关 VGDP 模块。用户随时可以编辑该 ConfigMap,但要让修改生效,需要重启 node-agent 服务端。
从源码看,node-agent 服务端通过 getDataPathConfigs 在启动阶段读取该 ConfigMap,并将结果保存到 s.dataPathConfigs 中,供后续初始化 VGDP 相关模块使用。
ConfigMap 中的数据结构
ConfigMap 内部新增一种名为 loadAffinity 的配置。设计文档给出了如下数据结构:
type Configs struct {
// LoadConcurrency is the config for load concurrency per node.
LoadConcurrency *LoadConcurrency `json:"loadConcurrency,omitempty"`
// LoadAffinity is the config for data path load affinity.
LoadAffinity []*LoadAffinity `json:"loadAffinity,omitempty"`
}
type LoadAffinity struct {
// NodeSelector specifies the label selector to match nodes
NodeSelector metav1.LabelSelector `json:"nodeSelector"`
}
这一结构在仓库中已落地为真实类型。在 pkg/types/node_agent.go 中,NodeAgentConfigs 是 node-agent 配置的完整载体,包含 LoadConcurrency、LoadAffinity、BackupPVCConfig、RestorePVCConfig、PodResources、PriorityClassName、PodAnnotations、PodLabels 等多项配置;LoadAffinity 类型定义于 pkg/types/node_agent.go。而实际承载亲和性配置的 kube.LoadAffinity 结构体定义在 pkg/util/kube/pod.go,它在设计文档的基础上增加了一个关键字段:
type LoadAffinity struct {
// NodeSelector specifies the label selector to match nodes
NodeSelector metav1.LabelSelector `json:"nodeSelector"`
// StorageClass specifies the VGDPs the LoadAffinity applied to. If the StorageClass doesn't have value, it applies to all. If not, it applies to only the VGDPs that use this StorageClass.
StorageClass string `json:"storageClass"`
}
也就是说,实际实现支持按 StorageClass 细化亲和性:storageClass 为空时配置对全局生效,非空时仅对使用该 StorageClass 的 VGDP 生效(详见下文“按 StorageClass 匹配亲和性”一节)。
为什么 loadAffinity 是数组
用户可能希望根据不同的条件(如不同的 StorageClass、CSI 驱动所代表的存储)设置不同的 LoadAffinity 配置,因此设计文档将 loadAffinity 定义为数组。这是出于可扩展性考虑——当前版本并不支持多配置,因此如果数组中存在多条配置,实现上总是取数组中的第一条。而在实际的代码演进中,配合 StorageClass 字段,GetLoadAffinityByStorageClass 已经实现了按 StorageClass 精确匹配、未匹配时回退到全局配置(StorageClass 为空的那条)的查找逻辑。
亲和性与反亲和性的语义
loadAffinity 内的 nodeSelector 使用 Kubernetes 标准的 metav1.LabelSelector,通过两种方式表达亲和/反亲和规则:
Affinity(亲和性):允许 VGDP 实例在指定节点运行
- MatchLabels:
MatchLabels中的标签默认表示LabelSelectorOpIn操作,因此在本上下文中会被当作亲和规则处理——只有带这些标签的节点才允许运行 VGDP 实例; - MatchExpressions:标签定义在
MatchExpressions的Key和Values中,Operator必须设置为LabelSelectorOpIn或LabelSelectorOpExists。
Anti-affinity(反亲和性):禁止 VGDP 实例在指定节点运行
- 通过
MatchExpressions定义,Operator必须设置为LabelSelectorOpNotIn或LabelSelectorOpDoesNotExist。
需要提醒的是:亲和性与反亲和性规则位于同一个 nodeSelector 内,且相互独立地作用于调度过程——最终的调度结果是“同时满足所有亲和条件、且不落入任何反亲和条件”的节点集合。
完整示例与创建方法
设计文档给出了一个完整的 ConfigMap 数据示例,同时涵盖了亲和性与反亲和性:
{
"loadAffinity": [
{
"nodeSelector": {
"matchLabels": {
"beta.kubernetes.io/instance-type": "Standard_B4ms"
},
"matchExpressions": [
{
"key": "kubernetes.io/hostname",
"values": [
"node-1",
"node-2",
"node-3"
],
"operator": "In"
},
{
"key": "xxx/critial-workload",
"operator": "DoesNotExist"
}
]
}
}
]
}
该示例包含两条亲和性配置和一条反亲和性配置:
| 规则类型 | 配置内容 | 语义 |
|---|---|---|
| 亲和性(matchLabels) | beta.kubernetes.io/instance-type=Standard_B4ms |
VGDP 实例只会在带该标签的节点上运行 |
| 亲和性(matchExpressions) | kubernetes.io/hostname In [node-1, node-2, node-3] |
VGDP 实例只会运行在 node-1、node-2、node-3 上 |
| 反亲和性(matchExpressions) | xxx/critial-workload DoesNotExist |
VGDP 实例不会运行在带有 xxx/critial-workload 标签的节点上 |
创建 ConfigMap
用户需要先把类似上述示例的内容保存为一个 JSON 文件,然后执行以下命令创建 ConfigMap:
kubectl create cm <ConfigMap name> -n velero --from-file=<json file name>
例如,将示例保存为 load-affinity.json 后:
kubectl create cm node-agent-config -n velero --from-file=load-affinity.json
创建完成后,需要确保 node-agent 的启动参数 --node-agent-configmap 指向该 ConfigMap 名称,并重启 node-agent 使配置生效。
实现原理:loadAffinity 如何作用于备份 Pod
从 LabelSelector 到 corev1.Affinity 的翻译
如 Volume Snapshot Data Movement 设计 所述,Exposer 决定 VGDP 实例在哪里启动。目前对于卷快照数据移动备份,Exposer 会创建 backupPod,VGDP 实例将随 backupPod 的调度结果在对应节点上启动。因此,loadAffinity 会被翻译(从 metav1.LabelSelector 翻译为 corev1.Affinity)并设置到 backupPod 上。
翻译逻辑实现在 pkg/util/kube/pod.go 的 ToSystemAffinity 函数中:
- 将
MatchLabels中的每个标签键值对转换为NodeSelectorOpIn的NodeSelectorRequirement; - 将
MatchExpressions中的每条表达式原样转换为NodeSelectorRequirement(保留其Operator,从而保留In/NotIn/Exists/DoesNotExist等语义); - 将所有 requirement 汇总到
NodeAffinity.RequiredDuringSchedulingIgnoredDuringExecution的NodeSelectorTerms中; - 若调用方提供了卷拓扑(
volumeTopology,即存储拓扑),还会将卷拓扑的NodeSelectorTerms一并合并进来,确保备份 Pod 既能满足用户亲和性,又能访问快照卷。
在 CSI 快照 Exposer 的实现 pkg/exposer/csi_snapshot.go 中,先通过 kube.GetLoadAffinityByStorageClass 按备份 PVC 的 StorageClass 取出匹配的亲和性配置,随后在 csi_snapshot.go 处调用 kube.ToSystemAffinity(affinity, volumeTopology) 生成 Pod 亲和性,并在创建 backupPod 时通过 Affinity: podAffinity(csi_snapshot.go)将其注入 Pod 规格。创建成功后日志会记录 Backup pod is created 及其携带的 affinity(csi_snapshot.go)。
按 StorageClass 匹配亲和性
GetLoadAffinityByStorageClass 的查找逻辑如下:
- 遍历
loadAffinity数组,优先查找StorageClass与备份 PVC 的 StorageClass 完全匹配的配置,命中即返回(深拷贝,避免污染共享配置); - 若未找到匹配项,则回退到
StorageClass为空(全局)的那条配置; - 两者都没有时,返回空,即不施加亲和性约束。
该函数返回的是配置的深拷贝(deepCopy,见 pkg/util/kube/pod.go),确保调用方修改结果时不会破坏 node-agent 共享的配置对象。
与 node-agent DaemonSet 调度的配合
设计文档特别强调了一个容易踩坑的点:
- node-agent 作为 DaemonSet,并不一定在每个工作节点上都运行 Pod,用户可以通过给 node-agent DaemonSet 指定
nodeSelector或nodeAffinity来限制其分布; - 而当前实现中,VGDP 实例必须被调度到有 node-agent Pod 运行的节点上;
- 因此,如果 node-agent 本身有节点选择配置,用户必须将其一并考虑进 loadAffinity 配置中,以保证 VGDP 实例始终被调度到存在 node-agent 的节点上;
- 这一责任在用户侧,Velero 不会继承 node-agent DaemonSet 的任何节点选择配置——因为设计文档认为 DaemonSet 调度器与普通 Pod 调度器的工作方式不同,简单地全量继承可能引发 backupPod 调度出现意外结果。
如果 backupPod 被调度到没有 node-agent Pod 的节点,对应的 DataUpload CR 将停留在 Accepted 阶段,直到 prepare 超时(默认 30 分钟)。
调度失败的排查与处理
快照卷不可达导致的调度失败
作为 expose 操作的一部分,Exposer 会从快照创建一个卷(由 backupPVC 表示)。backupPVC 与源卷使用相同的 StorageClass:
- 若该 StorageClass 的
volumeBindingMode为Immediate,卷会在等待 backupPod 之前立即从底层存储分配; - 此时如果 backupPod 被调度到快照卷不可访问的节点(例如因存储拓扑限制),backupPod 将无法进入 Running 状态,数据移动无法完成。
设计文档给出了该问题发生时 backupPod 的状态示例:
status:
conditions:
- lastProbeTime: null
message: '0/2 nodes are available: 1 node(s) didn''t match Pod''s node affinity/selector,
1 node(s) had volume node affinity conflict. preemption: 0/2 nodes are available:
2 Preemption is not helpful for scheduling..'
reason: Unschedulable
status: "False"
type: PodScheduled
phase: Pending
从消息中可以清晰地看到两类原因:节点不匹配 Pod 的 node affinity/selector(即用户配置的亲和性排除了所有可用节点),以及卷节点亲和性冲突(存储拓扑约束与调度冲突)。
Prepare 超时与诊断机制
- 问题发生后,backupPod 停留在
Pending阶段,对应 DataUpload CR 停留在Accepted阶段,直到 prepare 超时(默认 30 分钟)后 backupPod 被删除; - 超时时间由 node-agent 的
--data-mover-prepare-timeout参数控制,默认值为 30 分钟(见 pkg/cmd/cli/nodeagent/server.go); - 超时逻辑位于 DataUpload 控制器的 onPrepareTimeout,当
time.Since(du.Status.AcceptedTimestamp.Time)超过preparingTimeout时触发(data_upload_controller.go),将 DataUpload 状态消息置为timeout on preparing data upload。
由于 backupPod 在 prepare 超时后即被删除,用户无法再据此判断失败原因究竟是上述哪一类。为此,设计文档提出可以增加诊断机制:在因 prepare 超时删除 backupPod 之前,先收集同一节点上 backupPod 与 node-agent 的状态信息用于排障。仓库中已有对应的诊断工具函数 DiagnosePod,它会汇总 Pod 的 phase、node name、status message、各 condition 以及相关 Warning 事件,可用于生成上述场景的诊断报告。
小结
loadAffinity 机制为 Velero 卷快照数据移动备份提供了将 VGDP 实例约束到指定节点的能力,使用户能够:避开运行关键业务的节点、将备份集中到资源充裕的节点、或贴合存储拓扑限制。配置以数组形式存于 --node-agent-configmap 指定的 ConfigMap 中,支持基于 metav1.LabelSelector 的亲和/反亲和表达,实现上由 Exposer 在创建 backupPod 时经 ToSystemAffinity 翻译后注入 Pod 调度约束,并支持按 StorageClass 精确匹配。使用时需注意 node-agent DaemonSet 自身的节点选择必须同步纳入亲和性配置,同时要警惕存储拓扑冲突导致的 Unschedulable 与 prepare 超时问题。
参考链接
- 设计文档:design/Implemented/node-agent-affinity.md
- VGDP 上游设计:design/Implemented/unified-repo-and-kopia-integration/unified-repo-and-kopia-integration.md
- Volume Snapshot Data Movement 设计:design/Implemented/volume-snapshot-data-movement/volume-snapshot-data-movement.md
- node-agent 服务端配置加载:pkg/cmd/cli/nodeagent/server.go
- node-agent 配置结构定义:pkg/types/node_agent.go
- 亲和性翻译与按 StorageClass 匹配:pkg/util/kube/pod.go
- CSI 快照 Exposer 对亲和性的应用:pkg/exposer/csi_snapshot.go
- DataUpload 控制器 prepare 超时逻辑:pkg/controller/data_upload_controller.go