CubeSandbox CubeMaster 调度器配置完全指南：节点选择、评分因子与故障排查

CubeSandbox CubeMaster 调度器配置完全指南节点选择、评分因子与故障排查【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox本篇技术指南以 CubeSandbox 的 cubemaster-scheduler-config.md 为骨架系统讲解 CubeMaster 调度器配置的存放位置、节点选择四步流程、评分因子语义、Cubelet 上报元数据对调度的影响以及 one-click 与 Terraform 部署变量到调度行为的映射。读完本文你将能够为单机或多节点集群正确配置scheduler段、读懂调度日志定位无可用资源 / 模板不可用 / 流量集中等常见问题并在扩容计算节点后正确执行模板重做template redo。如果只是需要基础的多节点评分配置可先参考 多节点集群部署。本文面向需要完整参考的场景调度失败、资源耗尽、节点标签不匹配、模板本地性template locality问题以及扩容后模板同步。一、调度器配置存放位置CubeMaster 的调度器配置保存在 CubeMaster 自身的conf.yaml中。不同部署方式下配置文件的落盘位置和应用方式如下表部署方式配置位置生效方式one-click / systemd/usr/local/services/cubetoolbox/CubeMaster/conf.yaml重启cube-sandbox-cubemaster.service源码配置模板configs/single-node/cubemaster.yaml重新构建 bundle或将其拷贝到运行环境腾讯云 Terraform / TKEdeploy/one-click/terraform/tencentcloud/tke-addons.tfkubernetes_secret.cubemaster_conf更新 Terraform 生成的yamlencode配置后重新apply并重启或滚动 cube-master PodKubernetes / Helm chartdeploy/kubernetes/chart/files/cube-master/conf.yaml由 deploy/kubernetes/chart/templates/master-config-secret.yaml 渲染更新 chart 文件或渲染出的 Secret并重启或滚动 cube-master Pod以仓库内置的单节点模板为例其scheduler段默认配置为见 configs/single-node/cubemaster.yamlscheduler: priority_select_num: 1 metric_update_timeout: 300s local_metric_update_timeout: 300s filter: enable_filters: - cpu - mem - template_locality - realtime_create_num可以看到仓库默认模板只开启了过滤filter没有开启评分score——这正是文档所说不加评分时新沙箱会集中到第一个可用节点的原因也是多节点部署时需要合并评分配置的起点。二、Cubelet 节点元数据与配额配置节点侧的元数据与配额不在 CubeMaster 中配置。每个 Cubelet 将节点状态上报给 CubeOps端口 3010CubeMaster 再从 CubeOps 同步节点视图。one-click 部署中主要输入为配置位置说明Cubelet 静态配置/usr/local/services/cubetoolbox/Cubelet/config/config.toml含node_status_update_frequency修改后需重启 CubeletCubelet 动态配置/usr/local/services/cubetoolbox/Cubelet/dynamicconf/conf.yaml含host.scheduler_label与host.quota修改后需重启 Cubeletnode_status_update_frequency属于静态配置。仓库中的 Cubelet/config/config.toml 明确注释了这一点[plugins.io.cubelet.internal.v1.cubelet] # Static-only cadence for node status and resource reporting. # Do not configure this in dynamicconf/conf.yaml. node_status_update_frequency 1s即默认上报间隔为1s且不得放入 dynamicconf。文档对这点给出了强约束不要把它放进动态配置。常见的 Cubelet 动态配置如下host: scheduler_label: default-cluster quota: mcpu_limit: 0 mem_limit: mvm_limit: 0 creation_concurrent_num: 0需要注意0或空值通常表示 Cubelet 从宿主机资源推导默认值并不代表无上限。在压测或大型集群中应显式审查 CPU、内存、MVM 数量和创建并发数限制。三、CubeMaster 如何选择计算节点四步流程对每个沙箱创建请求调度大体按以下四步进行解析请求约束读取instance_type、模板 ID、资源需求、显式 host IP、节点亲和/注解等约束过滤节点剔除不健康节点、指标陈旧节点、达到 MVM 上限的节点、无本地模板副本的节点、实时/本地创建数过多的节点、不满足亲和性的节点当磁盘过滤或 backoff 路径激活时还会剔除磁盘占用过高的节点评分节点对剩余候选节点评分例如按权重综合mvm_num、local_create_num、quota_cpu_usage、quota_mem_usage最终选择从得分最高的候选集合中选出最终节点。priority_select_num控制进入最终随机选择的名次范围least_select_name默认为random。这套流程在源码中有非常直接的对应。核心入口是 CubeMaster/pkg/scheduler/schedule.go 中的Select函数func Select(selCtx *selctx.SelectorCtx) (nodes *node.Node, err error) { ... if err : runPreFilter(selCtx); err ! nil { ... } // 预过滤 if err : runFilter(selCtx, scheduler.filter); err ! nil { ... } // 过滤 if err : runScoreFilter(selCtx, scheduler.score); err ! nil { ... } // 评分 return selCtx.LeastRandomSelect(config.GetConfig().Scheduler.PrioritySelectNum), nil // 最终选择 }几个值得注意的源码细节过滤是并行执行的parallelRunFilters使用errgroup并发运行所有启用的过滤器只有全部过滤器都通过的节点才会保留见 schedule.go评分会按插件权重归一化runScoreFilter中每个插件的得分乘以其weight最后除以所有参与插件的总权重totalPluginWeight再按得分排序见 schedule.go最终选择是加权随机LeastRandomSelect(n)取排序后前n个节点以节点得分为权重int(leastNodes[i].Score*1e6)做加权随机抽取见 CubeMaster/pkg/scheduler/selctx/selectcontext.go。当resultWithScore为空即未启用评分时退化为等概率随机或按过滤后的顺序选取least_select_name默认为random在 selectcontext.go 的New中默认分支构造的是randomSelect。文档特别强调没有评分时CubeMaster 仍然会过滤节点但可能从过滤后的顺序中选择这会导致新沙箱集中在第一个可用节点上直到资源过滤器把流量推走。另外调度失败时存在backoff 路径runPreFilter或runFilter失败后会尝试runBackoffFilter/BackoffSelect随机选择一个 backoff 候选。值得注意的是当请求带template_id且启用了template_locality过滤器时shouldSkipBackoffForTemplate会跳过 backoff见 schedule.go避免绕过模板本地性约束。四、关键调度字段详解以下评分字段需要合并进cubemaster.yaml已有的scheduler段。保留你现有的 filter、超时和 instance-type 相关设置除非你有意替换scheduler: # 保留已有的 filter、超时及其他调度设置。 priority_select_num: 3 score: enable_scorers: - real_time_weighted_average resource_weights: mvm_num: 2 local_create_num: 3 quota_cpu_usage: 1 quota_mem_usage: 1 plugin_conf: real_time_weighted_average: weight: 1.0 enable_weight_factors: - mvm_num - local_create_num - quota_cpu_usage - quota_mem_usage各字段含义字段作用priority_select_num从得分最高的前 N 个节点中做最终选择。多节点集群应大于1小集群从3起步较合适metric_update_timeout超过该时长即视为资源指标陈旧。该值应远大于Cubelet 上报间隔local_metric_update_timeout预留的本地指标超时字段。当前 prefilter 逻辑对全局与本地指标统一用metric_update_timeout判断新鲜度filter.enable_filters启用调度过滤器。常见过滤器包括 CPU、内存、模板本地性、实时创建并发数score.enable_scorers启用评分插件。多节点部署通常启用real_time_weighted_average启用后必须配置对应的score.plugin_conf.real_time_weighted_average块否则 CubeMaster 在调度器启动时可能 panicscore.resource_weights控制 MVM 数量、创建并发、CPU 配额使用率、内存配额使用率的影响权重。权重越高影响越大因子也必须同时列在score.plugin_conf.real_time_weighted_average.enable_weight_factors中node_max_mvm_num/node_max_mvm_num_conf全局或按 instance type 的单节点 MVM 上限。Cubelet 上报的max_mvm_num也参与有效上限的计算disk_usage_max_percentdisk过滤器与 backoff 路径使用的磁盘阈值避免把新沙箱放到接近写满的机器affinityconf/node_affinity_selector_allowed_keys按集群标签、可用区、CPU 类型、instance type 等允许的 selector key 控制亲和性与约束4.1 为什么real_time_weighted_average必须配套plugin_conf这在源码中可以直接验证。NewRealTimeWeightedAverageScore在RealTimeWeightedAverage配置为nil时会直接 panic见 CubeMaster/pkg/selector/score/realtimescore.gofunc NewRealTimeWeightedAverageScore() *realTimeWeightedAverageScore { if config.GetConfig().Scheduler.Score.ScorePluginConf.RealTimeWeightedAverage nil { panic(config.Scheduler.Score.ScorePluginConf.RealTimeWeightedAverage is nil) } ... }这解释了文档中启用real_time_weighted_average时必须提供配套plugin_conf块的警告来源。4.2 已注册的过滤器清单从源码注册表可以看到当前可用的过滤器见 CubeMaster/pkg/selector/filter/init.govar filters map[string]interface{}{ cpu: NewCpuFilter, mem: NewMemFilter, template_locality: NewTemplateLocalityFilter, realtime_create_num: NewRealtimecreatelimit, disk: NewDiskFilter, thirtparty: NewThirtpartyFilter, }filter.enable_filters中列出的名字会逐一映射到这些构造函数。4.3 评分因子的底层计算方式评分因子的具体实现位于 CubeMaster/pkg/selector/score/utils.goenable_weight_factors可识别的因子包括create_concurrent_limit、mvm_num、metric_update、local_metric_update、quota_cpu、quota_mem、cpu_util、mem_usage、cpu_load_usage、real_time_create_num、local_create_num、data_disk_usage、storage_disk_usage、sys_disk_usage。其中与文档示例直接相关的是mvm_num100 - (mvm_num / max_mvm_limit) * 100MVM 使用率越低得分越高local_create_num100 - (local_create_concurrent_limit × healthy_master_nodes / create_concurrent_num) * 100本地创建并发越低得分越高quota_cpu_usage/quota_mem_usage100 - (有效已分配配额 / 配额上限) * 100配额占用越低得分越高。所有因子都以剩余越多、得分越高的方式归一化到 0~100 区间再由resource_weights加权求和。五、节点元数据如何影响调度Cubelet 注册节点后通过 CubeOps 的/internal/v1/node-agent接口持续上报状态。CubeOps 将元数据持久化到 MySQL/RedisCubeMaster 每隔数秒从 CubeOps 同步节点视图并在本地缓存快照用于调度。Cubelet 上报字段来源调度影响instance_typeCubelet 节点身份/实例类型匹配请求的instance_type、选择模板副本、应用类型相关的 MVM 设置cluster_labelhost.scheduler_label用于集群标签亲和性与节点池隔离quota_cpuhost.quota.mcpu_limit或由宿主机资源推导CPU 过滤与评分使用的可调度 CPU 容量quota_mem_mbhost.quota.mem_limit或由宿主机资源推导内存过滤与评分使用的可调度内存容量max_mvm_numhost.quota.mvm_limit或按内存推导的默认值单节点 MVM 上限达到上限的节点会被过滤掉create_concurrent_numhost.quota.creation_concurrent_num上报的每节点创建并发数。0表示 Cubelet 不额外设置引擎流控但 CubeMaster 调度层仍会回退到cubelet_conf.create_concurrent_limitallocated / 磁盘使用率 / cgroup 指标Cubelet 周期性上报用于当前资源使用量、磁盘水位与评分因子这些值按计算节点逐一配置并上报。异构集群可以在不同节点上使用不同的 instance type、标签、配额和创建并发限制。关于0回退到cubelet_conf.create_concurrent_limit仓库默认值为create_concurrent_limit: 100见 configs/single-node/cubemaster.yaml。排查并发瓶颈时应先确认该字段的实际生效值。5.1 模板本地性过滤的实现template_locality过滤器是调度中一个关键的硬约束。其实现见 CubeMaster/pkg/selector/filter/template_locality.go做了两件事检查请求模板是否在该节点的模板作用域内TemplateNodeScope可按节点 ID 或 Host IP 匹配检查localcache.GetImageStateByNode(templateID, nodeID)是否为非空即该节点上是否存在可用的本地模板副本若请求要求强制快照存储还会校验快照存储是否允许写入。这意味着即使节点健康、资源充足只要本地没有模板副本创建请求也不会落到该节点上。这是理解扩容后创建仍集中在旧节点问题的关键。六、部署变量映射6.1 one-click 多节点变量/配置效果ONE_CLICK_DEPLOY_ROLEcompute安装计算节点运行 Cubelet/运行时服务并注册到控制面CUBE_SANDBOX_NODE_IP该节点注册的可路由地址。配置错误会导致节点不可达或不可见ONE_CLICK_CONTROL_PLANE_IP/ONE_CLICK_CONTROL_PLANE_CUBEOPS_ADDRCubelet 注册与上报使用的 CubeOps 端点端口 3010。CubeMaster 独立监听 8089node_status_update_frequencyCubelet/config/config.toml节点状态/资源上报间隔默认1s不要放进动态配置host.scheduler_labelCubelet/dynamicconf/conf.yaml亲和与隔离使用的节点池标签host.quota.*Cubelet/dynamicconf/conf.yamlCPU、内存、MVM 数量与创建并发调度容量6.2 腾讯云 Terraform / TKE变量效果TENCENTCLOUD_COMPUTE_NODE_COUNTPVM 计算节点数量直接控制承载沙箱的节点池规模TENCENTCLOUD_COMPUTE_INSTANCE_TYPE默认计算节点实例类型影响真实 CPU/内存以及 Cubelet 推导的配额TF_VAR_compute_instance_types异构计算池的按节点实例类型TENCENTCLOUD_COMPUTE_DATA_DISK_SIZE/data/cubelet的数据盘大小影响模板、快照与运行时数据容量TENCENTCLOUD_CUBELET_NODE_STATUS_UPDATE_FREQUENCY写入每个计算节点的 Cubelet 静态配置控制节点状态/资源上报节奏TENCENTCLOUD_TKE_NODE_COUNT/TENCENTCLOUD_TKE_WORKER_INSTANCE_TYPE控制面 Pod 资源。它们不直接承载沙箱但影响 cube-master、cube-api、cube-proxy 及整体控制面吞吐务必注意TENCENTCLOUD_COMPUTE_NODE_COUNT与TENCENTCLOUD_TKE_NODE_COUNT是两套独立资源——前者运行 Cubelet 并承载沙箱后者运行控制面 Pod。七、推荐配置7.1 小型测试集群适用于 POC、功能验证和低并发场景。这是一个完整的新建小集群起点已包含仓库自带的超时/过滤默认值如果是更新既有部署请以合并方式修改而不是盲目整体替换无关的调度设置scheduler: priority_select_num: 3 metric_update_timeout: 300s local_metric_update_timeout: 300s filter: enable_filters: - cpu - mem - template_locality - realtime_create_num score: enable_scorers: - real_time_weighted_average resource_weights: mvm_num: 2 local_create_num: 3 quota_cpu_usage: 1 quota_mem_usage: 1 plugin_conf: real_time_weighted_average: weight: 1.0 enable_weight_factors: - mvm_num - local_create_num - quota_cpu_usage - quota_mem_usage建议至少使用2 个计算节点以便验证节点选择与故障隔离priority_select_num: 3起步若集群不足 3 个计算节点将其设置为节点数保持 Cubelet 默认1s上报、CubeMaster 指标超时300s默认推导的host.quota可用于基础验证但压测前必须检查其实际值。7.2 更大的生产级集群面向高并发或长期运行环境为每个节点池设置明确的host.scheduler_label例如 general、memory-heavy、load-test 池按instance_type配置node_max_mvm_num_conf避免大小节点共用一个上限将priority_select_num提高到健康计算节点数的较小比例但避免最终选择完全随机化保持template_locality过滤器开启确保创建只落到有可用模板副本的节点显式设置host.quota.creation_concurrent_num避免镜像、磁盘或 VMM 突发工作压垮单节点同步扩展控制面提高TENCENTCLOUD_TKE_NODE_COUNT及相关控制面副本数避免 CubeMaster 或 cube-api 成为瓶颈。八、扩容后模板重做template redo节点注册成功 ≠ 所有模板在该节点可用。template_locality过滤器要求目标节点上有可用的本地模板副本因此新增节点后创建可能失败或继续只落到旧节点直到模板完成同步。对镜像构建的模板扩容后应执行模板重做cubemastercli tpl redo \ --template-id tpl-id \ --node node-ip要点--node接受节点 ID 或 host IP多个节点可重复传入redo默认等待完成使用--detach提交后立即退出使用--failed-only只重做失败的节点等待 redo 任务完成后再从该模板在新节点创建沙箱。推荐的扩容流程安装计算节点确认其出现在 CubeMaster 节点列表中确认节点健康、Cubelet 资源上报新鲜对需要运行在新节点的模板执行cubemastercli tpl redo --template-id tpl-id --node node-ip等待 redo 任务成功后再开放流量或运行 E2E 测试。九、故障排查9.1 调度失败或无更多资源检查quota_cpu/quota_mem_mb是否低于请求资源host.quota.mcpu_limit、host.quota.mem_limit、host.quota.mvm_limit是否仍是较低的推导默认值mvm_num是否达到max_mvm_num或node_max_mvm_num_conf生效的创建并发限制是否阻塞了节点。注意create_concurrent_num: 0仍会在调度层回退到 CubeMaster 的cubelet_conf.create_concurrent_limit。常用排查入口curl http://127.0.0.1:3010/internal/v1/nodes sudo tail -F /data/log/CubeMaster/cubemaster-req.log sudo tail -F /data/log/Cubelet/Cubelet-req.log9.2 节点状态或资源上报陈旧如果 CubeMaster 日志提到指标更新超时确认计算节点上cube-sandbox-cubelet.service在运行确认ONE_CLICK_CONTROL_PLANE_CUBEOPS_ADDR或 Terraform 生成的 CubeOps 端点从计算节点可达检查node_status_update_frequency是否被意外调得过高确保metric_update_timeout远大于上报间隔。补充说明CubeMaster 的 Redis 侧为节点指标键设置了安全 TTL默认 600 秒见 configs/single-node/cubemaster.yaml每次心跳刷新离线节点自动过期——如果上报停滞陈旧节点会被过滤或自动清理。9.3 模板不可用典型症状扩容后新沙箱仍只落在旧节点或日志提示本地模板副本不可用。处理确认请求的template_id对新节点执行cubemastercli tpl redo --template-id tpl-id --node node-ip检查模板任务状态确认 redo 成功保持template_locality过滤器开启不要用关闭过滤器的方式绕过问题。9.4 节点标签不匹配如果请求使用了节点亲和、集群标签或指定 instance type但没有任何候选节点剩余检查 Cubelethost.scheduler_label是否与请求或affinityconf匹配检查instance_type是否与模板和请求匹配检查node_affinity_selector_allowed_keys是否允许请求使用的 selector key异构节点池场景下确认模板副本已重做到目标标签/实例类型池。亲和性选择器支持的操作符包括In、NotIn、Exists、DoesNotExist、Gt、Lt见 CubeMaster/pkg/scheduler/affinity/types.go。9.5 创建集中在少数节点多节点集群中新沙箱仍集中在一台机器上时确认score.enable_scorers已启用启用real_time_weighted_average时确认score.plugin_conf.real_time_weighted_average.enable_weight_factors包含预期因子将priority_select_num设为大于1检查local_create_num、mvm_num、quota_cpu_usage、quota_mem_usage的权重是否已配置确认模板在所有目标节点可用否则template_locality会缩小候选集。十、相关文档多节点集群部署腾讯云集群部署Terraform服务管理与日志模板故障排查【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考