Velero node-agent 并发控制设计:VGDP 并发实例的全局与按节点配额机制

原创2026-09-15 14:02:561,755 阅读
文章标签:云原生容器编排灾备存储备份恢复CLI运维高可用

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 启动时,并发数的计算与落地遵循如下链路:

  1. velero node-agent server 解析 --node-agent-configmap 参数(pkg/cmd/cli/nodeagent/server.go);
  2. 服务端通过 nodeagent.GetConfigs 从 Kubernetes API 读取 ConfigMap,反序列化为 NodeAgentConfigs(pkg/nodeagent/node_agent.go);
  3. getDataPathConcurrentNum 根据当前节点标签计算并发数:先取 globalConfig(非法则回退到 1),再遍历 perNodeConfig 规则取命中的最小值,无命中则用全局值(pkg/cmd/cli/nodeagent/server.go);
  4. 用该数值创建全局唯一的 datapath.Manager,并注入四个 controller(pkg/datapath/manager.go);
  5. 控制器每次准备启动 VGDP 实例时调用 Manager 的创建方法,超过配额即返回 ConcurrentLimitExceed,任务保持等待,直到有实例完成释放额度。

实践建议与注意事项

  • 从 1 起步,逐步调优:并发数的默认值是 1(无并发)。若节点资源充足,可先观察实际资源占用情况再逐步增大 globalConfig,避免一次性调大导致 OOM 或任务挂起。
  • 善用按节点规则做资源隔离:对于运行关键工作负载或资源紧张的节点,用 kubernetes.io/hostname 精确锁定节点并设置较小的 number;对于规格较高的一批节点,可用实例类型等公共标签批量设置较大并发数。
  • 规则冲突取最小值:当节点命中多条 perNodeConfig 规则时取最小值,配置多条规则时应预判重叠情况,避免得到意外偏小的并发数。
  • 注意恢复优先场景的局限:当前设计不区分备份与恢复的优先级,恢复任务同样受并发配额约束;灾备场景若恢复被备份阻塞,需要人工干预(如先停止备份)。
  • 完全阻断某节点的 VGDP 不可行:不要试图通过把 number 设为 0 来完全禁止某节点的备份/恢复,因为 number <= 0 的规则会被跳过、任务 CR 仍会被提交但永不处理;需要更完整的节点禁用能力时,应等待/参考后续围绕 exposer 等模块的扩展设计。
  • 多命名空间多实例:如果集群中按命名空间安装了多个 Velero 实例,每个命名空间需要各自的 ConfigMap,且只对该命名空间的 node-agent 生效。

参考与延伸阅读

登录后查看全文
velero