SkyPilot 配置来源与覆盖机制详解从用户配置到 CLI 覆盖的完整优先级体系【免费下载链接】skypilotThe AI Compute Platform for frontier teams. SkyPilot turns fragmented AI compute into one AI supercomputer, so frontier AI teams build custom intelligence faster.项目地址: https://gitcode.com/GitHub_Trending/sk/skypilotSkyPilot 允许通过多种来源设置配置并实现了一套带优先级的合并机制来分层组合它们管理员可以在 API 服务器上定义全局默认值团队可以在项目目录中存放共享默认值而单个任务可以通过 Task YAML 的config字段或 CLI 的--config参数实现按任务覆盖。读完本文你将掌握 SkyPilot 五种配置来源的确切位置与作用域、从低到高的覆盖优先级规则、列表与字典各自的合并语义以及如何用命令行点号键值对dotlist精准覆盖任意深层配置项。上图仓库中同时提供明暗两个版本config-cheatsheet-light.svg与config-cheatsheet-dark.svg直观展示了各配置层的位置与优先级关系下文将逐一展开。配置来源总览五层配置各司其职SkyPilot 的配置可以来自五个不同的来源每一层的作用域由粗到细逐步收窄配置类型配置位置说明Server configurationAPI 服务器上的~/.sky/config.yaml应用于发送到 SkyPilot API 服务器的所有请求User configuration~/.sky/config.yaml应用于本机所有 SkyPilot 调用Project configuration$pwd/.sky.yaml应用于当前目录下的所有 SkyPilot 调用SkyPilot YAMLSkyPilot YAML 文件中的config字段应用于某个特定的 SkyPilot 任务CLI flags使用--configCLI 参数覆盖特定命令的配置所有配置来源都遵循相同的配置语法完整字段定义见 高级配置文档。需要特别注意的是任何新的配置变更都不会影响已经存在的集群——配置在集群创建时被捕获后续修改配置只会作用于新启动的任务。当多个来源同时指定了配置时SkyPilot 会按照后文所述的优先级机制进行合并merge而不是简单丢弃低优先级来源中的其余字段。服务器配置Server Configuration管理员的全局基准如果你使用的是远程 SkyPilot API 服务器部署细节见 SkyPilot API 服务器文档服务器会在其自身实例或容器的~/.sky/config.yaml中查找服务器配置。这份配置由管理员统一维护对通过该 API 服务器发出的所有请求生效是整棵配置合并树的最低优先级基准层。从源码实现看服务器加载路径由_resolve_server_config_path()决定sky/skypilot_config.py优先读取SKYPILOT_GLOBAL_CONFIG环境变量指向的文件否则回退到~/.sky/config.yaml。此外服务器端配置还支持持久化到数据库当配置中包含db连接串时服务器配置会被存入config_yaml数据表键为api_server_config下次启动时从数据库恢复见 sky/skypilot_config.py。如果你使用的是本地 API 服务器即skyCLI 直连本机则不存在独立的服务器配置层请直接使用下面的用户配置来设置全局默认值。用户配置User Configuration全局默认值SkyPilot 客户端会在~/.sky/config.yaml中查找用户配置。这是最常用的全局配置层适用于本机发起的所有 SkyPilot 调用——包括认证、云厂商参数、Kubernetes 集群偏好等。源码中对应的默认路径常量定义在 sky/skypilot_config.py# Path to the client config files. _GLOBAL_CONFIG_PATH ~/.sky/config.yaml _PROJECT_CONFIG_PATH .sky.yaml如果你希望为非默认位置指定用户配置文件可以设置SKYPILOT_GLOBAL_CONFIG环境变量指向目标路径若该路径不存在客户端会直接报错并提示请检查路径或取消该环境变量unset SKYPILOT_GLOBAL_CONFIG这一行为同样由resolve_user_config_path()sky/skypilot_config.py实现。项目配置Project Configuration团队级共享默认值SkyPilot 客户端会在当前工作目录下查找.sky.yaml文件作为项目配置适用于该目录下的所有 SkyPilot 调用。这非常适合在 monorepo 或多租户仓库中存储团队共享的默认值例如统一指定 Kubernetes 的allowed_contexts或云厂商标签避免每个成员各自维护一份全局配置。要指定不同的项目配置文件可通过SKYPILOT_PROJECT_CONFIG环境变量指向所需路径。对应实现位于 sky/skypilot_config.py其查找逻辑与用户配置一致先看SKYPILOT_PROJECT_CONFIG环境变量若未设置则回退到$pwd/.sky.yaml。客户端在启动时会按先用户配置、再项目配置的顺序加载并叠加这两层_reload_config_as_client()见 sky/skypilot_config.py项目配置中出现的字段会覆盖用户配置中的同名字段。SkyPilot YAML 内联配置任务级配置你可以在 SkyPilot YAML 文件的config字段中直接编写内联配置完整 YAML 字段语法见 yaml-spec 文档。该层配置仅作用于该 YAML 定义的具体任务适合随任务一起版本化、可移植的配置项。SkyPilot YAML 内联配置支持以下字段docker.run_optionsnvidia_gpus.disable_ecckubernetes.pod_configkubernetes.provision_timeoutkubernetes.dwskubernetes.kueuegcp.managed_instance_group示例# In your SkyPilot YAML config: docker: run_options: ... kubernetes: pod_config: ... provision_timeout: ... dws: ... kueue: ... gcp: managed_instance_group: ... nvidia_gpus: disable_ecc: ...从源码来看哪些键允许在任务级覆盖由白名单机制严格控制。OVERRIDEABLE_CONFIG_KEYS_IN_TASK定义了完整的可覆盖键集合sky/skylet/constants.py除了文档列出的字段外还包括ssh.pod_config、ssh.provision_timeout、kubernetes.remote_identity、kubernetes.quota、azure.remote_identity、gcp.subnet_names、gcp.placement_policy、slurm.sbatch_options、active_workspace等。任何试图覆盖白名单之外键的配置都会被_recursive_update中的键检查逻辑拒绝见 sky/utils/config_utils.py从而保证任务无法越权修改全局配置。CLI 参数覆盖单条命令的临时配置通过--config标志可以向 CLI 传入配置参数这是优先级最高的一层只对当前执行的命令生效。--config标志有两种用法传入配置文件路径此时只允许一个--config标志传入点号键值对dotlist可以重复使用多个--config来覆盖多个字段。# pass a config file sky launch --config my_config.yaml ... # pass individual config options sky launch --config kubernetes.provision_timeout600 --config kubernetes.pod_config.spec.priorityClassNamehigh-priority ... sky launch --config kubernetes.custom_metadata.annotations.myannotation1myvalue1 --config kubernetes.custom_metadata.annotations.myannotation2myvalue2 ...CLI 层的实现位于 sky/client/cli/flags.pyconfig_option装饰器定义了--config选项multipleTrue即允许重复出现每个值在命令执行前通过回调被送入skypilot_config.apply_cli_config()应用到全局配置上。解析逻辑_compose_cli_config()sky/skypilot_config.py会先判断参数是否为已存在的文件若是文件则走parse_and_validate_config_file()并强制只允许单个--config否则按点号键值对解析。点号键值对的解析由_parse_dotlist()sky/skypilot_config.py实现以第一个分割键值键按.拆分为嵌套键路径值则通过 YAML 安全加载yaml_utils.safe_load解析因此你可以传入数字、布尔值或字符串sky launch --config kubernetes.provision_timeout600 --config kubernetes.pod_config.spec.priorityClassNamehigh-priority --config aws.labels.Ownermy-team另外值得一提的是--workspace/-w参数本质上也是--config active_workspacename的语法糖见 sky/client/cli/flags.py。配置覆盖优先级与合并规则当同一个配置字段在多个来源中都被指定时SkyPilot 按下述优先级从高到低依次覆盖CLI flag最高优先级SkyPilot YAMLProject configurationUser configurationServer configuration最低优先级合并规则如下列表List默认被更高优先级的来源整体覆盖。例外kubernetes.pod_config中 Kubernetes 定义了补丁合并键patch merge key的字段例如containers和volumes按name合并volumeMounts按mountPath合并会按该键逐项合并键与已有项匹配的项会被合并进已有项其余项则被追加到列表末尾。而args、command和imagePullSecrets作为整体被替换因此一个空的imagePullSecrets列表即可清空低优先级来源设置的密钥。剩余的列表字段则被追加到已有列表之后。字典Dict按键逐项合并各个键由高优先级来源覆盖。这段合并语义在源码中有完整实现。merge_k8s_configs()sky/utils/config_utils.py定义了 Kubernetes 配置的合并行为其中_PATCH_MERGE_KEYS常量sky/utils/config_utils.py给出了完整的关键映射表列表字段合并键行为containers/initContainers/ephemeralContainersname按 name 逐项合并volumesname按 name 逐项合并volumeMountsmountPath按 mountPath 逐项合并envname按 name 逐项合并hostAliasesip按 ip 逐项合并portscontainerPort按 containerPort 逐项合并volumeDevicesdevicePath按 devicePath 逐项合并args/command/imagePullSecrets—原子字段整体替换空列表可清空继承值其余列表字段—追加到已有列表此外_validate_mergeable_types()sky/utils/config_utils.py会在合并前校验覆盖值的类型是否与基准值兼容若用标量覆盖字典或列表等不兼容类型会抛出InvalidSkyPilotConfigError避免产生难以排查的静默错误。而显式的null值则用于清空继承的子树——Kubernetes 将 null 字段视为不存在。覆盖示例从两份配置推导最终结果假设用户配置文件~/.sky/config.yaml中配置了kubernetes: allowed_contexts: [context1, context2] provision_timeout: 600 aws: labels: map-migrated: my-value Owner: user-unique-name而项目配置文件$pwd/.sky.yaml中配置了# project config overrides user config kubernetes: allowed_contexts: [context3, context4] provision_timeout: 300 aws: labels: Owner: project-unique-name根据上述合并规则最终合并后的配置为kubernetes: # lists are overridden by config sources with higher priority allowed_contexts: [context3, context4] provision_timeout: 300 aws: # dicts are merged, with individual keys overridden by # config sources with higher priority labels: map-migrated: my-value Owner: project-unique-name分析要点kubernetes.allowed_contexts是列表由更高优先级的项目配置整体覆盖[context1, context2]被[context3, context4]取代kubernetes.provision_timeout被覆盖为300aws.labels是字典按键合并map-migrated保留用户配置中的值Owner被项目配置覆盖为project-unique-name。如果你还想针对单条命令进一步覆盖比如把这次启动的 K8s 上下文限制到context5可以在 CLI 层补充--config kubernetes.allowed_contexts[context5]——CLI 层优先级最高列表将被整体替换。客户端忽略的字段与管理员策略有两类字段需要特别留意以下字段如果由客户端指定会被忽略admin_policyallowed_clouds这背后是SKIPPED_CLIENT_OVERRIDE_KEYS机制sky/skylet/constants.py当客户端配置与服务器配置合并时api_server、allowed_clouds、workspaces、db、daemons、metrics、控制器 consolidation 模式、Slurm 集群身份映射等键一律以服务器端为准客户端的不同取值会被忽略并打印警告。这是出于安全与职责划分的考虑——云供应商白名单和策略审计必须由服务器管理员统一把控。如果你是 SkyPilot API 服务器的管理员可以通过实施**管理员策略admin policy**禁用覆盖或只允许特定字段被覆盖。管理员策略的配置方法详见 管理员策略文档。深入原理客户端配置的加载与分层叠加把上述各层串联起来的核心逻辑是客户端启动时的_reload_config_as_client()sky/skypilot_config.py其执行顺序与配置文档完全对应解析用户配置resolve_user_config_path()→~/.sky/config.yaml或SKYPILOT_GLOBAL_CONFIG解析项目配置_resolve_project_config_path()→$pwd/.sky.yaml或SKYPILOT_PROJECT_CONFIG按优先级依次调用overlay_skypilot_config()将项目配置叠加到用户配置之上通过validate_schema校验最终配置是否符合 配置 schema 定义在 CLI 命令执行时apply_cli_config()再以同样的 overlay 方式把--config的覆盖施加到已加载的配置上sky/skypilot_config.py。叠加的核心是Config.get_nested()与_recursive_update()sky/utils/config_utils.py前者返回深层拷贝并应用覆盖后者递归逐键合并字典、按规则处理列表从而保证任意层的合并都不会污染其他来源的配置对象。对于 Kubernetes 这类支持上下文context区分的云平台配置还支持按上下文/节点池分层的context_configs在读取配置时get_cloud_config_value_from_dict()sky/utils/config_utils.py会优先查找cloud/context_configs/context/keys找不到再回退到云级cloud/keys与全局合并语义保持一致。这与配置来源分层一起构成了 SkyPilot 一处基准、多层覆盖、按需精调的完整配置管理体系。【免费下载链接】skypilotThe AI Compute Platform for frontier teams. SkyPilot turns fragmented AI compute into one AI supercomputer, so frontier AI teams build custom intelligence faster.项目地址: https://gitcode.com/GitHub_Trending/sk/skypilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考