Salt Proxy 执行模块:在 Minion 上自动部署与管理 salt-proxy 进程
Salt Proxy 执行模块:在 Minion 上自动部署与管理 salt-proxy 进程
导读
salt_proxy 是 Salt 提供的执行模块(execution module),用于在普通 Minion 上自动部署、配置并守护 salt-proxy 代理进程,从而让一台设备同时扮演"控制节点"与"代理宿主"的双重角色。在管理交换机、路由器等无法直接安装 Salt Minion 的网络设备场景中,该模块是与 Proxy Minion 架构 配套的关键一环。阅读本文后,你将掌握 configure_proxy 与 is_running 两个核心函数的完整用法、底层实现原理,以及如何通过 State、Beacon 实现代理进程的自动化部署与自愈。
模块定位:Proxy Minion 体系的自动化部署入口
Salt 的 Proxy Minion 机制允许通过代理进程与无法运行标准 Minion 的远程设备(如网络交换机、物联网硬件)通信。传统做法是手工在主机上启动 salt-proxy --proxyid=<name> 进程,而 salt_proxy 模块(salt/modules/salt_proxy.py,versionadded:: 2015.8.3)将这一过程代码化:它由 普通 Minion 执行,替宿主完成两件核心工作:
- 写入代理配置文件:在 Salt 配置目录下生成
proxy文件,记录 master 地址; - 启动代理进程:以守护进程(
-d)方式拉起salt-proxy --proxyid=<name>。
这意味着你可以在 master 上向任意 Minion 下发指令,让它"临时"变成一个代理宿主,从而把 proxy minion 的部署纳入 Salt 的统一自动化体系,而不是逐台手工操作。
configure_proxy:一键完成配置写入与进程启动
configure_proxy 是模块的入口函数(salt/modules/salt_proxy.py#L104-L146),签名如下:
def configure_proxy(proxyname, start=True):
参数说明
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
proxyname |
str | 必填 | 该代理实例的名称,必须与 master 端 pillar 中定义的 proxy ID 一致(如 p8000) |
start |
bool | True |
是否在配置写入后启动 salt-proxy 进程;设为 False 时仅完成配置落盘 |
调用方式
在 master 上针对承载代理的普通 Minion(示例中命名为 deviceminion)执行:
salt deviceminion salt_proxy.configure_proxy p8000
执行流程与返回结构
从源码看,该函数依次调用两个内部辅助函数,并把结果合并为标准的 Salt 返回字典:
_proxy_conf_file(proxyfile, test)(salt/modules/salt_proxy.py#L42-L67):检查CONFIG_DIR/proxy是否已存在。不存在则通过_write_proxy_conf(salt/modules/salt_proxy.py#L20-L39)写入内容master: <master地址>(master 地址取自__grains__["master"]);已存在则跳过并记录 "already exists"。_proxy_process(proxyname, test)(salt/modules/salt_proxy.py#L84-L101):先调用_is_proxy_running探测同名进程,若未运行则执行:
salt-proxy --proxyid=<proxyname> -l info -d
即以 info 级别日志、守护进程模式启动代理;若 start=False,则跳过进程启动步骤,仅在 changes 中记录 "Start is False, not starting salt-proxy process"。
最终返回:
{
"result": status_file and status_proc, # 文件写入与进程启动是否全部成功
"changes": {"old": "...", "new": "..."}, # 变更前后信息
}
其中 changes.new 会包含诸如 Salt Proxy: Started proxy process for p8000 的说明,便于在 state 输出中直接观察本次变更内容。
关键细节:test 模式(dry-run)
函数开头的 test = __opts__<a href="https://link.gitcode.com/i/1ebd2eebf7b5895d360de5388b10fa13" target="_blank">"test"]([salt/modules/salt_proxy.py#L125)使模块天然支持 Salt 的 test 模式:在 test=True 时,_proxy_conf_file 与 _proxy_process 只记录"将会发生什么"(如 Salt Proxy: Update required to proxy conf ...),不真正写文件、不启动进程,方便先演练再执行。
关键细节:proxy 文件的位置
proxy 配置文件的落盘路径由 os.path.join(salt.syspaths.CONFIG_DIR, "proxy") 决定(salt/modules/salt_proxy.py#L128)。CONFIG_DIR 在 salt/syspaths.py 中按平台推导:Linux 下通常为 /etc/salt,即最终生成 /etc/salt/proxy;Windows/macOS 等平台对应 /usr/local/etc/salt、/var/local/salt/etc 等路径。这也解释了为什么该模块通常要求以具备配置目录写权限的用户(如 root)运行。
is_running:检查指定代理进程是否存活
is_running(salt/modules/salt_proxy.py#L149-L167)用于查询某个 proxy ID 对应的 salt-proxy 进程是否存在:
salt deviceminion salt_proxy.is_running p8000
其底层由 _is_proxy_running(salt/modules/salt_proxy.py#L70-L81)实现,通过 cmd.run_all 执行进程匹配命令:
ps ax | grep "salt-proxy --proxyid=p8000" | grep -v grep
- 返回结构为
{"result": True/False}; proxyname经过shlex.quote转义(salt/modules/salt_proxy.py#L74-L76),避免特殊字符注入;- 命令设置了 5 秒超时,避免在极端情况下阻塞执行。
该函数是 State 与 Beacon 判断"是否需要拉起进程"的依据,也是日常巡检代理存活状态的最小化工具。
实战场景一:通过 State 在 Minion 上部署 Proxy
salt_proxy 执行模块被封装为同名 State 模块(salt/states/salt_proxy.py),configure_proxy(name, proxyname="p8000", start=True) 直接透传调用执行模块,并把执行结果包装为标准 state 返回(salt/states/salt_proxy.py#L31-L56)。这样即可把代理部署写成可重复执行的 SLS,官方教程 Proxy Minion States 给出了完整七步流程:
1. 在 master 的 pillar top 中为代理定义条目
base:
'p8000':
- p8000
2. 创建 /srv/pillar/p8000.sls(默认 pillar_roots 下)
proxy:
# 根据实际 proxymodule 设置 proxytype
proxytype: ssh_sample
host: saltyVM
username: salt
password: badpass
3. 在 state 树中创建 salt_proxy.sls
salt-proxy-configure:
salt_proxy.configure_proxy:
- proxyname: p8000
- start: True # 如果进程未运行则启动它
4~5. 确保 master 与普通 minion 运行,并在目标 minion 上执行
# salt device_minion state.sls salt_proxy
这会在 device_minion 上写入 /etc/salt/proxy(若不存在)并启动 salt-proxy 进程。
6. 在 master 上接受代理的密钥
salt-key -y -a p8000
7. 现在即可直接对代理下发命令
salt p8000 pkg.list_pkgs
实战场景二:通过 Beacon 实现代理进程自愈
除了手动/State 触发,Salt 还提供了 salt_proxy Beacon(salt/beacons/salt_proxy.py,versionadded:: 2015.8.3),让 minion 周期性地检查并自动拉起宕掉的代理进程。其配置方式:
beacons:
salt_proxy:
- proxies:
p8000: {}
p8001: {}
Beacon 每次触发时调用 beacon(config)(salt/beacons/salt_proxy.py#L55-L72),其核心逻辑 _run_proxy_processes(salt/beacons/salt_proxy.py#L15-L32)对每个代理名执行:
salt_proxy.is_running(proxy)探测存活;- 未存活则调用
salt_proxy.configure_proxy(proxy, start=True)重新拉起; - 返回事件消息,如
Proxy p8000 is already running或Proxy p8000 was started。
Beacon 的配置校验由 validate(config)(salt/beacons/salt_proxy.py#L35-L52)负责:配置必须是列表、必须包含 proxies 字典,否则返回 (False, 错误信息)。
底层机制补充:proxy 宿主相关配置项
承载代理进程的主机同样需要一份 proxy 配置。仓库提供了完整模板 conf/proxy,其中与代理托管最相关的选项包括:
proxy_merge_grains_in_module:若 proxymodule 提供grains函数,是否在常规 grains 加载时调用并合并结果;proxy_keep_alive与proxy_keep_alive_interval(2017.7.0 起):启用后由调度任务定期调用 proxymodule 的alive函数检测与远端设备的连接,异常则尝试重建连接;proxy_always_alive(2017.7.0 起):默认代理初始化即打开与远端设备的连接;部分 proxymodule 支持改为按命令开关会话;append_minionid_config_dirs:多代理/多 minion 同机运行时,可为pki_dir、cachedir等目录追加 minion ID,默认对 proxy 追加cachedir,避免缓存互相污染。
这些选项直接决定了 salt-proxy 进程运行时的连接生命周期与自愈行为,是与 salt_proxy 模块配合使用的"宿主侧"配置基础。
测试佐证:模块行为如何被验证
仓库对这套机制提供了单元与集成测试,可作为理解行为的辅助证据:
- 单元测试 tests/pytests/unit/beacons/test_salt_proxy.py 通过 mock
salt_proxy.is_running与salt_proxy.configure_proxy验证 Beacon 的两条分支:代理已运行(返回 "already running")与代理未运行(调用配置并返回 "was started"),同时覆盖了非法配置的校验逻辑; - 集成测试 tests/pytests/integration/proxy/test_shell.py 在真实代理链路上验证
test.ping、pkg.list_pkgs、service.*等命令能够正常往返执行,从端到端角度印证了"代理启动后可被 master 调度"这一核心链路。
总结
salt_proxy 执行模块虽然只有两个公开函数,却是 Salt Proxy Minion 自动化落地的最小闭环:configure_proxy 解决"如何让代理跑起来",is_running 解决"如何确认代理还活着"。配合 State 模块 做声明式部署、配合 Beacon 做故障自愈,即可把原本需要逐台手工启动的 salt-proxy 进程,变成由 Salt 自身统一编排、可重复、可巡检的受管资源。若需深入理解 proxy minion 的完整设计,可继续阅读 Proxy Minion 官方主题文档 及同目录下的 demo.rst、ssh.rst 等分篇。