Salt Python Client API 全解析用*Client()接口编程化驱动 Salt【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/saltSalt 为 Python 应用提供了多套程序化接入入口统称为*Client()API。本文以仓库官方文档 doc/ref/clients/index.rst 为核心脉络系统梳理这些 Client 各自的职责边界master 侧、minion 侧、runner、wheel、cloud、ssh并下沉到源码层salt/client/init.py、salt/config/init.py、salt/loader/init.py 等讲解其工作原理与调用前提。读完本文你将掌握如何获取opts配置字典、如何手动加载模块Loader 接口、以及在不同场景下应该选用哪一个 Client 类、如何调用其核心方法如cmd、run_job、cmd_async、cmd_batch。概述Salt 的编程化接入点Salt 提供了多个用于与 Python 应用交互的入口点这些入口点通常被称为*Client()API。每个 Client 访问 Salt 的不同部分——或从 master 侧发起或从 minion 侧发起。文档中逐个对每个 Client 进行了说明核心列表如下Client 类定义位置对应 CLI 工具运行位置典型用途LocalClientsalt/client/init.pysaltmaster向 minion 下发执行模块命令并收集返回Callersalt/client/init.pysalt-callminion在本机执行执行模块无需守护进程ProxyCallersalt/client/init.py—proxy minion面向 proxy minion 的本机调用RunnerClientsalt/runner.pysalt-runmaster调用 runner 模块WheelClientsalt/wheel/init.py—master调用 wheel 模块master 管理类操作CloudClientsalt/cloud/init.pysalt-cloudmaster云主机生命周期管理SSHClientsalt/client/ssh/client.pysalt-sshmaster通过 SSH 无代理执行Tiamat 打包运行时说明官方文档专门提示对于 Tiamat 打包分发的 Salt 发行版必须使用其自带的 Python 运行时来执行脚本因为系统 Python 无法访问 Salt 内部模块。有两种执行方式直接运行/path/to/salt python script.py使用 shebang在脚本首行写#!/path/to/salt python其他编程化途径seealso除*Client()之外Salt 还提供多种程序化访问方式文档明确列举Outputter 系统通过 doc/ref/output 中定义的输出器将 Salt 的返回数据格式化为 JSON、shell 友好文本或其它多种格式方便程序消费结构化数据事件总线使用state.eventrunner定义于 salt/runners/state.py可从 shell 脚本或程序中消费 Salt 的事件流netapi 模块通过 REST 接口从外部访问 Salt详见 doc/ref/netapi。获取 Salt 的opts字典部分 Client 需要访问 Salt 的opts字典——即 master 配置文件conf/master或 minion 配置文件conf/minion的字典化表示。文档给出的常见模式是优先读取环境变量否则从默认位置加载配置文件。salt.config.client_config加载 master 侧客户端配置定义于 salt/config/init.py#L4650import salt.config master_opts salt.config.client_config(/etc/salt/master)该函数返回「与本地运行的 Salt Master 守护进程通信所需的必要选项」字典。从源码看它做了以下几件关键事情以DEFAULT_MASTER_OPTS为默认值通过master_config()加载 master 配置文件进一步叠加用户级配置优先读取 XDG 配置目录下的saltrc否则读取用户主目录下的.saltrc支持通过环境变量覆盖处理token_file令牌文件与令牌有效性默认有效期token_expire为 43200 秒将interface为0.0.0.0/::的情况规整为回环地址保证 master 运行在 localhost 时能够被正确寻址若未显式设置master_uri则按tcp://{interface}:{ret_port}自动构造最终返回OptsDict。该函数适合 master 侧操作例如实例化LocalClient。salt.config.minion_config加载 minion 配置定义于 salt/config/init.py#L2686import salt.config minion_opts salt.config.minion_config(/etc/salt/minion)该函数读取 minion 配置文件并设置特殊选项适用于 minion 侧操作如Caller类和手动运行 Loader 接口。源码要点默认值来自DEFAULT_MINION_OPTS通过环境变量SALT_MINION_CONFIG或SALT_CONFIG_DIR自动定位配置文件路径使用include_config()处理default_include默认的*.d目录与显式include配置实现配置合并通过apply_minion_config()完成默认值合并与特殊选项加工返回OptsDict并设置__role字段默认为minion可传master实现 master 模式下加载 minion 配置。说明opts字典的获取是所有 Client 使用的基础。LocalClient/SSHClient默认通过client_config加载Caller/ProxyCaller默认通过minion_config或proxy_config加载同时所有 Client 都支持传入mopts参数直接注入现成的opts字典跳过文件读取。Salt 的 Loader 接口手动加载模块Salt 生态中的模块使用自定义 Loader 系统加载到内存中。这一机制允许模块声明条件依赖操作系统、系统版本、已安装库等并允许 Salt 注入特殊变量__salt__、__opts__等。大多数模块都可以被手动加载这在第三方 Python 应用或编写测试时非常有用。但部分模块要求底层存在完整、运行的 Salt 系统——尤其是负责 master 到 minion 通信的模块如salt.modules.minesalt/modules/mine.pysalt.modules.publishsalt/modules/publish.pysalt.modules.peersalt/modules/peer.py如果手动加载这些模块时遇到报错KeyError: master_uri文档明确指出这就是「缺少完整运行环境」的典型信号。此时应改用salt.client.Caller类来执行这些模块而不是直接手动加载。每种模块类型都有对应的加载函数全部定义于 salt/loader/init.py加载函数定义位置加载目标salt.loader.minion_modssalt/loader/init.py#L390minion 上的执行模块execution modulessalt.loader.raw_modsalt/loader/init.py#L557单个模块原始加载不注入完整环境salt.loader.statessalt/loader/init.py#L1133state 模块salt.loader.grainssalt/loader/init.py#L1490grains 数据salt.loader.grain_funcssalt/loader/init.py#L1400自定义 grain 函数以minion_mods为例LocalClient在初始化时正是通过salt.loader.minion_mods(self.opts, utilsself.utils)加载全部执行模块见 salt/client/init.py#L384这也是LocalClient能在 master 侧解析执行模块函数的关键一步。Client 接口详解LocalClientmaster 侧的命令下发接口LocalClientsalt/client/init.py#L285是 master 上saltCLI 工具使用的接口用于向 minion 发送命令、执行执行模块并收集返回结果。文档列出的成员方法包括cmdrun_jobcmd_asynccmd_subsetcmd_batchcmd_itercmd_iter_no_blockget_cli_returnsget_event_iter_returns使用前提源码 docstring 明确要求必须在 Salt Master 所在的同一台机器上、以运行 Salt Master 的同一用户身份导入和使用除非配置了external_auth并在执行时携带认证凭据。基本用法import salt.client local salt.client.LocalClient() local.cmd(*, test.fib, [10])构造函数签名salt/client/init.py#L315支持以下关键参数c_path配置文件的路径默认指向syspaths.CONFIG_DIR下的mastermopts直接传入 opts 字典传入后将不再读取配置文件skip_perm_errors是否忽略加载密钥时的权限错误io_loop/keep_loopTornado IOLoop 相关用于异步事件获取auto_reconnect事件订阅断开时是否自动重连versionadded 3004listen是否持续监听事件直到调用destroyversionadded 3004。重要注意事项Tornado IOLoopLocalClient内部使用 Tornado IOLoop。如果在既有 IOLoop 环境中使用LocalClient会产生冲突——要么在创建LocalClient之前创建 IOLoop要么在创建 IOLoop 时使用ioloop.current()会返回LocalClient创建的 ioloop。从实现上看LocalClient初始化时还会读取 master 的轮转认证密钥__read_master_key缓存于cachedir下以.{user}_key命名的文件中并加载 utils、执行模块与 returner为后续命令下发与结果回收做准备。Callerminion 侧的本机调用接口Callersalt/client/init.py#L2338是 minion 上salt-call命令行工具使用的同一接口。与LocalClient不同它不需要 master 或 minion 守护进程正在运行——salt-call --local的本质只是把file_client设为local在 Python 层面同样可以做到。使用前提必须在 Salt Minion 所在的同一台机器上、以运行 Salt Minion 的同一用户身份使用。import salt.client caller salt.client.Caller() caller.cmd(test.ping)cmd方法versionchanged 2015.8.0 起与其它 Client 保持一致命名用于调用执行模块caller.cmd(test.arg, Foo, Bar, bazBaz) caller.cmd(event.send, myco/myevent/something, data{foo: Foo}, with_env[GIT_COMMIT], with_grainsTrue)也支持直接传入moptsversionadded 2014.7.0例如将 minion 配置加载后切换为 local 模式import salt.client import salt.config __opts__ salt.config.minion_config(/etc/salt/minion) __opts__[file_client] local caller salt.client.Caller(mopts__opts__)源码实现中Caller通过内部创建salt.minion.SMinionsalt/minion.py完成 opts 初始化与模块装载cmd方法本质上就是self.sminion.functionsfun。当需要执行mine、publish、peer这类依赖完整运行环境的模块时正是通过Caller来规避KeyError: master_uri问题。ProxyCallerproxy minion 的本机调用接口ProxyCallersalt/client/init.py#L2416与Caller类似但面向proxy minion——即管理无法直接安装 Salt minion 的设备如网络设备的代理进程。其默认配置路径指向proxy配置文件核心成员方法同样为cmd。proxy minion 的架构与使用可参考 doc/topics/proxyminion 与 doc/ref/proxy。RunnerClient调用 runner 模块RunnerClientsalt/runner.py#L23用于调用 runner 模块——即 master 侧执行管理任务的模块对应salt-run工具。它继承自salt.client.mixins.SyncClientMixin与AsyncClientMixinsalt/client/mixins.py因此同时具备同步与异步两套调用能力。文档列出的成员方法cmdasynchronouscmd_synccmd_async典型用法import salt.runner runner salt.runner.RunnerClient(master_opts) ret runner.cmd_sync(jobs.list_jobs)runner 模块的完整列表可查阅 salt/runners/ 目录如jobs、state、manage、cache等对应文档见 doc/ref/runners。WheelClient调用 wheel 模块WheelClientsalt/wheel/init.py#L19用于调用 wheel 模块——master 侧的管理类操作如密钥管理key、配置管理config等。它与RunnerClient一样继承同步/异步 mixin成员方法一致cmdasynchronouscmd_synccmd_asyncwheel 模块列表见 salt/wheel/ 目录对应文档见 doc/ref/wheel。CloudClient云主机生命周期管理CloudClientsalt/cloud/init.py#L172是salt-cloud的编程化接口用于在 Python 中管理云主机创建、销毁、查询、镜像与配置文件管理等。它通过云 provider 配置见 conf/cloud.providers.d/与云 profile 配置见 conf/cloud.profiles.d/工作。示例import salt.cloud cloud salt.cloud.CloudClient(/etc/salt/cloud) nodes cloud.map()云相关的完整文档见 doc/topics/cloud。SSHClient无代理的 salt-ssh 接口SSHClientsalt/client/ssh/client.py#L15为通过 salt-ssh 后端执行任务提供客户端对象versionadded 2015.5.0。文档列出的成员方法为cmd、cmd_iter。它默认从 master 配置文件c_path加载 opts并可通过disable_custom_roster禁用自定义 rostersalt-api 场景下强制禁用自定义 roster 以保障安全。salt-ssh 使用 SSH 通道执行命令不需要在目标机器上安装 minion适用于无法部署代理的场景相关用法见 doc/topics/ssh。如何选择合适的 Client根据文档的划分逻辑与源码实现可以按「操作发生的位置 目标对象」快速决策向一批 minion 下发执行模块命令、并需要聚合返回结果→LocalClientmaster 侧需守护进程或事件总线在单台 minion 本机执行模块、无需守护进程→Callerproxy 场景用ProxyCaller执行 master 侧 runner 管理任务→RunnerClient执行 master 侧 wheel 管理操作密钥、配置等→WheelClient管理云主机→CloudClient通过 SSH 无代理执行→SSHClient。所有 Client 都遵循同一模式要么显式传入mopts字典来源即salt.config.client_config/salt.config.minion_config/salt.config.proxy_config要么通过默认路径自动加载配置初始化完成后通过统一的cmd或cmd_sync/cmd_async方法发起调用。掌握opts获取与 Loader 机制这两个底层能力后无论是编写自动化脚本、第三方应用集成还是为 Salt 编写测试都可以做到有的放矢。【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址: https://gitcode.com/gh_mirrors/sa/salt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考