Velero node-agent 并发控制设计:VGDP 并发实例的全局与按节点配额机制
Velero node-agent 并发控制设计:VGDP 并发实例的全局与按节点配额机制
导读
本文围绕 Velero 仓库中 node-agent 并发能力的设计文档,讲解如何通过一个 ConfigMap 为每个节点上的 VGDP(Velero Generic Data Path,通用数据路径)实例数量设置并发上限,从而在有限的 CPU、内存与网络带宽资源下取得备份/恢复吞吐与稳定性之间的平衡。读完本文,你将掌握 loadConcurrency 配置项的完整数据结构、全局与按节点并发数的作用规则与优先级、ConfigMap 的创建与生效方式,以及并发限额在 node-agent 服务端与 data path manager 中的真实实现路径,可直接用于规划生产集群中 node-agent 的负载并发策略。
背景:为什么需要为 node-agent 配置并发
Velero node-agent 是一个以 DaemonSet 形式部署的守护进程组件,承载控制器与 VGDP 模块,负责完成备份/恢复中的具体数据搬运工作,典型场景包括 PodVolume backup/restore(文件系统级备份/恢复)与 Volume Snapshot Data Movement(卷快照数据移动)。例如,node-agent 会在每个节点上运行 DataUpload 控制器,监听 DataUpload CR;某个控制器实例拿到一个 DataUpload CR 后,会启动一个 VGDP 实例——该实例内部初始化 uploader 实例与备份仓库连接——来完成数据传输。VGDP 实例可能直接运行在 node-agent Pod 内,也可能运行在与 node-agent Pod 相关联的、位于同一节点上的其他 Pod 中。
由于数据规模、数据复杂度和资源可用性各不相同,VGDP 实例可能耗时很长,且会占用可观的 CPU、内存和网络带宽。从技术上看,VGDP 实例彼此之间是并发无关的:例如一个用于 PodVolume backup 的 VGDP 实例,可以与另一个用于 DataUpload 的 VGDP 实例并行运行。但这两个实例如果位于同一节点,就会共享该节点的资源。
因此,在有限资源下获得最优性能,就值得为每个节点配置 VGDP 的并发实例数量:当节点资源充足时,可以调大并发数以缩短备份/恢复耗时;当节点资源紧张时,则应调小并发数,否则备份/恢复可能遭遇时间延迟、挂起甚至 OOM Kill 等问题。相关设计文档见 node-agent-concurrency.md。
设计目标与边界
本设计的目标有两个:
- 定义 node-agent 中 VGDP 并发实例的行为;
- 提供一种机制,让用户能够指定每个节点的 VGDP 并发数量。
同时,设计文档明确了当前不做(Non-Goals)的边界:
- 跨节点并发:不同节点上的 VGDP 实例始终并发运行,因为在大多数常见场景下节点间资源是隔离的;对于某些跨节点共享资源的特殊情况,目前不支持限制。
- 恢复优先调度:实际生产中恢复往往具有更高优先级(例如灾备场景),但当前设计不区分优先级——当恢复对应的 VGDP 实例撞上并发上限时,即使占用额度的是备份实例,它同样会被阻塞。如果用户遇到此类问题,应考虑先停止备份。
- 完全阻断某节点的备份/恢复:有时用户想完全禁止某个节点上的备份/恢复运行,这超出了本设计范围。要做到这一点需要联动更多模块(如数据移动的 exposer 等),单纯限制 VGDP(例如把并发数设为 0)并不能奏效。例如对于 fs-backup,VGDP 实例必须运行在源 Pod 所在的节点,如果只是从 VGDP 层阻断,PodVolumeBackup CR 仍会被提交但永远不会被处理。
解决方案:通过 ConfigMap 下发并发配置
解决方案的核心是引入一个 ConfigMap,由 velero node-agent CLI 的参数 --node-agent-configmap 指定其名称,用于承载 node-agent 相关配置。该 ConfigMap 由用户按需手动创建,Velero 不会自动创建它,并且它必须位于 Velero 安装所在的命名空间中。如果多个 Velero 实例安装在不同命名空间,则每个命名空间各有一个 ConfigMap,各自只作用于该命名空间内的 node-agent。
node-agent 服务端在启动时读取这些配置,并用它们初始化相关 VGDP 模块。因此用户虽然可以随时编辑这个 ConfigMap,但要让修改生效,必须重启 node-agent 服务端。
从当前仓库的代码来看,该 ConfigMap 已被扩展为多种 node-agent 配置的载体(如 loadAffinity、backupPVC、podResources 等,见 pkg/types/node_agent.go),而本文主题对应的并发配置即其中的 loadConcurrency 一项。在设计文档成文时,loadConcurrency 是 ConfigMap 中唯一的配置种类。
数据结构定义
设计文档给出的配置结构如下:
type Configs struct {
// LoadConcurrency is the config for load concurrency per node.
LoadConcurrency *LoadConcurrency `json:"loadConcurrency,omitempty"`
}
type LoadConcurrency struct {
// GlobalConfig specifies the concurrency number to all nodes for which per-node config is not specified
GlobalConfig int `json:"globalConfig,omitempty"`
// PerNodeConfig specifies the concurrency number to nodes matched by rules
PerNodeConfig []RuledConfigs `json:"perNodeConfig,omitempty"`
}
type RuledConfigs struct {
// NodeSelector specifies the label selector to match nodes
NodeSelector metav1.LabelSelector `json:"nodeSelector"`
// Number specifies the number value associated to the matched nodes
Number int `json:"number"`
}
对照当前仓库源码 pkg/types/node_agent.go,LoadConcurrency 结构体在实现中还增加了一个可选字段 PrepareQueueLength(控制处于 expose 阶段的负载最大数量,配合 exposer.VgdpCounter 使用),而并发控制本身的 GlobalConfig 与 PerNodeConfig 字段与设计文档保持一致:
type LoadConcurrency struct {
// GlobalConfig specifies the concurrency number to all nodes for which per-node config is not specified
GlobalConfig int `json:"globalConfig,omitempty"`
// PerNodeConfig specifies the concurrency number to nodes matched by rules
PerNodeConfig []RuledConfigs `json:"perNodeConfig,omitempty"`
// PrepareQueueLength specifies the max number of loads that are under expose
PrepareQueueLength int `json:"prepareQueueLength,omitempty"`
}
全局并发数(globalConfig)
globalConfig 用于指定一个应用于所有节点的并发数,仅当某节点没有对应的按节点配置时生效:
- 该数值从 1 开始,1 表示没有并发,同一时刻只允许一个 VGDP 实例运行;
- 没有上限(no roof limit),用户可以按需调大;
- 如果该数值未指定或非法(例如小于等于 0),则使用硬编码的默认值 1。
在服务端实现中,getDataPathConcurrentNum 会先取出 globalConfig,一旦发现 <= 0 就回退到默认值(pkg/cmd/cli/nodeagent/server.go 中常量 defaultDataPathConcurrentNum = 1):
func (s *nodeAgentServer) getDataPathConcurrentNum(defaultNum int) int {
configs := s.dataPathConfigs
if configs == nil || configs.LoadConcurrency == nil {
s.logger.Infof("Concurrency configs are not found, use the default number %v", defaultNum)
return defaultNum
}
globalNum := configs.LoadConcurrency.GlobalConfig
if globalNum <= 0 {
s.logger.Warnf("Global number %v is invalid, use the default value %v", globalNum, defaultNum)
globalNum = defaultNum
}
if len(configs.LoadConcurrency.PerNodeConfig) == 0 {
return globalNum
}
// ...
}
按节点并发数(perNodeConfig)
perNodeConfig 允许为不同节点指定不同的并发数。例如:Node-1 允许 3 个并发实例、Node-2 允许 2 个、Node-3 允许 1 个。设计动机如下:
- 节点资源差异:不同节点的资源可能不同,可为资源较少的节点配置较小的并发数,为资源较多的节点配置较大的并发数;
- 隔离关键环境:用户可能在特定节点上运行关键工作负载,由于 VGDP 实例可能消耗大量资源,用户希望在这些节点上运行更少的并发实例。
按节点并发数的取值范围与全局并发数一致。按节点配置优先于全局配置——一旦命中规则,将覆盖该节点的全局并发数。
perNodeConfig 是一个 RuledConfigs 列表,每个元素通过标签选择器(label selector)匹配一个或多个节点,并为匹配到的节点指定并发数。也就是说,节点通过标签来识别。例如:
"nodeSelector: kubernetes.io/hostname=node1; number: 3"
"nodeSelector: beta.kubernetes.io/instance-type=Standard_B4ms; number: 5"
- 第一个元素表示:主机名为
node1的节点获得按节点并发数 3; - 第二个元素表示:所有带有标签
beta.kubernetes.io/instance-type=Standard_B4ms的节点获得按节点并发数 5。
规则匹配的语义细节:
- 预期至少有一个节点带有规则指定的标签;如果没有任何节点带该标签,这条规则不产生效果;
- 如果一个节点命中多条规则(例如 node1 同时也带有
beta.kubernetes.io/instance-type=Standard_B4ms标签),将取最小的数值(上例中为 3)。
这一点与实现完全一致:在 getDataPathConcurrentNum 中,服务端遍历 PerNodeConfig,用 metav1.LabelSelectorAsSelector 将规则转换成 selector,与当前节点的标签做匹配,并始终取所有命中规则中的最小值(初始值为 math.MaxInt32):
concurrentNum := math.MaxInt32
for _, rule := range configs.LoadConcurrency.PerNodeConfig {
selector, err := metav1.LabelSelectorAsSelector(&(rule.NodeSelector))
if err != nil {
s.logger.WithError(err).Warnf("Failed to parse rule with label selector %s, skip it", rule.NodeSelector.String())
continue
}
if rule.Number <= 0 {
s.logger.Warnf("Rule with label selector %s is with an invalid number %v, skip it", rule.NodeSelector.String(), rule.Number)
continue
}
if selector.Matches(labels.Set(curNode.GetLabels())) {
if concurrentNum > rule.Number {
concurrentNum = rule.Number
}
}
}
if concurrentNum == math.MaxInt32 {
s.logger.Infof("Per node number for node %s is not found, use the global number %v", s.nodeName, globalNum)
concurrentNum = globalNum
} else {
s.logger.Infof("Use the per node number %v over global number %v for node %s", concurrentNum, globalNum, s.nodeName)
}
注意实现细节:当某条规则的 Number <= 0 或 selector 解析失败时,该规则会被跳过;如果当前节点没有命中任何有效规则,则回退到全局并发数。
完整配置示例
设计文档给出的 ConfigMap 内容示例如下:
{
"loadConcurrency": {
"globalConfig": 2,
"perNodeConfig": [
{
"nodeSelector": {
"matchLabels": {
"kubernetes.io/hostname": "node1"
}
},
"number": 3
},
{
"nodeSelector": {
"matchLabels": {
"beta.kubernetes.io/instance-type": "Standard_B4ms"
}
},
"number": 5
}
]
}
}
该配置的含义是:默认情况下每个节点允许 2 个 VGDP 并发实例;主机名为 node1 的节点例外,允许 3 个;所有 beta.kubernetes.io/instance-type=Standard_B4ms 的节点例外,允许 5 个(若某个节点同时命中这两条规则,则取较小值 3)。
实战:创建并启用配置
创建 ConfigMap
按设计文档,用户需要先把类似上面的 JSON 内容保存到本地文件中,然后执行:
kubectl create cm <ConfigMap name> -n velero --from-file=<json file name>
例如,将上述 JSON 保存为 node-agent-config.json,再执行:
kubectl create cm node-agent-config -n velero --from-file=node-agent-config.json
需要注意:ConfigMap 必须创建在 Velero 安装的命名空间中,且 Velero 不会自动创建它。
挂接配置到 node-agent
在安装 Velero 时,通过 velero install 的 --node-agent-configmap 参数把 ConfigMap 名称传给 node-agent。仓库中的安装代码将其作为 node-agent 容器的启动参数写入 DaemonSet(见 pkg/install/daemonset.go):
daemonSetArgs = append(daemonSetArgs, fmt.Sprintf("--node-agent-configmap=%s", c.nodeAgentConfigMap))
安装时还会对 ConfigMap 做一次校验(见 pkg/cmd/cli/install/install.go 中 --node-agent-configmap 相关逻辑,通过 VerifyJSONConfigs 把 ConfigMap 数据解析为 NodeAgentConfigs 结构,解析失败会直接报错)。
node-agent 服务端启动后,getDataPathConfigs 会读取该 ConfigMap(通过 nodeagent.GetConfigs),并将其解析为 *velerotypes.NodeAgentConfigs。从 pkg/nodeagent/node_agent.go 中的 GetConfigs 实现可以看到解析的硬性约束:
- ConfigMap 的
data不能为空,否则报错data is not available in config map ...; data中只能有一个 key,多于一个 key 会报错more than one keys are found in ConfigMap ...'s data. only expect one;- 值必须是合法的 JSON,否则报 JSON 反序列化错误。
也就是说,用 kubectl create cm --from-file 创建后,ConfigMap 的 data 会形如 { "<json文件名>": "<json内容>" },恰好满足单 key 的要求。单元测试也覆盖了这一解析路径,例如 pkg/nodeagent/node_agent_test.go 中的 TestGetConfigs 使用 {"loadConcurrency":{"globalConfig": 5}} 这样的 JSON 验证解析结果。
生效时机
配置只在 node-agent 服务端启动时读取一次,因此:
- 修改 ConfigMap 后必须重启 node-agent(例如
kubectl rollout restart daemonset/node-agent -n velero,或直接删除对应 node-agent Pod 让其被 DaemonSet 重建),新配置才会生效; - 每个 node-agent Pod 只读取与自己所在节点相关的配置,因此按节点配置天然是分节点生效的。
实现原理:全局数据路径管理器(Global Data Path Manager)
从"每控制器一个管理器"到"全局一个管理器"
在代码实现层面,data path manager 的作用是维护当前正在运行的 VGDP 实例总数,并保证不超过并发上限。在引入本设计之前,每个控制器各自持有一个 data path manager 实例,导致并发数按控制器分别计算,无法在不同请求方(如 PodVolume backup 与 DataUpload)之间统一限制并发。
因此本设计创建了一个全局唯一的 data path manager 实例(server 范围),并在启动时把它传递给各个控制器。该实例在 node-agent 服务端启动时创建。在 pkg/cmd/cli/nodeagent/server.go 中可以看到:
s.dataPathMgr = datapath.NewManager(s.getDataPathConcurrentNum(defaultDataPathConcurrentNum))
即:先通过 getDataPathConcurrentNum 计算出当前节点的并发数(可能来自 per-node 规则,也可能回退到 global 或默认值 1),再以此数值初始化全局唯一的 *datapath.Manager。随后这个 dataPathMgr 被依次传入 PodVolumeBackup、PodVolumeRestore、DataUpload、DataDownload 四个 controller(见 NewPodVolumeBackupReconciler、NewPodVolumeRestoreReconciler、NewDataUploadReconciler、NewDataDownloadReconciler 的调用处),从而保证四个请求方共享同一个并发配额。
Manager 的并发控制实现
datapath.Manager 的核心实现位于 pkg/datapath/manager.go。它通过一个带互斥锁的 map 跟踪所有正在运行的异步数据路径实例:
var ConcurrentLimitExceed error = errors.New("Concurrent number exceeds")
type Manager struct {
cocurrentNum int
trackerLock sync.Mutex
tracker map[string]AsyncBR
}
func NewManager(cocurrentNum int) *Manager {
return &Manager{
cocurrentNum: cocurrentNum,
tracker: map[string]AsyncBR{},
}
}
创建新的数据路径实例前会检查当前运行实例数量是否已达到上限(pkg/datapath/manager.go 中 CreateGenericDataPath):
func (m *Manager) CreateGenericDataPath(jobName string, requestorType string, ctx context.Context, client client.Client, namespace string, callbacks Callbacks, log logrus.FieldLogger) (AsyncBR, error) {
m.trackerLock.Lock()
defer m.trackerLock.Unlock()
if len(m.tracker) >= m.cocurrentNum {
return nil, ConcurrentLimitExceed
}
m.tracker[jobName] = VGDPCreator(jobName, requestorType, client, namespace, callbacks, log)
return m.tracker[jobName], nil
}
当并发实例数达到上限时,创建请求会返回 ConcurrentLimitExceed 错误;请求方(controller)会据此把对应的备份/恢复任务保持为排队/等待状态,而不会立即启动新的 VGDP 实例。与此对应:
RemoveAsyncBR(jobName)在数据路径实例完成(成功或失败)后从 tracker 中移除,释放并发额度;GetAsyncBR(jobName)用于按任务名查询运行中的实例(例如恢复/续跑场景);- 对于微服务(MicroService)模式,
CreateMicroServiceBRWatcher在resume(恢复)场景下不检查并发上限,只有全新创建时才受限制。
设计文档还给出了 Manager 的原型签名(其中 CreateFileSystemBR 是早期版本命名,当前代码中对应方法为 CreateGenericDataPath 与 CreateMicroServiceBRWatcher):
func NewManager(cocurrentNum int) *Manager
func (m *Manager) CreateFileSystemBR(jobName string, requestorType string, ctx context.Context, client client.Client, namespace string, callbacks Callbacks, log logrus.FieldLogger) (AsyncBR, error)
一次配置计算的完整调用链
综合以上源码,当 node-agent 启动时,并发数的计算与落地遵循如下链路:
velero node-agent server解析--node-agent-configmap参数(pkg/cmd/cli/nodeagent/server.go);- 服务端通过
nodeagent.GetConfigs从 Kubernetes API 读取 ConfigMap,反序列化为NodeAgentConfigs(pkg/nodeagent/node_agent.go); getDataPathConcurrentNum根据当前节点标签计算并发数:先取globalConfig(非法则回退到 1),再遍历perNodeConfig规则取命中的最小值,无命中则用全局值(pkg/cmd/cli/nodeagent/server.go);- 用该数值创建全局唯一的
datapath.Manager,并注入四个 controller(pkg/datapath/manager.go); - 控制器每次准备启动 VGDP 实例时调用 Manager 的创建方法,超过配额即返回
ConcurrentLimitExceed,任务保持等待,直到有实例完成释放额度。
实践建议与注意事项
- 从 1 起步,逐步调优:并发数的默认值是 1(无并发)。若节点资源充足,可先观察实际资源占用情况再逐步增大
globalConfig,避免一次性调大导致 OOM 或任务挂起。 - 善用按节点规则做资源隔离:对于运行关键工作负载或资源紧张的节点,用
kubernetes.io/hostname精确锁定节点并设置较小的number;对于规格较高的一批节点,可用实例类型等公共标签批量设置较大并发数。 - 规则冲突取最小值:当节点命中多条
perNodeConfig规则时取最小值,配置多条规则时应预判重叠情况,避免得到意外偏小的并发数。 - 注意恢复优先场景的局限:当前设计不区分备份与恢复的优先级,恢复任务同样受并发配额约束;灾备场景若恢复被备份阻塞,需要人工干预(如先停止备份)。
- 完全阻断某节点的 VGDP 不可行:不要试图通过把
number设为 0 来完全禁止某节点的备份/恢复,因为number <= 0的规则会被跳过、任务 CR 仍会被提交但永不处理;需要更完整的节点禁用能力时,应等待/参考后续围绕 exposer 等模块的扩展设计。 - 多命名空间多实例:如果集群中按命名空间安装了多个 Velero 实例,每个命名空间需要各自的 ConfigMap,且只对该命名空间的 node-agent 生效。
参考与延伸阅读
- 设计文档:node-agent-concurrency.md
- VGDP 概念的来源设计:unified-repo-and-kopia-integration.md(即设计文档中链接的 Unified Repository 设计)
- 配置数据结构定义:pkg/types/node_agent.go
- ConfigMap 读取与校验:pkg/nodeagent/node_agent.go 中的
GetConfigs - node-agent 服务端并发数计算与 Manager 装配:pkg/cmd/cli/nodeagent/server.go 中的
getDataPathConcurrentNum - 并发限额执行引擎:pkg/datapath/manager.go
- 安装时挂接 ConfigMap 参数:pkg/install/daemonset.go 与 pkg/cmd/cli/install/install.go
- 相关测试:pkg/nodeagent/node_agent_test.go(
TestGetConfigs)、pkg/install/daemonset_test.go(--node-agent-configmap参数断言)