Salt salt_proxy Beacon 实战指南:让 Minion 自动守护并拉起 Salt Proxy 进程
Salt salt_proxy Beacon 实战指南:让 Minion 自动守护并拉起 Salt Proxy 进程
Salt 的 salt_proxy beacon(自 2015.8.3 版本引入)是一个运行在 Minion 上的轻量级守护型 beacon:它周期性检查一组 salt-proxy 进程是否存活,发现异常即调用执行模块自动重启,并把每个 proxy 的状态以事件形式发布到 Salt 事件总线,供 Master 端 reactor 响应。本文基于当前仓库的 beacon 实现、执行模块、单元测试 与 beacon 通用文档,完整讲解其配置方法、校验规则、进程自愈原理与事件集成,帮助你在盐环境中实现 proxy 进程的自动化巡检与自愈。
一、为什么需要 salt_proxy Beacon:proxy minion 的进程守护难题
在 Salt 中,proxy minion(代理 minion)是一类特殊的轻量级 minion,用于管理无法直接安装 salt-minion 的设备(如网络交换机、路由器、带 REST API 的 IoT 设备)。每个 proxy 都以独立进程 salt-proxy --proxyid=<name> 的方式运行在某个"宿主"主机上,并通过 pillar 描述其连接凭据与设备信息。
这类进程一旦崩溃或异常退出,对应的受管设备就会"失联",而传统做法依赖人工 ps 检查或 cron 脚本,维护成本高、反应滞后。salt_proxy beacon 正是为解决这一场景而设计的:它让运行在宿主上的普通 minion 兼任"proxy 保姆",周期性地:
- 检查每个 proxyid 对应的
salt-proxy进程是否存在; - 若进程不存在,自动调用
salt_proxy.configure_proxy执行模块重建配置文件并拉起进程; - 将每个 proxy 的结果("已启动" 或 "已在运行")作为事件返回,交给 Salt 事件系统(可触发 reactor 告警或进一步处理)。
从 beacon 实现 看,其核心巡检逻辑 _run_proxy_processes 对配置中的每个 proxy 依次执行"探测 → 拉起 → 记录结果"三步,逻辑简单而清晰。
二、Beacon 机制速览:它如何被周期性地执行
要正确使用 salt_proxy beacon,先理解 Salt beacon 的通用运行机制(详见 Beacons 通用文档):
- Beacon 由 Salt 加载器(loader)以插件形式加载,配置放在 minion 配置的顶层
beacons:块中,可写在/etc/salt/minion、/etc/salt/minion.d/beacons.conf或 pillar/grains 中; - 每个 beacon 模块必须提供
beacon函数,minion 主循环会按loop_interval(默认约 1 秒)反复调用它; - 可选提供
validate函数,加载器在启用前自动调用以校验配置合法性; beacon函数必须返回"字典列表",列表中的每个字典都会被翻译为一条事件(tag 与 data),发送到 minion 与 master 的事件总线,可被 reactor 捕获。
调度侧的实现可参见 salt/beacons/init.py 中的 Beacon.process:它负责在每次循环中调用 {beacon_name}.validate 校验配置、根据 interval 控制执行频率、并最终调用 {beacon_name}.beacon 收集事件。
三、配置 salt_proxy Beacon:最小可用配置
在宿主 minion 的配置文件(如 /etc/salt/minion.d/beacons.conf)中加入:
beacons:
salt_proxy:
- proxies:
p8000: {}
p8001: {}
保存后重启 minion 服务(service salt-minion restart),beacon 即开始生效。该示例直接取自 beacon 模块的 docstring,语义如下:
| 配置项 | 类型 | 说明 |
|---|---|---|
proxies |
字典(dict) | 要守护的 proxy 列表,key 为 proxyid(须与 pillar 中定义的 proxy 名称一致),value 为附加选项字典(当前实现可留空 {}) |
p8000、p8001 这类名字对应运行时的进程参数 salt-proxy --proxyid=p8000,同时必须与 pillar 中为该 proxy 定义的连接配置(如 proxytype、设备 IP、凭据等)对应,否则即使进程被拉起也无法正常连接设备。
3.1 配置位置的三种来源
与所有 beacon 一致(见 Beacons 通用文档),salt_proxy beacon 配置可来自:
- minion 本地配置:
/etc/salt/minion或/etc/salt/minion.d/*.conf中的beacons:块; - pillar:为特定 minion 下发
beacons:键,优点是可动态更新而无需重启 minion(通用文档 明确说明 beacon 配置可通过 pillar 在运行期动态变更); - grains 或本地配置的其他来源。
其中 pillar 方式特别适合批量管理:所有宿主 minion 共用一份 pillar 模板,新增一个 proxy 设备时只需在 pillar 中追加一个 proxyid。
四、配置校验:validate 函数的规则与常见报错
salt_proxy beacon 实现了 validate 函数(源码位置),在 beacon 每次被启用前由加载器自动调用(见 salt/beacons/init.py)。校验规则逐条如下:
def validate(config):
# 1. 配置必须是列表
if not isinstance(config, list):
return False, "Configuration for salt_proxy beacon must be a list."
# 2. 列表转字典后必须包含 proxies 键
config = salt.utils.beacons.list_to_dict(config)
if "proxies" not in config:
return False, "Configuration for salt_proxy beacon requires proxies."
# 3. proxies 必须是字典
if not isinstance(config["proxies"], dict):
return False, "Proxies for salt_proxy beacon must be a dictionary."
return True, "Valid beacon configuration"
即存在三类无效配置,分别返回对应错误信息:
| 错误场景 | 错误信息 | 典型错误写法 |
|---|---|---|
| 顶层不是列表 | Configuration for salt_proxy beacon must be a list. |
beacons: salt_proxy: {proxies: {p8000: {}}}(直接给字典) |
缺少 proxies 键 |
Configuration for salt_proxy beacon requires proxies. |
beacons: salt_proxy: - interval: 5 |
proxies 不是字典 |
Proxies for salt_proxy beacon must be a dictionary. |
- proxies: p8000(写成字符串/列表) |
校验失败时,Beacon.process 会记录 Beacon %s configuration invalid, not running 错误日志并跳过该 beacon,因此配置错误不会导致 minion 崩溃,但也不会有任何巡检动作——排查时应先检查 minion 日志。
这里的"列表转字典"动作来自工具函数 salt/utils/beacons.py 的 list_to_dict:它把列表形式的 beacon 配置逐项合并成一个字典,从而兼容 - proxies: {...}、- interval: 5 这类多个列表元素混合的写法。这也是整个 Salt beacon 体系的通用配置风格。
五、运行原理:beacon 函数如何检查并拉起进程
beacon 函数(源码位置)把列表配置转为字典后,调用 _run_proxy_processes(config["proxies"]) 遍历所有 proxy:
def _run_proxy_processes(proxies):
ret = []
for proxy in proxies:
result = {}
if not __salt__<a href="https://link.gitcode.com/i/4df442095ced530d43cafd0a5625f21e" target="_blank">"salt_proxy.is_running"</a>["result"]:
__salt__"salt_proxy.configure_proxy"
result[proxy] = f"Proxy {proxy} was started"
else:
msg = f"Proxy {proxy} is already running"
result[proxy] = msg
log.debug(msg)
ret.append(result)
return ret
每个 proxy 的处理流程为:
- 探测:调用执行模块
salt_proxy.is_running(proxy),返回{"result": True/False}; - 自愈:若
result为False(进程不存在),调用salt_proxy.configure_proxy(proxy, start=True),自动写配置文件并启动进程,结果记为"Proxy {proxy} was started"; - 健康:若进程已存在,结果记为
"Proxy {proxy} is already running",同时仅记录 debug 日志; - 收集:每个 proxy 的结果以
{proxyid: 状态消息}字典形式追加到返回值列表。
返回值形如:
[
{"p8000": "Proxy p8000 is already running"},
{"p8001": "Proxy p8001 was started"},
]
按 beacon 契约(通用文档),这个列表中的每个字典会在 minion 上被翻译为一条事件,事件 tag 形如 salt/beacon/{minion_id}/salt_proxy/,data 为上述字典内容(id 自动补为 minion id,见 salt/beacons/init.py)。
5.1 beacon 函数的轻量性要求
值得强调的是,通用文档 明确要求 beacon 函数"不能阻塞、应尽可能轻量",因为默认情况下它会在 minion 每次主循环(每秒可达数十到上百次)中被调用。salt_proxy beacon 每次调用都会对每个 proxy 执行一次 ps ax | grep 系统调用(由执行模块的 _is_proxy_running 发起),若托管 proxy 数量较多,建议配合 interval 参数降低巡检频率(见第七节),避免对宿主造成不必要的 IO 压力。
六、底层支撑:salt_proxy 执行模块的完整调用链
beacon 本身不做系统交互,所有"写文件、起进程"的脏活都委托给执行模块 salt/modules/salt_proxy.py,这符合 Salt "执行模块是所有工作与系统交互的首选位置" 的设计原则(通用文档)。执行模块同样自 2015.8.3 提供,功能为"在 minion 上部署与管理 salt-proxy 进程"。
6.1 is_running:进程探测
def is_running(proxyname):
return {"result": _is_proxy_running(proxyname)}
底层 _is_proxy_running(源码位置)执行:
ps ax | grep "salt-proxy --proxyid={proxyname}" | grep -v grep
通过 cmd.run_all 以 timeout=5、python_shell=True 运行,stdout 非空即判定进程在运行。注意:
- 探测基于精确匹配 proxyid 的进程命令行,proxyid 经过
shlex.quote转义以防注入; - 仅匹配
--proxyid=参数形式,若 proxy 以其他方式启动(如不同参数名)将无法识别,可能被误判为"未运行"而触发重复拉起。
6.2 configure_proxy:配置写入与进程拉起
def configure_proxy(proxyname, start=True):
# 1. 必要时写入 <CONFIG_DIR>/proxy 文件(内容为 master: <master地址>)
# 2. start=True 时检查并启动 salt-proxy 进程
return {
"result": status_file and status_proc,
"changes": {"old": ..., "new": ...},
}
该方法分两步(源码位置):
- 写配置:若
${CONFIG_DIR}/proxy(Linux 上即/etc/salt/proxy,路径来自 salt/syspaths.py 的CONFIG_DIR)不存在,则写入master: <master地址>(内容取自__grains__["master"]);已存在则跳过并记录already exists。这保证新拉起的 salt-proxy 知道应向哪个 master 注册; - 起进程:当
start=True时,若探测发现进程未运行,执行salt-proxy --proxyid={name} -l info -d(-d后台守护、-l info日志级别),并把结果记录到changes.new;若已在运行则记录到changes.old。
start 参数默认 True,但若显式传 False,则只保证配置文件就绪、不启动进程(记录 Start is False, not starting salt-proxy process)。该方法遵循 salt 的 test 模式语义:__opts__["test"] 为真时仅报告将要执行的动作而不实际写入/启动。最终返回标准的 {"result": bool, "changes": {...}} 结构,beacon 仅使用其 result 判断拉起动作是否生效。
6.3 与 beacon 的组合语义
综合来看,一次巡检的完整调用链为:
beacon.beacon()
└─ salt_proxy.is_running(proxy) # 探测进程
└─ _is_proxy_running() # ps ax | grep --proxyid=
└─ salt_proxy.configure_proxy(proxy, start=True) # 仅当未运行时
├─ _proxy_conf_file() # 写 /etc/salt/proxy(如缺失)
└─ _proxy_process() # 拉起 salt-proxy --proxyid=... -d
这条链路在单元测试 tests/pytests/unit/beacons/test_salt_proxy.py 中被完整验证:测试 mock 掉 is_running/configure_proxy/cmd.run_all 三个 __salt__ 入口,分别断言"进程已在运行"时返回 {"p8000": "Proxy p8000 is already running"},"进程未运行"时返回 {"p8000": "Proxy p8000 was started"},并覆盖了非列表配置、空配置(缺 proxies)两类校验失败场景——这些测试即上文第四节的校验规则的直接依据。
七、进阶配置:巡检频率与事件防循环
作为 beacon,salt_proxy 同样支持所有通用 beacon 参数,可在 proxies 之外追加列表元素:
beacons:
salt_proxy:
- proxies:
p8000: {}
p8001: {}
- interval: 30
- disable_during_state_run: True
interval(秒):默认 beacon 约 1 秒巡检一次(通用文档 的监控间隔说明);由于每次巡检都伴随ps系统调用,托管 proxy 多时可设为 30~60 秒以降低开销。调度侧由 Beacon._process_interval 基于loop_interval计数实现。disable_during_state_run: True:当宿主 minion 正在执行 state 运行时暂停该 beacon(通用文档)。该参数对salt_proxybeacon 尤为重要:若你的 state 或 reactor 本身会操作 proxy 进程,避免"beacon 拉起进程 → state 关掉进程 → beacon 再拉起"的事件-反应死循环(通用文档称之为 avoiding beacon event loops)。run_once:让 beacon 仅执行一次后自动禁用(Beacon.process),适合一次性巡检场景。beacon_module:从 Neon 版本起(通用文档),可通过该参数以不同名称注册同一 beacon 的多份配置,例如分别守护不同批次的 proxy:
beacons:
watch_proxy_west:
- proxies:
p8000: {}
- beacon_module: salt_proxy
watch_proxy_east:
- proxies:
p9000: {}
- beacon_module: salt_proxy
八、与 reactor 联动:让巡检结果触发自动化响应
beacon 产生的事件默认只发布到事件总线,实际响应依赖 reactor。在 Master 端配置 reactor(见 Beacons 通用文档的 reactor 示例)即可实现告警或联动:
# /etc/salt/master.d/reactor.conf
reactor:
- 'salt/beacon/*/salt_proxy/*':
- /srv/reactor/proxy_status.sls
# /srv/reactor/proxy_status.sls
alert-proxy-restarted:
local.state.apply:
- tgt: {{ data['id'] }}
- arg:
- report_proxy_status
事件数据中 data 为 {proxyid: "Proxy xxx was started"} 形式(另含自动补充的 id 字段),reactor 的 SLS 可通过 {{ data<a href="https://link.gitcode.com/i/9f194d818af4c359f2ff64a1b7235f23" target="_blank">'p8000'] }} 等方式引用具体 proxy 状态,例如:某 proxy 被拉起时触发告警通知,或对所有 proxy 健康时保持静默。调试时可在 Master 上运行 salt-run state.event pretty=true 实时观察 beacon 事件流([通用文档)。
九、使用建议与注意事项
- proxyid 与 pillar 必须对齐:beacon 只负责"进程存活",不负责"设备可用"。
proxies中的名称必须与 pillar 中定义的 proxy 配置一致,否则拉起的进程可能因缺少凭据而反复退出。 - 探测机制的边界:进程检测基于
ps ax | grep "salt-proxy --proxyid=<name>",无法感知进程"活着但僵死(zombie)或失联"的状态;若需更深度的健康检查,可结合其他 beacon(如load、ps)或 reactor 侧的心跳超时逻辑。 - test 模式可用:在 minion 的
test: True模式下,configure_proxy只报告"将要写入/启动"而不真正执行,可安全用于演练与验证配置正确性。 - 控制巡检频率:默认每秒一次的系统调用在高密度 proxy 场景下会有额外开销,合理设置
interval是生产环境的关键调优项。 - 日志排查:beacon 使用
salt_proxy命名空间的 logger,正常静默时仅记录 debug 级日志;配置无效会在 minion 日志中输出Beacon salt_proxy configuration invalid错误,是定位问题的第一入口。
十、参考资料
- Beacon 实现:salt/beacons/salt_proxy.py(
validate/beacon/_run_proxy_processes) - 执行模块:salt/modules/salt_proxy.py(
configure_proxy/is_running/_is_proxy_running) - 单元测试:tests/pytests/unit/beacons/test_salt_proxy.py
- Beacon 通用机制:doc/topics/beacons/index.rst
- Beacon 调度框架:salt/beacons/init.py
- 配置工具函数:salt/utils/beacons.py
- Beacon 模块索引:doc/ref/beacons/all/index.rst