Salt 调度执行模块 salt.modules.schedule 完全指南管理与运维 minion 定时任务【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt导读本文围绕 Saltgh_mirrors/sa/salt中的salt.modules.schedule执行模块展开系统讲解如何通过saltCLI 在 minion 上查看、新增、修改、删除、启停定时任务并结合底层调度器实现说明其工作原理。读者学完后可以熟练使用schedule.*系列命令管理单台或集群中的计划任务并理解调度任务的持久化机制、pillar/opts 两种来源以及事件驱动的工作方式。说明关联文档 doc/ref/modules/all/salt.modules.schedule.rst 是 Sphinx 的automodule自动文档入口其全部技术内容实际来自模块源码 salt/modules/schedule.py 的 docstring 与实现。本文以该模块为主线结合源码与测试展开。一、模块概览与适用前提salt.modules.schedule用于管理 minion 上的 Salt 调度任务Module for managing the Salt schedule on a minion自 Salt 2014.7.0 版本引入。它本质上是管理 Salt 内置调度器scheduler的用户接口真正的调度循环实现在 salt/utils/schedule.py 的Schedule类中而本模块通过向 minion 事件总线event bus发射manage_schedule事件来驱动调度器的增删改查。依赖要求模块 docstring 明确指出要求 minion 上安装 python-dateutil否则when按指定时间执行与range时间段相关能力不可用。源码中通过 try/except 检测依赖salt/modules/schedule.pytry: import dateutil.parser as dateutil_parser _WHEN_SUPPORTED True _RANGE_SUPPORTED True except ImportError: _WHEN_SUPPORTED False _RANGE_SUPPORTED False若要在调度任务中使用cron表达式底层调度器还需要croniter库见 salt/utils/schedule.py 的导入逻辑该依赖缺失时cron选项会报错。代理 minion 支持模块顶部声明__proxyenabled__ [*]意味着该模块可以被所有类型的 proxy minion 加载使用如网络设备代理 minion这是通过代理方式纳管网络设备时同样可以管理定时任务的依据。二、调度任务的两种来源opts 与 pillar调度任务可以来自两个位置理解这一点是正确使用本模块的前提opts配置来源来自 minion 配置文件或minion.d/*.conf中的schedule段以及通过模块命令新增后被持久化的任务。命令执行后默认会持久化到 minion 配置目录下 minion.d 中的_schedule.conf文件该文件由 Salt 自动创建文件名以下划线开头属于 Salt 内部使用文件详见 minion 配置文档。pillar 来源来自 master 下发的 pillar 数据中的schedule段。来自 pillar 的任务不会被持久化到本地_schedule.conf因为其生命周期由 pillar 管理。这一点可以从源码中得到印证模块的delete、modify、enable_job、disable_job、postpone_job、skip_job、move、copy等函数在操作时都会先判断任务属于whereopts还是wherepillar针对 pillar 中的任务会明确设置persist: False例如 salt/modules/schedule.py避免把 pillar 任务写入本地配置文件造成冲突。三、任务字段白名单与通用选项模块顶部定义了调度任务的字段白名单SCHEDULE_CONFsalt/modules/schedule.pylist输出任务时会只保留这些字段其余字段被过滤。完整字段如下字段含义name任务名调度器内部用于识别任务function要执行的执行模块函数如test.ping、state.applyargs/kwargs传给 function 的位置参数列表与关键字参数字典seconds/minutes/hours/days间隔周期可组合使用_seconds为内部归一化后的秒数when指定具体时间点执行依赖 dateutil支持hh:mm或 ISO 格式列表once/once_fmt只执行一次once_fmt指定时间格式默认%Y-%m-%dT%H:%M:%Scroncron 表达式依赖 croniterrange仅在指定时间段内执行依赖 dateutilsplay随机延时间隔可为整数或{start: n, end: m}范围字典maxrunning最大并行运行实例数默认 1enabled任务是否启用默认 Truejid_include是否把任务执行记录到 minion 的 job cache默认 Truereturner结果返回器return_config/return_kwargs返回器的配置选项与参数metadata随任务结果一起返回的元数据run_on_startminion 启动/调度器重启时是否立即执行一次until/after任务生效的截止/起始时间skip_during_range/run_after_skip_range在指定时间段内跳过执行以及跳过结束后是否补跑return_job任务结束后是否发 job 返回事件注意模块别名映射为__func_alias__ {list_: list, reload_: reload}因此 CLI 上使用schedule.list与schedule.reload即可。四、任务生命周期管理增删改查与启停以下命令全部通过salt远程执行目标可以是单个 minion 或一组 minion。1. 查看任务schedule.list列出 minion 上当前所有调度任务# 列出全部任务默认隐藏内部任务、显示禁用任务 salt * schedule.list # 显示所有任务含 Salt 内部以 __ 开头的任务 salt * schedule.list show_allTrue # 隐藏被禁用的任务 salt * schedule.list show_disabledFalse # 仅查看 opts配置来源的任务 salt * schedule.list whereopts # 仅查看 pillar 来源的任务 salt * schedule.list wherepillar实现要点salt/modules/schedule.py默认输出 YAML 格式可通过return_yamlFalse改为返回 Python 字典以__开头的任务属于 Salt 内部自动添加如 mine 更新默认隐藏show_allTrue时显示任务未显式声明enabled时默认视为启用每个任务会附加saved: True/False字段标识该任务是否已持久化到 minion 配置即存在于_schedule.conf支持offlineTrue离线模式不经过事件总线直接从_schedule.conf文件读取minion 未运行时也能查看。2. 新增任务schedule.add# 每 3600 秒执行一次 test.ping salt * schedule.add job1 functiontest.ping seconds3600 # 带参数执行 cmd.run salt * schedule.add job2 functioncmd.run job_args[date /tmp/date.log] seconds60 # 离线模式minion 未运行时直接把任务写入 _schedule.conf salt * schedule.add job1 functiontest.ping seconds3600 offlineTrue常用参数组合示例# 每 5 分钟执行带 1~10 秒随机抖动 salt * schedule.add check_disk functiondisk.usage minutes5 splay{start: 1, end: 10} # 每天 02:30 执行基于 when需 dateutil salt * schedule.add nightly functionstate.apply when02:30am # 按 cron 表达式每周一凌晨执行需 croniter salt * schedule.add weekly functionpkg.upgrade cron0 3 * * 1 # 通过 pillar 下发任务不持久化到本地 salt * schedule.add pillar_job functiontest.ping seconds60 wherepillar关键行为源码 salt/modules/schedule.py时间参数冲突校验seconds/minutes/hours/days不能与when或cron混用when与cron也不能同时使用违反时返回错误信息。job_args必须是 listjob_kwargs必须是 dict否则校验失败。若任务已存在则直接报错already exists。支持testTrue试运行模式只提示would be added而不真正添加。默认persistTrue任务会持久化到_schedule.conf设置为persistFalse则只对当前运行中的调度器生效。3. 修改任务schedule.modify# 修改 job1 的执行周期 salt * schedule.modify job1 functiontest.ping seconds7200 # 离线修改 salt * schedule.modify job1 functiontest.ping seconds7200 offlineTrue实现要点salt/modules/schedule.py目标任务不存在时报错Job X does not exist in schedule.未指定的字段沿用原任务值function缺省时自动取原值比较新旧任务内容若完全一致则返回Job X in correct state幂等变更时会先在返回结果的changes中记录old与new两份任务定义支持testTrue试运行以及offlineTrue离线写文件。4. 删除任务schedule.delete 与 schedule.purge# 删除单个任务 salt * schedule.delete job1 # 删除全部用户任务跳过以 __ 开头的内部任务与全局 enabled 标志 salt * schedule.purge # 离线删除 salt * schedule.delete job1 offlineTruedelete只针对单个任务来自 pillar 的任务删除时不会持久化salt/modules/schedule.pypurge遍历所有非内部任务逐个删除同样支持test与offline模式salt/modules/schedule.py离线模式下删除操作在全部完成后一次性把新的调度配置写回_schedule.conf。5. 启停任务enable / disable / enable_job / disable_job# 启用/禁用某个任务 salt * schedule.enable_job job1 salt * schedule.disable_job job1 # 启用/禁用 minion 上全部任务全局开关对应 schedule 中的 enabled 标志 salt * schedule.enable salt * schedule.disableenable_job/disable_job针对单个任务操作后校验任务状态是否符合预期salt/modules/schedule.pyenable/disable操作的是全局enabled开关disable后整个调度器暂停salt/modules/schedule.py均有testTrue试运行与persist持久化参数。6. 立即执行任务schedule.run_job# 立即触发一次 job1 salt * schedule.run_job job1 # 任务被禁用时强制触发 salt * schedule.run_job job1 forceTrue实现要点salt/modules/schedule.py若任务存在且未禁用则通过事件总线发射run_job指令让调度器立即执行一次禁用状态下不带forceTrue会返回Job X is disabled.。7. 持久化与重载schedule.save 与 schedule.reload# 把当前调度任务非 pillar 部分保存到 _schedule.conf salt * schedule.save # 从 _schedule.conf 与 pillar 重新加载调度任务 salt * schedule.reloadsave通过事件总线请求调度器把非 pillar 任务落盘salt/modules/schedule.pyreload会先触发pillar_refresh刷新 pillar 中的 schedule再读取config_dir/minion.d/schedule.conf注意这里读取的是schedule.conf与模块命令持久化使用的_schedule.conf是不同文件前者是用户在 minion.d 下手写的配置将其中内容重新加载到运行中的调度器salt/modules/schedule.py。五、跨 minion 分发schedule.move 与 schedule.copy# 把 job1 迁移到 web1 minion原 minion 上删除 salt * schedule.move job1 web1 # 把 job1 复制到 web1 minion原任务保留 salt * schedule.copy job1 web1 # 支持复合目标 salt * schedule.copy job1 web*实现要点salt/modules/schedule.py这两个函数读取任务定义后把每个字段拼装为keyvalue形式的参数列表通过__salt__publish.publish在目标 minion 上重新执行schedule.add。move在全部目标成功返回后才在原 minion 上delete若有 minion 返回 False则返回失败的 minion 列表并中止。返回结果中minions字段给出实际应答的 minion 列表。六、时间控制postpone_job / skip_job / show_next_fire_time / job_status这三个功能自 Salt 2018.3.0 加入用于对一次性/周期性任务做精确时间控制。postpone_job推迟任务# 把原计划在 2026-09-24T03:00:00 触发的任务推迟到 03:30:00 salt * schedule.postpone_job job1 2026-09-24T03:00:00 2026-09-24T03:30:00 # 自定义时间格式 salt * schedule.postpone_job job1 2026-09-24 03:00:00 2026-09-24 03:30:00 time_fmt%Y-%m-%d %H:%M:%S实现要点salt/modules/schedule.pycurrent_time与new_time均需符合time_fmt默认%Y-%m-%dT%H:%M:%S源码用datetime.datetime.strptime严格校验格式解析失败返回Date string could not be parsed.。skip_job跳过任务# 跳过 job1 在 2026-09-24T03:00:00 的这次触发 salt * schedule.skip_job job1 2026-09-24T03:00:00实现要点salt/modules/schedule.py与postpone_job类似在指定时间点跳过任务执行同样支持time_fmt自定义格式。show_next_fire_time查看下次触发时间salt * schedule.show_next_fire_time job1实现要点salt/modules/schedule.py通过事件总线向调度器请求get_next_fire_time返回next_fire_time字段方便排查任务是否按预期排期。job_status查看任务运行信息salt * schedule.job_status job1实现要点salt/modules/schedule.py请求调度器返回指定任务最近一次运行的状态信息含data字段源码会把其中的datetime对象统一格式化为字符串再返回便于直接展示。is_enabled查询启用状态# 查询单个任务是否启用 salt * schedule.is_enabled namejob1 # 不带 name 时返回调度器全局 enabled 状态自 2015.5.3 加入 salt * schedule.is_enabled七、底层原理事件总线驱动调度器理解salt.modules.schedule的机制关键在于它并不是直接操作调度数据结构而是通过minion 事件总线与调度器通信模块函数如add调用__salt__event.fire在本地事件总线上发射manage_schedule事件payload 中携带funcadd/delete/modify/enable/disable/run_job/save_schedule/reload 等与任务数据minion 的调度器监听该事件并执行对应操作操作完成后调度器在事件总线上回发对应的完成事件如minion_schedule_add_complete、minion_schedule_delete_complete、minion_schedule_list_complete等模块函数用event_bus.get_event(tag..., wait30)等待完成事件并校验complete字段据此组装result/comment/changes返回给调用方。例如list的实现salt/modules/schedule.py先发{func: list, where: where}再等待minion_schedule_list_complete事件取回完整调度表。若事件模块不可用如某些极简环境函数会捕获KeyError并返回Event module not available的提示而非崩溃。真正的调度循环位于 salt/utils/schedule.py 的Schedule类约 1979 行它负责按seconds/minutes/hours/days、when、cron、once等规则计算下次触发时间、在skip_during_range时段跳过、应用splay随机延迟、受maxrunning限制并发、并把执行结果按returner配置返回。模块中的SCHEDULE_CONF白名单与调度器的字段约定保持一致确保经模块管理的任务能被调度器正确解析。八、离线模式与持久化文件模块中多数写操作add/delete/modify/purge支持offlineTrue用于minion 未运行时直接编辑调度配置文件配置文件路径由_get_schedule_config_file()计算salt/modules/schedule.py取__opts__[conf_dir]无则取 minion 配置所在目录拼上default_include的目录默认minion.d最终指向minion.d/_schedule.conf离线模式下跳过事件总线直接以 YAML 形式读写该文件写入内容形如{schedule: {...}}写入失败会记录错误日志但不会中断捕获OSError正常在线模式下persistTrue时调度器自身也会在完成事件后把非 pillar 任务写入同一文件。因此查看任务时返回的saved字段正是以该任务是否出现在_schedule.conf中为依据salt/modules/schedule.py。minion 配置文档也明确提示minion.d目录中以下划线开头的文件典型如_schedule.conf是 Salt 自行创建的内部文件见 minion 配置文档。九、测试与验证仓库中为schedule模块提供了较完整的单元测试tests/pytests/unit/modules/test_schedule.py覆盖了test_add、test_delete、test_modify、test_purge增删改与清空的参数解析与事件交互test_build_schedule_item、test_build_schedule_item_invalid_when、test_build_schedule_item_invalid_jobs_args、test_build_schedule_item_jid_include任务字段构建及非法when、非 list 的job_args等校验逻辑test_enable_job、test_disable_job、test_enable、test_disable任务级与全局启停test_move、test_copy跨 minion 分发的 publish 交互test_is_enabled、test_job_status、test_list及全局 enabled 相关用例。此外状态模块 salt/states/schedule.py 提供了声明式的schedule.present/schedule.absent状态可在 state 文件SLS中描述任务期望状态由状态系统自动调用本执行模块完成收敛适合把定时任务纳入版本管理相关单测见 tests/pytests/unit/states/test_schedule.py。十、最佳实践小结任务尽量来自 pillar 或 state用schedule.present状态或 pillar 统一管理任务避免在多台 minion 上手工schedule.add造成配置漂移手工添加的任务需确认persistTrue才能跨重启保留。善用测试模式schedule.add/modify/delete/purge均支持testTrue先试运行确认变更内容再真正执行。留意依赖when/range需要 python-dateutilcron需要 croniter缺依赖时任务会直接校验失败并给出明确报错。区分全局与任务级启停schedule.disable会暂停整个调度器schedule.disable_job只停单个任务排障时先用schedule.list show_allTrue观察enabled与saved字段。跨机分发先小范围验证move会在目标全部成功后删除源任务建议先在测试目标上copy验证再执行move。【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考