运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载导读在 SaltStack 管理实践中你经常需要快速回答三个问题这台 minion 上到底加载了哪些执行模块某个函数的参数签名是什么某个 state 或 runner 的用法文档在哪sys执行模块salt/modules/sysmod.py正是为此而生的元信息查询模块它不直接管理系统资源而是对 minion 上已加载的执行模块execution modules、state 模块、runner、returner、renderer 进行枚举、文档提取和参数签名分析。读完本文你将掌握通过salt * sys.xxx与salt-call --local sys.xxx快速盘点、检索、校验 Salt 模块体系的全套方法并能理解其底层实现原理。本文对应的官方 API 文档页为 doc/ref/modules/all/salt.modules.sysmod.rst该页通过automodule指令自动从源码生成完整实现位于 salt/modules/sysmod.py。一、sys 模块定位minion 上的模块元信息中心从源码看sys模块是一个非常轻量、但与 loader 深度耦合的模块__virtualname__ sys __proxyenabled__ [*]__virtualname__ sys模块对外暴露的名称是sys因此所有调用入口都是sys.function__proxyenabled__ [*]表明该模块对所有 proxy minion 类型开放即代理 minion如网络设备、云 API 代理上同样可以调用这些函数模块没有维护任何自身状态全部依赖 dunder 变量__salt__执行模块字典、__opts__配置以及salt.loader、salt.state、salt.runner等加载器组件动态获取信息。模块 docstring 一句话点明了它的定位The sys module provides information about the available functions on the minionsys 模块提供 minion 上可用函数的信息。所有函数在 master 上统一通过salt命令调用格式为salt * sys.function [参数]在没有 master 的单机场景可用salt-call的本地模式获得相同能力salt-call --local sys.function [参数]下文所有 CLI 示例均同时适用于这两种调用方式salt-call --local输出的 JSON 结构相同。二、文档检索类函数doc / state_doc / runner_doc / returner_doc / renderer_doc这类函数的作用是批量抓取各类模块的 docstring文档字符串并聚合返回返回值是一个{函数名: 文档字符串}的字典。所有返回内容都会经过salt.utils.doc.strip_rst清洗见第五节源码分析。2.1sys.doc执行模块文档不传参数时返回 minion 上所有执行模块函数的 docstring传参时可以指定一个或多个模块名、函数名甚至 glob 通配符salt * sys.doc salt * sys.doc sys salt * sys.doc sys.doc salt * sys.doc network.traceroute user.info参数支持 glob 通配2015.5.0 起salt * sys.doc sys.* salt * sys.doc sys.list_*注意源码中的匹配细节sysmod.py#L64-L83参数中不含*时会把module归一化为module .即sys与sys.都能匹配sys.*系列函数但不会误匹配sysctl这类以sys开头的其他模块参数中含*时使用fnmatch.filter(__salt__, target_mod)进行 glob 匹配。2.2sys.state_docstate 模块文档返回所有 state 函数如service.running、pkg.installed的 docstring2014.7.0 引入glob 支持于 2015.5.0salt * sys.state_doc salt * sys.state_doc service salt * sys.state_doc service.running salt * sys.state_doc service.running iptables.append salt * sys.state_doc service.* iptables.*实现上它通过salt.state.State(__opts__)构造 state 对象后遍历其states字典并且会额外提取每个 state 模块文件的__globals__[__doc__]即模块级 docstring作为模块级说明同时保留每个函数自身的 docstring。2.3sys.runner_docrunner 文档返回 runner运行在 master 上的模块函数的文档2014.7.0 引入salt * sys.runner_doc salt * sys.runner_doc cache salt * sys.runner_doc cache.grains salt * sys.runner_doc cache.grains mine.get salt * sys.runner_doc cache.clear_*实现上通过salt.runner.Runner(__opts__)获取 master 侧 runner 函数字典run_.functions。2.4sys.returner_docreturner 文档返回 returner结果回传后端模块函数的文档2014.7.0 引入salt * sys.returner_doc salt * sys.returner_doc sqlite3 salt * sys.returner_doc sqlite3.get_fun salt * sys.returner_doc sqlite3.get_fun etcd.get_fun salt * sys.returner_doc sqlite3.get_*实现上通过salt.loader.returners(__opts__, [])加载 returner 函数字典。2.5sys.renderer_docrenderer 文档返回 renderer渲染器如 jinja、yaml、json函数的文档2015.5.0 引入salt * sys.renderer_doc salt * sys.renderer_doc cheetah salt * sys.renderer_doc jinja json salt * sys.renderer_doc c* j*实现上通过salt.loader.render(__opts__, [])加载 renderer 函数字典。三、枚举清单类函数盘点已加载的模块与函数这类函数返回的是已加载模块/函数的名称列表Python 的list便于脚本化处理或快速确认某个模块是否可用。3.1 执行模块# 列出 minion 上所有已加载的执行模块名2015.5.0 引入 salt * sys.list_modules # 用 glob 过滤模块名 salt * sys.list_modules s* # 列出所有执行函数0.12.0 引入 salt * sys.list_functions # 指定模块或函数 salt * sys.list_functions sys salt * sys.list_functions sys user salt * sys.list_functions module.specific_function # glob 匹配函数名2015.5.0 引入 salt * sys.list_functions sys.list_*注意list_functions源码中带有**kwargs形参注释说明这是为了防止垃圾参数被追加到末尾时产生 traceback调用时多传参数也不会报错。3.2 state 模块与函数# 列出所有已加载的 state 模块2014.7.0 引入 salt * sys.list_state_modules # glob 过滤 salt * sys.list_state_modules mysql_* # 列出所有 state 函数2014.7.0 引入 salt * sys.list_state_functions # 指定 state 模块或函数 salt * sys.list_state_functions file salt * sys.list_state_functions pkg user salt * sys.list_state_functions file.* salt * sys.list_state_functions file.s* # 2016.9.0 起支持直接指定模块.具体函数 salt * sys.list_state_functions module.specific_function3.3 runner 与 runner 函数# 列出所有已加载的 runner 模块2014.7.0 引入 salt * sys.list_runners # glob 过滤 salt * sys.list_runners m* # 列出所有 runner 函数2014.7.0 引入 salt * sys.list_runner_functions # 指定 runner 模块或 glob salt * sys.list_runner_functions state salt * sys.list_runner_functions state virt salt * sys.list_runner_functions state.* virt.*3.4 returner 与 returner 函数# 列出所有已加载的 returner 模块2014.7.0 引入 salt * sys.list_returners # glob 过滤 salt * sys.list_returners s* # 列出所有 returner 函数2014.7.0 引入 salt * sys.list_returner_functions # 指定 returner 模块或 glob salt * sys.list_returner_functions mysql salt * sys.list_returner_functions mysql etcd salt * sys.list_returner_functions sqlite3.get_*3.5 renderer# 列出所有已加载的 renderer2015.5.0 引入 salt * sys.list_renderers # glob 过滤 salt * sys.list_renderers yaml*需要特别说明的是list_modules、list_state_modules等模块级函数在源码中都是通过对函数名split(.)[0]提取模块前缀并去重得到的因此输出的是模块名集合而list_*_functions系列直接返回完整函数名。两者都使用 Pythonset去重后sorted()排序输出保证结果稳定、有序。四、签名分析类函数argspec 系列当你想确认某个函数的参数、默认值、是否支持*args/**kwargs时argspec系列函数会返回一份结构化的函数签名报告非常适合写 SLS、Pillar 或二次开发前校验参数用法。4.1 四类 argspec# 执行模块函数签名2015.5.0 引入 salt * sys.argspec pkg.install salt * sys.argspec sys salt * sys.argspec # state 函数签名2015.5.0 引入 salt * sys.state_argspec pkg.installed salt * sys.state_argspec file salt * sys.state_argspec # runner 函数签名2015.5.0 引入 salt * sys.runner_argspec state salt * sys.runner_argspec http salt * sys.runner_argspec # returner 函数签名2015.5.0 引入 salt * sys.returner_argspec xmpp salt * sys.returner_argspec xmpp smtp salt * sys.returner_argspecglob 同样适用salt * sys.argspec pkg.* salt * sys.state_argspec pkg.* salt * sys.returner_argspec sqlite3.* salt * sys.runner_argspec winrepo.*4.2 返回结构基于argspec_report四者最终都委托给 salt/utils/args.py 的salt.utils.args.argspec_report(functions, module)。对每个匹配函数它返回如下结构的字典{ 函数名: { args: [positional 参数名列表], # 无则 null defaults: [默认值列表], # 无则 null varargs: true | null, # 是否接受 *args kwargs: true | null # 是否接受 **kwargs } }源码中args与defaults一一对应defaults逆序对齐到args末尾varargs/kwargs用布尔值标记是否支持可变参数。通过对比sys.argspec pkg.install与sys.argspec file.managed的输出你可以快速看到不同模块函数的参数差异这是排查参数名写错类问题的高效手段。state_argspec、returner_argspec、runner_argspec分别基于salt.state.State(__opts__).states、salt.loader.returners(__opts__, [])、salt.runner.Runner(__opts__).functions这三个函数字典调用同一个argspec_report。五、进阶sys.state_schema与 JSON Schema 输出sys.state_schema2016.3.0 引入是 argspec 之上的一层封装它把 state 函数的参数签名转换为JSON Schema便于集成到外部工具链、编辑器补全或 CI 校验中salt * sys.state_schema salt * sys.state_schema pkg.installed实现流程sysmod.py#L865-L884先调用state_argspec(module)拿到每个 state 函数的args/defaults交给私有辅助函数_argspec_to_schema(mod, spec)sysmod.py#L826-L862将参数拆分为必填参数与带默认值参数两组利用salt.utils.schema的OneOfItem为每个参数生成BooleanItem/IntegerItem/NumberItem/StringItem联合类型必填参数requiredTrue带默认值参数附带default最终动态构造一个Schema子类并serialize()输出 JSON Schema 列表。返回结果是 schema 对象的列表每个元素对应一个 state 函数。这份 schema 描述了 state 函数每个参数的类型与默认值是 Salt 在参数自描述方向上的代表性能力。六、sys.reload_modules一个特殊的钩子函数sys.reload_modules用于让 minion 重新加载执行模块但它的实现并不在 sysmod.py 内。源码 docstring 明确说明sysmod.py#L406-L420This function is actually handled inside the minion.py file, the function is caught before it ever gets here. Therefore, the docstring above is only for the online docs, and ANY CHANGES made to it must also be made in each of the gen_modules() funcs in minion.py.也就是说sysmod.py 中的这个函数体return True永远不会被执行真正的逻辑位于 salt/minion.py在MinionBase.gen_modules()中模块加载完成后会执行self.functions[sys.reload_modules] self.gen_modulesminion.py#L753把sys.reload_modules直接绑定到gen_modules方法上当收到sys.reload_modules作业时minion.py#L2469-L2478 会走专用分发路径调用_load_modules()重新构建functions、returners、function_errors、executors并同步更新调度器self.schedule.functions与self.schedule.returners。因此sys.reload_modules的效果是热重载执行模块、returner、executor常用于模块文件更新后无需重启 minion 即可生效。其 docstring 中ANY CHANGES must also be made in minion.py的警告提醒维护者这个函数在 sysmod.py 与 minion.py 中都有同名 docstring 副本修改时需保持同步。从调用语义看sys.reload_modules的目标是 minion 进程自身通过 master 下发salt * sys.reload_modules这也解释了为什么它需要被 minion 的作业处理循环特殊截获。七、源码级实现原理7.1 数据来源__salt__与加载器sys 模块的所有盘点能力都建立在 Salt 的 loader 体系之上。以sys.doc为例__salt__是 minion 上由salt.loader.minion_mods(opts, ...)加载出的执行模块函数字典参见 salt/minion.py 的gen_modules模块名与函数名的映射即{模块名.函数名: callable}。sys 模块只是对这个字典做遍历、过滤与格式化自身不持有任何模块清单。而 state/runner/returner/renderer 文档与清单函数则分别通过salt.state.State(__opts__)、salt.runner.Runner(__opts__)、salt.loader.returners(__opts__, [])、salt.loader.render(__opts__, [])按需构造对应加载器再读取其states、functions等字典属性。7.2 匹配规则glob 与sys 不匹配 sysctl几乎所有带参数的函数都遵循同一套匹配逻辑参数含*走fnmatch.filter(函数字典, pattern)支持sys.*、sys.list_*这类 glob参数不含*将参数补一个点号作为前缀target_mod module .再做startswith前缀匹配——这样sys只匹配sys.*不会误匹配sysctl、system等以sys开头的其它模块源码中多处注释明确提到这一点多参数*args支持一次性传入多个模块/函数名如salt * sys.doc network.traceroute user.info各自独立匹配后合并结果。7.3 文档清洗salt.utils.doc.strip_rst所有*_doc函数返回前都调用salt.utils.doc.strip_rst(docs)salt/utils/doc.py#L11-L39用正则对 docstring 做规范化删除.. code-block::指令及其内容保留示例代码本身将.. note::/.. warning::替换为Note:/Warning:将.. versionadded::/.. versionchanged::替换为New in version/Changed in version。这样聚合到 master 上供人阅读的文档就是纯文本而非原始 reStructuredText。7.4 版本演进脉络从 docstring 的versionadded标记可以勾勒出 sys 模块的能力演进史版本新增能力0.12.0sys.list_functions2014.7.0state_doc、runner_doc、returner_doc以及list_state_*、list_runner*、list_returner*系列2015.5.0大批量引入 glob 匹配支持新增list_modules、list_renderers、renderer_doc、argspec、state_argspec、runner_argspec、returner_argspec2016.3.0state_schemaJSON Schema 输出2016.9.0list_state_functions支持直接指定模块.具体函数八、实战建议与测试佐证8.1 典型排查场景这个函数存在吗salt * sys.list_functions配合 grep例如salt * sys.list_functions | grep pkg这个函数怎么用salt * sys.doc pkg.install直接看返回的用法与 CLI 示例这个函数接受什么参数salt * sys.argspec pkg.install核对参数名与默认值state 写错了参数名salt * sys.state_argspec file.managed比对参数列表模块热更新修改自定义执行模块后执行salt * sys.reload_modules无需重启 minion单机速查没有 master 时用salt-call --local sys.doc test.ping等命令直接在本机查询。8.2 仓库内的测试佐证仓库的测试代码可以印证 sys 模块的实际行为tests/pytests/pkg/integration/test_salt_call.py 验证了salt-call --local sys.doc none查询不存在的模块与sys.doc aliases模块别名如aliases.list_aliases的输出行为tests/pytests/functional/loader/test_subsystem_whitelist_dunder.py 验证了在严格whitelist_modules白名单场景下sys.doc仍能通过内部 loader 正常解析包括sys.doc(test.ping)与 glob 形式sys.doc(foo.bar*)避免泄露KeyError或 tracebacktests/pytests/integration/resources/test_resource_loader_strict.py 确认在资源 loader 严格模式下sys.list_functions返回空列表而非泄露完整的标准模块清单tests/integration/loader/test_ext_modules.py 在扩展模块集成测试中通过sys.list_functions验证自定义模块是否被正确加载。这些测试表明sys.doc、sys.list_functions不仅在常规场景可用在 whitelist、资源 loader 等受限加载模型下也被设计为始终可用的诊断入口是排查 minion 模块加载问题的第一选择。结语sys模块是 Salt 运维与开发者的万能查询器sys.doc系列解决文档在哪的问题sys.list_*系列解决有什么可用的问题sys.argspec系列解决参数怎么传的问题sys.state_schema则把参数能力结构化输出给外部工具。理解它的源码实现——基于__salt__与加载器字典、glob/前缀双模式匹配、strip_rst文档清洗、以及reload_modules在 minion.py 中的特殊处理——能让你在任何规模的 Salt 集群中快速定位模块能力、编写正确的 SLS 与二次开发代码。相关实现细节可继续阅读 salt/modules/sysmod.py、salt/utils/args.py、salt/utils/doc.py 与 salt/minion.py 中gen_modules相关代码。赞分享运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载相关推荐Salt Cloud 执行模块salt.modules.cloud完全指南在任意 Minion 上直接驱动 Salt CloudSalt Cloud 执行模块salt.modules.cloud完全指南在任意 Minion 上直接驱动 Salt Cloud 导读 本文围绕 Salt运维配置管理后端salt-call 命令完全指南在 Salt Minion 本地执行模块函数salt call 命令完全指南在 Salt Minion 本地执行模块函数 salt call 是 Salt 体系中用于在 Minion 本机直接执行模块函运维配置管理后端Salt Proxy 执行模块在 Minion 上自动部署与管理 salt-proxy 进程Salt Proxy 执行模块在 Minion 上自动部署与管理 salt proxy 进程 导读 salt_proxy 是 Salt 提供的执行模块exe运维配置管理后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考