运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载salt-call是 Salt 体系中用于在 Minion 本机直接执行模块函数的命令行工具无需经由 Master 下发任务既是排查 Minion 问题的第一把手也是构建无 MasterStandalone/Masterless架构的核心入口。本文以官方参考文档 doc/ref/cli/salt-call.rst 为骨架结合本仓库中 salt/cli/call.py、salt/cli/caller.py 与 salt/utils/parsers.py 的源码实现系统讲解其全部选项、执行流程、返回码语义与实战用法。读完本文你将能熟练使用salt-call完成本机调试、Standalone 状态应用、返回器对接与脚本化集成。一、概述salt-call 是什么按官方语法salt-call的调用形式为salt-call [options]它的核心定位是在 Minion 本地运行模块函数module functions而不是由 Master 远程执行。两个最典型的应用场景在官方文档中明确列出运行 Standalone Minion无 Master 独立运行用于 Minion 故障排查该工具最初就是为此而生。一个容易忽略但非常重要的行为差异官方文档以 note 强调salt-call命令从当前用户的 shell 上下文执行而salt命令从系统默认上下文执行。这意味着salt-call执行的权限、环境变量、~/.bashrc等由你调用它时的登录用户决定——排查手动执行成功但 cron/服务执行失败类问题时这个差异往往是根因。另外需要注意除非指定--local否则salt-call在执行过程中仍会联系 Master 获取 state 文件和其他资源文件服务器、pillar 等。也就是说不带--local的salt-call并不是完全离线的它只是把执行放在本机、把数据来源仍交给 Master。二、工作机制从命令行到函数执行理解salt-call的选项之前先看它在源码中的完整执行链路这能帮你判断每个选项到底作用于哪个环节。2.1 入口SaltCall.run()salt-call的 CLI 入口类是 salt/cli/call.py 中的SaltCall其run()方法salt/cli/call.py#L17-L151依次完成parse_args()解析命令行参数选项定义来自salt.utils.parsers.SaltCallOptionParser将--file-root、--pillar-root、--states-dir参数转换为绝对路径并写入config[file_roots]、config[pillar_roots]、config[states_dirs]若指定--local设置config[file_client] local若指定--master覆盖config[master]调用salt.utils.verify.verify_env校验 pki 目录、缓存目录等环境通过Caller.factory(self.config)创建调用器当前实现固定返回ZeroMQCaller见 salt/cli/caller.py#L40-L42若带-d/--doc则打印模块文档若带-g/--grains则打印 grains随后启动 tracing span 并执行caller.run()。值得注意的细节如果你传了--file-root/--pillar-root/--states-dir却没有同时传--local程序会向 stderr 打印一条警告并忽略这些参数源码注释引用了 issue #68137不指定--local时远程文件客户端会从 Master 拉取 state/pillar 数据从而静默覆盖本地配置的 file_roots / pillar_roots / states_dirs。源码位于 salt/cli/call.py#L44-L65。2.2 执行核心Caller.call()真正执行函数的是BaseCaller.call()salt/cli/caller.py#L122-L297关键步骤包括为本次调用生成 jidsalt.utils.jid.gen_jid并把调用信息序列化写入 Minion 的 proc 目录cachedir/proc/jid这是salt-run jobs.list_jobs、saltutil等能查到本地 job 的前提若函数不存在会通过sys.doc做错误路径文档查找尝试给出相近模块提示与模块加载失败原因function_errors这是排查模块缺失的贴心设计按module_executors列表依次尝试执行器默认direct_call首个返回非None的执行器结果胜出计算 retcode优先取__context__[retcode]否则检查返回 dict 中的result/success键是否有假值若函数带__outputter__属性则用其作为默认输出器遍历--return指定的返回器把结果写入各返回器接口若处于非 local 模式且未指定--no-return-event则通过ReqChannelsalt.channel.client.ReqChannel.factory把结果回传 Masterreturn_pub见 salt/cli/caller.py#L563-L572。2.3 本地模式判定源码中is_local的判定条件salt/cli/caller.py#L263-L267决定了结果是否回传 Masteris_local ( self.opts[local] or self.opts.get(file_client, False) local or self.opts.get(master_type) disable )即满足以下任一条件即视为本地模式命令行带--local、minion 配置file_client: local、或配置master_type: disable。这与 Standalone Minion 教程 中介绍的两种 masterless 实践方式一一对应。三、基本用法SaltCallOptionParser定义的 usage 为%prog [options] function [arguments]salt/utils/parsers.py#L2821。常见示例# 本机执行 test.ping salt-call test.ping # 查看本机 grains salt-call grains.items # 本机应用 state连 Master 拉取 state 数据 salt-call state.apply # 完全离线地本机应用 state salt-call --local state.apply # 查看某个模块的文档 salt-call -d state.apply # 查看 test 模块下所有函数的文档 salt-call -d test参数解析有个强制约束_mixin_after_parsedsalt/utils/parsers.py#L3019-L3032必须提供函数、--grains或--doc三者之一否则打印帮助并报错-g/--grains不接受任何参数-d/--doc一次只能查询一个函数。函数名与参数分别存入config[fun]与config[arg]。四、通用选项Common Options以下选项在 doc/ref/cli/_includes/common-options.rst 中定义所有 Salt CLI 通用选项说明--version打印当前 Salt 版本--versions-report打印程序依赖与版本号后退出-h, --help显示帮助信息并退出-c CONFIG_DIR, --config-dirCONFIG_DIR指定 Salt 配置目录含 master/minion 配置文件多数系统默认为/etc/salt五、核心选项详解以下选项均在 salt/utils/parsers.py#L2830-L3017 的_mixin_setup()中注册默认值与源码逐一对应。5.1 执行模式--local本地执行如同没有 Master 运行。设置后config[file_client] localsalt/cli/call.py#L67-L68不联系 Master 获取文件与 pillar 数据也不回传结果。--masterMASTER指定要使用的 Master。Minion 必须已与该 Master 完成认证省略时使用 minion 配置中的 master 选项若配置了多 Master则使用第一个响应的 Master。--idID指定本次调用使用的 minion id省略时取 minion 配置中的 id 选项。5.2 数据源覆盖仅--local下生效这三组选项用于 Standalone 场景下覆盖本机数据根目录均可重复指定多次--file-rootFILE_ROOT设置基础 file root。源码会把每个值转为绝对路径并展开 glob组装为config[file_roots] {base: [...]}salt/cli/call.py#L23-L28。--pillar-rootPILLAR_ROOT设置基础 pillar root逻辑同上salt/cli/call.py#L30-L35。--states-dirSTATES_DIR设置额外搜索 state 的目录salt/cli/call.py#L37-L42。⚠️ 再次强调不带--local时这三组选项会被忽略并打印警告数据仍从 Master 获取。5.3 模块与信息查看-m MODULE_DIRS, --module-dirsMODULE_DIRS额外指定模块加载目录可多次传递-m/--module-dirs加载多个目录。-d, --doc, --documentation打印指定模块的文档不指定模块则打印全部模块文档。底层由Caller.print_docs()遍历self.minion.functions实现salt/cli/caller.py#L67-L78。-g, --grains返回 Salt grains 生成的信息。底层由Caller.print_grains()调用salt.loader.grains并交给 grains 输出器展示salt/cli/caller.py#L80-L85。--skip-grains不加载 grains。--refresh-grains-cache强制刷新 grains 缓存。5.4 返回行为控制--return RETURNER把返回数据交给一个或多个 returner 接口多 returner 用逗号分隔returner1,returner2。源码按,拆分后逐个调用self.minion.returnersf{returner}.returnersalt/cli/caller.py#L268-L283单个 returner 失败会被吞掉并继续。--no-return-event不向 Master 回传 return 事件。对应源码中if not is_local and not self.opts.get(no_return_event, False):的分支salt/cli/caller.py#L286。--metadata同时打印执行元数据outputter 数据、返回码等与返回结果。--print-metadata为 True 时直接输出完整ret含 jid、retcode 等输出器固定为nestedsalt/cli/caller.py#L103-L107。--set-metadataMETADATA源码补充项把元数据传入 Salt用于 job 检索元数据会出现在回传 Master 的载荷中salt/cli/caller.py#L160-L162。--retcode-passthrough以 salt call 自身的返回码退出而不是 salt 二进制的返回码。对应源码sys.exit(ret[retcode])分支salt/cli/caller.py#L115-L118详见下文退出码一节。--hard-crash抛出任何原始异常而非优雅退出默认 False。此默认值还受环境变量SALT_HARD_CRASH影响salt/utils/parsers.py#L509-L513。5.5 其他源码确认的选项-t, --timeout变更适用命令的超时认证超时默认 60 秒。--output-diff只报告发生变更的 state对应state_output_diff。--privUSER指定以哪个用户名运行 salt-call覆盖config[user]同时影响verify_env校验目录属主时的判定逻辑salt/cli/call.py#L81-L112。六、资源分发选项-r/--resources3008.0 新增从 Salt 3008.0 开始salt-call支持把一次调用**分发到被管理的资源managed resources**上-r, --resources除了管理 Minion 本身还把函数分发到匹配的所有资源上。不带-r时salt-call只在管理 Minion 上运行函数并返回单个裸值保持旧脚本行为带-r时函数针对--tgt匹配到的每个资源执行结果为以资源 id 为键的字典主机本身以管理 Minion id 为键。--tgtTGT目标表达式仅在-r/--resources同时传入时生效默认*匹配管理 Minion 与全部被管理资源。--tgt-typeTGT_TYPE目标表达式类型仅在-r同时传入时生效对应 Master CLI 的-t/--target-type。按 salt/utils/parsers.py#L3006-L3016 的choices校验当前合法值为glob默认、list、compound、grain、grain_pcre、pcre。实现层面由BaseCaller._call_with_resources()完成salt/cli/caller.py#L299-L448先通过Minion._resolve_resource_targets依据 pillaropts[resources]与各资源的 grains 缓存解析目标列表若目标是纯T/M复合表达式则管理 Minion 本身不再执行每个资源通过其类型对应的 resource loader 执行并临时把__grains__切换为该资源的 grains。对state.apply、state.highstate等合并类函数各资源返回的 state dict 会以资源 id 前缀 state id的方式合并进管理 Minion 的结果与 Master 端合并输出完全一致单个资源失败时以no_|-rid_|-rid_|-None键标记。七、日志选项Logging Options日志选项覆盖配置文件中的对应设置定义于 doc/ref/cli/_includes/logging-options.rst选项说明-l LOG_LEVEL, --log-levelLOG_LEVEL控制台日志级别取值为all、garbage、trace、debug、info、warning、error、quiet默认warning--log-fileLOG_FILE日志文件路径默认/var/log/salt/minion--log-file-levelLOG_LEVEL_LOGFILE日志文件级别取值同上默认warning这些默认值来自salt.config.DEFAULT_MINION_OPTS见 salt/utils/parsers.py#L2827-L2828 与 salt/config/init.py。排查问题时常用-l debug或-l trace观察函数执行的详细日志生产环境用默认warning避免刷屏。八、输出选项Output Options输出选项定义于 doc/ref/cli/_includes/output-options.rst--out指定输出器outputter展示返回数据可选highstate、json、key、overstatestage、pprint、raw、txt、yaml等完整列表见 输出器参考 目录下的各输出器文档。若所选输出器不支持当前数据自动回退到 Pythonpprint。--out-indent/--output-indent按指定空格数缩进输出负值禁用缩进仅对支持缩进的输出器生效。--out-file/--output-file把输出写入指定文件。--out-file-append/--output-file-append追加到指定文件。--no-color/--force-color禁用/强制彩色输出。彩色含义绿色成功红色失败蓝色变更且成功黄色预期未来的配置变更。--state-output/--state_output覆盖 minion 配置的state_output值取值full、terse、mixed、changes、filter默认none。每种模式可带两个后缀_id用 state ID 代替name显示如full_id、_color对变更区做统一 diff 着色如full_color后缀可组合如full_id_color。--state-verbose/--state_verbose覆盖配置的state_verbose设为 True 或 False默认 none。脚本化场景最常用--outjson或--outyaml结合--out-indent配合下文退出码使用。九、实战StandaloneMasterlessMinionsalt-call --local是无 Master 架构的基石。按 Standalone Minion 教程有两种实践方式方式一不运行 daemon按需调用salt-call --local。适用于仅需在初始化或人工触发时配置的主机离线环境、构建代理、单机环境、镜像构建流水线。例如# minion 配置 /etc/salt/minion 中设置 # file_client: local # file_roots: # base: # - /srv/salt # pillar_roots: # base: # - /srv/pillar salt-call --local state.apply方式二运行salt-minion但配置master_type: disable。当需要 beacon、engine、schedule 或本地 reactor 持续运行而无需连接 Master 时使用。注意默认情况下 salt-minion daemon 会尝试连接 Master 并失败从 2016.11.0 起设置master_type: disable即可让 daemon 无 Master 运行而salt-call本身不依赖 daemon。代码层面file_client: local或master_type: disable都会使is_local为真salt/cli/caller.py#L263-L267从而跳过结果回传。此外Standalone 下 minion 自身的 job 缓存可通过cache_jobs配置启用源码elif self.opts[cache_jobs]: salt.utils.minion.cache_jobs(...)salt/cli/caller.py#L293-L295。十、实战故障排查与脚本化salt-call最初就是为排查 Minion 问题而生的官方文档将其列为 Minion 故障排查 的首选工具。常见组合# 确认 Minion 本机函数栈是否正常 salt-call test.ping # 用 debug 日志定位加载或执行问题 salt-call -l debug state.apply # 查看模块文档确认参数签名 salt-call -d pkg.installed # 只打印变更适合核对 state 改动 salt-call state.apply --output-diff # 结构化输出供脚本消费 salt-call --local grains.items --outjson退出码语义salt/cli/caller.py#L103-L118执行结束后若指定--retcode-passthrough则直接以本次调用的 retcode 退出否则只要 retcode 非EX_OK就以EX_GENERIC退出。这意味着在 shell 脚本里可以用$?判断 state 是否成功salt-call --local state.apply if [ $? -eq 0 ]; then echo state 应用成功 else echo state 应用失败 fi另有一个用户相关的坑salt-call使用当前 shell 用户上下文执行若遇到cron 里执行失败、手动执行成功优先检查执行用户对cachedir/proc等目录的写权限——源码中写 proc 文件失败时会明确提示Cannot write to process directorysalt/cli/caller.py#L185-L190。若需以指定用户运行可用--privUSER配合系统sudo。十一、相关命令官方文档的 See also 部分指向同族命令的手册页仓库对应文档位于 CLI 参考索引salt(1)Master 端批量下发命令对应 salt 命令参考 之外的 Master CLI 文档salt-master(1)Master daemonsalt-minion(1)Minion daemon。与salt命令相比salt-call只作用于本机、无目标选择targeting概念也没有 Master 端的发布/订阅链因此非常适合作为快速验证与 Standalone 部署的执行引擎。两者的行为差异可参考 CLI 参考 下各命令的独立文档以及 tests/pytests/integration/cli/test_salt_call.py 中针对salt-call的集成测试用例其中覆盖了本地模式、返回码、grains/doc 输出等核心行为。赞分享运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载相关推荐Salt 的 data 执行模块minion 本地持久化数据仓库datastore完全指南Salt 的 data 执行模块minion 本地持久化数据仓库datastore完全指南 导读 salt.modules.data 是 Salt 内置的运维配置管理后端Salt Cloud 执行模块salt.modules.cloud完全指南在任意 Minion 上直接驱动 Salt CloudSalt Cloud 执行模块salt.modules.cloud完全指南在任意 Minion 上直接驱动 Salt Cloud 导读 本文围绕 Salt运维配置管理后端Salt Minion 守护进程完全指南salt-minion 命令行参考与启动原理解析Salt Minion 守护进程完全指南 salt minion 命令行参考与启动原理解析 导读 salt minion 是 Salt 配置管理体系中运行在被运维配置管理后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考