Salt Beacon 状态管理完全指南用 beacon.present / absent / enabled / disabled 声明式管理 Minion 信标【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt导读本文聚焦 Salt 配置管理体系中一个面向运行态的声明式管理能力beacon 状态state模块。在 Salt 中beacon 是常驻 minion 进程内部、按固定周期如每 5 秒探测系统状态并主动向事件总线发布事件的机制常用于文件变更监听、进程存活检测、系统负载监控等场景。而 salt/states/beacon.py 提供的beacon.present、beacon.absent、beacon.enabled、beacon.disabled四个状态函数则让你可以把某台 minion 上应配置哪些 beacon、每个 beacon 的触发参数是什么、是否启用写成幂等的 SLS 状态文件随状态运行自动创建、修改、删除或启停信标无需手工编辑 minion 的beacons.conf。读完本文你将掌握beacon 状态的完整参数与用法、每个状态函数与底层执行模块salt.modules.beacons的调用关系、save/test模式的行为差异、多副本 beaconbeacon_module配置技巧以及如何结合disable_during_state_run与 reactor 避免信标—状态运行互相触发的事件循环。一、beacon 状态模块是什么声明式管理运行期信标1.1 从一个最小示例开始beacon.present是最常用的信标状态它确保某个名为name的 beacon 以你指定的配置存在于 minion 上。官方文档给出如下经典示例salt/states/beacon.pyps: beacon.present: - save: True - enable: False - services: salt-master: running apache2: stopped这段 SLS 的含义是在目标 minion 上配置一个名为ps的信标它监听进程服务状态salt-master处于running、apache2处于stopped初始不启用enable: False并且配置落盘保存到beacons.confsave: True。值得注意的是beacon.present的当前状态判定完全依赖底层执行模块对 minion 当前信标配置的实时读取状态函数会先调用beacons.listreturn_yamlFalse取得当前已配置的信标集合再把 SLS 中传入的kwargs组装成配置数据与现状比对从而实现幂等。1.2 状态模块与执行模块的分工与 Salt 中大多数状态/执行模块的状态层负责声明与幂等、执行层负责实际操作分工一致状态层salt/states/beacon.py 中的present/absent/enabled/disabled负责比对、判定与编排最终通过__salt__[...]调用执行模块。执行层salt/modules/beacons.py 提供list、add、modify、delete、save、enable、disable、enable_beacon、disable_beacon、list_available等函数并通过 minion 内部的事件总线tag 为manage_beacons与 minion 守护进程通信完成真正的增删改查与持久化。状态层引用的底层函数映射如下状态函数底层执行函数触发条件beacon.presentbeacons.listbeacons.add/beacons.modify/beacons.savebeacon 不存在时add存在但配置不同时modifysaveTrue时savebeacon.absentbeacons.listbeacons.delete/beacons.savebeacon 存在时deletesaveTrue时savebeacon.enabledbeacons.listbeacons.enable_beaconbeacon 存在时启用beacon.disabledbeacons.listbeacons.disable_beaconbeacon 存在时禁用该模块自 2015.8.0 版本加入见 salt/states/beacon.py 与 salt/modules/beacons.py 的versionadded标记并随版本演进持续增强——例如 3000 版本开始支持用beacon_module参数在同一 minion 上配置同一类型信标的多个副本。二、beacon.present确保信标存在且配置正确2.1 函数签名与参数def present(name, saveFalse, **kwargs):name要确保配置的信标名称即 SLS 中的 ID如上例的ps。save布尔值默认False。为True时除内存中生效外还会把当前全部信标配置写入 minion 的beacons.conf文件由执行模块beacons.save完成。**kwargs信标自身的配置数据例如services、averages、files、mask、interval、enable、beacon_module、disable_during_state_run等。状态函数会将kwargs转换为[{key: value}, ...]形式的列表并整体交给执行模块。2.2 执行逻辑对照源码从 salt/states/beacon.py 的present实现可以看到完整判定流程调用beacons.list(return_yamlFalse, **kwargs)获取 minion 当前所有信标配置将kwargs组装为beacon_data [{k: v} for k, v in kwargs.items()]beacon 已存在且配置完全一致返回 Job {name} in correct stateresultTrue无变更——这是幂等路径beacon 已存在但配置不同调用beacons.modify(name, beacon_data)更新配置若执行模块返回resultFalse则整体失败否则记录 Modifying {name} in beaconsbeacon 不存在调用beacons.add(name, beacon_data)新增失败则整体失败saveTrue时调用beacons.save()将配置落盘并追加 Beacon {name} saved 注释。这里有一个重要的实现细节由于beacons.modify与beacons.add内部会做配置有效性校验详见下文执行模块部分状态层把执行层的result逐级透传——只要底层校验失败状态立即返回resultFalse与失败原因不会留下半配置状态。2.3 完整参数示例present支持任意信标类型的配置参数。下面是文档中完整的三个示例salt/states/beacon.py示例一ps进程监听ps: beacon.present: - save: True - enable: False - services: salt-master: running apache2: stopped示例二shshell 命令无额外配置sh: beacon.present: []注意当信标不需要任何配置项时直接在 ID 下写空列表[]即可效果等同- name: sh且不带任何 kwargs。示例三load系统负载监听load: beacon.present: - averages: 1m: - 0.0 - 2.0 5m: - 0.0 - 1.5 15m: - 0.1 - 1.0该配置定义了一个负载信标当 1 分钟平均负载落入[0.0, 2.0]区间、5 分钟平均负载落入[0.0, 1.5]、15 分钟平均负载落入[0.1, 1.0]时触发事件。负载区间以列表形式给出上下界。2.4 多副本信标beacon_moduleversionadded 3000从 3000 版本开始同一类型信标可以在一个 minion 上配置多份副本通过beacon_module指定实际使用的 beacon 实现salt/states/beacon.py。这在需要对多个不同文件各自独立做 inotify 监听、且各自有不同的触发与保存策略时非常有用inotify_infs: beacon.present: - save: True - enable: True - files: /etc/infs.conf: mask: - create - delete - modify recurse: True auto_add: True - interval: 10 - beacon_module: inotify - disable_during_state_run: True inotify_ntp: beacon.present: - save: True - enable: True - files: /etc/ntp.conf: mask: - create - delete - modify recurse: True auto_add: True - interval: 10 - beacon_module: inotify - disable_during_state_run: True这里两个信标名inotify_infs、inotify_ntp都映射到inotify实现各自监听不同的文件、都使用interval: 10每 10 秒探测一次与disable_during_state_run: True。底层执行模块在beacons.add中会先检查beacon_data中是否含有beacon_module键若有则用其值去beacons.list_available中校验该 beacon 类型是否可用见 salt/modules/beacons.py确保不会配置出不存在的信标类型。三、beacon.absent确保信标不存在def absent(name, saveFalse, **kwargs):beacon.absent用于移除指定信标salt/states/beacon.pyname要移除的信标名称saveTrue时同步更新beacons.conf文件。执行流程先beacons.list查询现状若信标存在调用beacons.delete(name)删除若信标本就未配置则返回 name not configured in beaconsresultTrue幂等不会报错。saveTrue时同样追加保存注释。文档示例remove_beacon: beacon.absent: - name: ps - save: True四、beacon.enabled / beacon.disabled启停信标beacon.enabled与beacon.disabled分别负责将已配置的信标置为启用/停用状态salt/states/beacon.pydef enabled(name, **kwargs): # 调用 beacons.enable_beacon(name) def disabled(name, **kwargs): # 调用 beacons.disable_beacon(name)共同点若name尚未配置为信标返回 name not a configured beaconenabled或 Job name is not configured.disabled且result保持True属于幂等空操作底层beacons.enable_beacon/beacons.disable_beacon要求name非空且会先list确认信标存在见 salt/modules/beacons.py成功后再通过事件总线完成状态翻转。典型用法先确保配置、再按需启停enable_beacon: beacon.enabled: - name: ps disable_beacon: beacon.disabled: - name: psp注意这两个函数本身不修改信标的业务参数只翻转enabled标志结合beacon.present中的- enable: False参数可以完整表达配置存在但暂不触发的场景——例如先部署监听、待人工确认后再启用从而避免误报事件。五、底层执行模块beacons.list / add / modify / delete / save了解状态层之后有必要深入执行层因为它决定了状态函数的可靠性与边界条件。执行模块的所有函数都通过 minion 事件总线与 minion 守护进程交互状态层触发的事件 tag 为manage_beacons执行模块监听salt/event/fire结果并等待形如/salt/minion/minion_beacons_动作_complete的完成事件见 salt/modules/beacons.py。5.1 beacons.listsalt * beacons.list返回 minion 当前全部信标配置支持return_yaml默认True返回 YAML 文本、include_pillar与include_opts是否合并 pillar/opts 中配置的信标。状态层统一以return_yamlFalse取得结构化字典用于比对。若事件系统不可用会返回resultFalse与 Event module not available. Beacon list failed.。5.2 beacons.addsalt * beacons.add ps [{processes: {salt-master: stopped, apache2: stopped}}]新增信标的关键路径salt/modules/beacons.py若同名信标已存在直接返回 Beacon {name} is already configured.resultTrue检查beacon_module若有并用beacons.list_available校验该类型可用通过事件总线触发validate_beacon调用对应 beacon 模块的validate函数做配置校验——配置不合法时直接拒绝添加返回Beacon {name} configuration invalid, not adding.\n原因校验通过后触发add并比对返回的信标集合确认写入成功若 60 秒default_event_wait可通过timeout覆盖内未收到完成事件则报错。这一步是状态beacon.present的校验防线SLS 中写的参数如 inotify 的mask、load 的averages最终都要过 beacon 模块自身的validate语法错误会在状态运行阶段被当场捕获。5.3 beacons.modifysalt * beacons.modify ps [{salt-master: stopped}, {apache2: stopped}]修改既有信标salt/modules/beacons.py信标不存在时返回 Beacon {name} is not configured.与add相同先validate_beacon校验新配置用difflib.unified_diff生成新旧配置的 diff写入返回值changes.diff——这正是beacon.present状态变更报告changes的内容来源读者在状态运行摘要里看到的差异文本即来自此处触发modify后只有当beacons[name] beacon_data时才算修改成功。5.4 beacons.delete 与 beacons.savesalt * beacons.delete ps salt * beacons.savedelete从运行态移除信标删除成功后name不再出现在信标集合中salt/modules/beacons.pysave将当前不含 pillar 的全部信标配置序列化为 YAML 写入beacons.conf路径由 minion 配置推导os.path.dirname(conf_file)与default_include目录拼接通常即/etc/salt/minion.d/beacons.confsalt/modules/beacons.py。写文件失败如权限不足会返回resultFalse与明确提示。这也是状态present/absent中save: True的实际落盘动作内存中的信标配置在 minion 重启后是否保留取决于是否执行过beacons.save。因此在生产环境建议将需要持久化的信标状态一律加上- save: True。六、实战进阶interval、disable_during_state_run 与事件循环防护6.1 指定探测间隔 intervalbeacon 默认按 beacon 模块自身设定的节奏运行但可以在配置中通过interval指定探测周期单位秒。主题文档给出的示例doc/topics/beacons/index.rst同时演示了inotify每 5 秒、load每 10 秒的配置beacons: inotify: - files: /etc/important_file: mask: - modify /opt: mask: - modify interval: 5 - disable_during_state_run: True load: - averages: 1m: - 0.0 - 2.0 5m: - 0.0 - 1.5 15m: - 0.1 - 1.0 interval: 106.2 避免事件循环disable_during_state_run信标 reactor 的组合容易产生事件回环例如一个监听文件读取的信标触发 reactor 去执行某个状态而该状态又读取了同一文件再次触发信标事件形成无限循环doc/topics/beacons/index.rst。解决方法是disable_during_state_run: True当 minion 正在执行状态运行state run时该信标暂停按常规间隔触发直到状态运行结束才恢复beacons: inotify: - files: /etc/important_file: {} mask: - modify - disable_during_state_run: True将这一参数放进beacon.present的 kwargs 同样有效见前文多副本示例。此外主题文档还提示如果自定义 beacon 需要在状态运行期间执行清理工作如关闭文件句柄以配合该参数可在 beacon 模块中实现close()函数参考inotifybeacon 的实现。6.3 完整实战inotify 信标 reactor 文件回滚将以上知识点串起来一个典型的文件被篡改自动回滚场景如下细节见 doc/topics/beacons/index.rst在 minion 上配置 inotify 信标监听/etc/important_file的modify事件并启用disable_during_state_run: True写入/etc/salt/minion.d/beacons.conf后重启 minion 服务beacons: inotify: - files: /etc/important_file: mask: - modify - disable_during_state_run: True在 master 上观察事件验证信标确实在文件变更时发出事件salt-run state.event prettytrue修改文件后事件总线上会出现形如下面的事件其中tag携带 minion ID、beacon 类型与文件路径{ _stamp: 2015-09-09T15:59:37.972753, data: { change: IN_IGNORED, id: larry, path: /etc/important_file }, tag: salt/beacon/larry/inotify//etc/important_file }编写 reactor 与状态让 master 在收到该事件时把文件恢复为期望内容# /srv/reactor/revert.sls revert-file: local.state.apply: - tgt: {{ data[id] }} - arg: - maintain_important_file# /srv/salt/maintain_important_file.sls important_file: file.managed: - name: /etc/important_file - contents: | important_config: True在 master 配置 reactor 映射若已存在reactor段则合并其中# /etc/salt/master.d/reactor.conf reactor: - salt/beacon/*/inotify//etc/important_file: - /srv/reactor/revert.sls主题文档特别强调两点工程建议一是信标触发的事件所对应的状态必须幂等idempotent避免反复执行产生副作用二是应结合disable_during_state_run: True防止信标触发状态 → 状态改动被监听文件 → 再次触发信标的闭环。七、测试与验证状态函数的单元测试视角仓库为 beacon 状态模块提供了完整的单元测试tests/pytests/unit/states/test_beacon.py可用于验证本文所述行为test_present通过patch.dict模拟beacons.list用side_effect依次返回信标存在/信标存在/信标不存在等不同现状、beacons.modify与beacons.add分别验证test模式与非test模式下的返回值与幂等行为test_absent模拟beacons.list与beacons.delete验证信标存在时删除、不存在时返回 ps not configured in beacons 且resultTrue。这些测试印证了前文的关键结论状态函数本身不直接操作系统资源而是把beacons.list的现状与目标配置比对后将增删改操作委托给执行模块并通过统一的{name, result, changes, comment}返回结构向 state 系统汇报。八、使用建议与注意事项持久化优先状态运行默认只改内存中的信标配置minion 重启即丢失需要跨重启保留时务必使用save: True或手动执行salt * beacons.save。配置校验前置beacons.add/beacons.modify会调用 beacon 模块自身的validate函数校验配置非法参数如不支持的mask值会在状态阶段直接失败可据此把配置错误挡在应用之前。多副本命名3000 版本起可用beacon_module让多个信标名共享同一实现信标名SLS ID此时仅作为该副本的标识实际类型以beacon_module为准。事件循环防护凡是信标事件 → reactor → 状态 → 再次影响被监听对象的场景都应组合使用disable_during_state_run: True与幂等状态必要时为自定义 beacon 实现close()配合暂停。查询与排障状态运行前可用salt * beacons.list查看现状、salt * beacons.list_available确认信标类型可用性事件总线上可用salt-run state.event prettytrue观察信标是否按预期发出事件。结语beacon.present、beacon.absent、beacon.enabled、beacon.disabled四个状态函数把 Salt minion 上零散的信标配置文件纳入了统一、幂等、可审计的声明式管理体系状态层负责目标比对与幂等判定执行层salt/modules/beacons.py负责配置校验、事件总线通信与落盘持久化。配合beacon_module多副本、interval探测周期、disable_during_state_run事件循环防护以及 reactor 的联动你可以用一份 SLS 把系统状态主动感知完整地纳入基础设施即代码的范畴让监控与告警的配置像其他资源一样可版本化、可测试、可回滚。【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考