运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载导读saltutil是 SaltStack本仓库 salt/modules/saltutil.py中负责管理 Salt 自身的执行模块从文件服务器同步自定义模块、刷新 minion 的 pillar/grains/beacons、查询与终止正在运行的作业、清理缓存、重建密钥甚至允许运行在 master 上的 minion 反向调用 runner、wheel 和 salt 命令。本文基于官方 API 参考文档 doc/ref/modules/all/salt.modules.saltutil.rst该文档通过automodule指令完整渲染本模块的全部函数签名与文档字符串逐类讲解其全部功能、参数语义与底层实现帮助你掌握用一条salt命令远程治理 minion 自身的完整能力。说明saltutil全部函数都在 minion 侧执行部分函数要求该 minion 位于 master 之上通常通过salt target saltutil.function调用也可在 minion 本机用salt-call saltutil.function调用。模块声明了__proxyenabled__ [*]salt/modules/saltutil.py因此也适用于所有 proxy minion。一、自定义扩展模块同步体系sync_*家族Salt 允许用户在文件服务器的_modules、_states、_grains等特殊目录中放置自定义扩展模块saltutil.sync_*系列函数负责把这些模块从 master 的文件服务器同步到 minion 的扩展模块目录并默认触发对应的刷新动作。该文档以 doc/ref/modules/all/salt.modules.saltutil.rst 为入口完整列出了所有同步函数。1.1 同步函数总览函数同步源目录默认 refresh 动作引入版本sync_modulessalt://_modules刷新执行模块0.10.0sync_statessalt://_states刷新执行模块0.10.0sync_grainssalt://_grains刷新 pillar间接刷新模块0.10.0sync_rendererssalt://_renderers刷新执行模块0.10.0sync_returnerssalt://_returners刷新执行模块0.10.0sync_utilssalt://_utils刷新执行模块2014.7.0sync_beaconssalt://_beacons刷新 beacons2015.5.1sync_log_handlerssalt://_log_handlers刷新执行模块2015.8.0sync_pillarsalt://_pillar刷新 pillar仅 masterless minion2015.8.11, 2016.3.2sync_sdbsalt://_sdb无不触发刷新2015.5.8, 2015.8.3sync_proxymodulessalt://_proxy刷新执行模块2015.8.2sync_enginessalt://_engines刷新执行模块2016.3.0sync_cloudssalt://_cloud刷新执行模块2017.7.0sync_thoriumsalt://_thorium刷新执行模块2018.3.0sync_matcherssalt://_matchers刷新执行模块2019.2.0sync_serializerssalt://_serializers刷新执行模块2019.2.0sync_executorssalt://_executors刷新执行模块3000sync_topssalt://_tops刷新环境缓存仅 masterless minion3007.0sync_wrappersalt://_wrapper刷新执行模块仅 masterless minion3007.0sync_output别名sync_outputterssalt://_output刷新执行模块—sync_resourcessalt://_resources触发资源重新发现—1.2 统一参数语义绝大多数sync_*函数共享同一组参数以文档字符串为准saltenv文件服务器环境fileserver environment。传逗号分隔列表可同步多个环境例如saltenvbase,dev。若不传则会读取 top file 中配置的所有环境如果没有 top file则默认同步base环境。这一逻辑由模块内的_get_top_file_envs()实现salt/modules/saltutil.py它实例化salt.state.HighState读取 top file并将结果缓存在上下文键saltutil._top_file_envs源码常量TOP_ENVS_CKEY中以避免重复解析若渲染 top file 失败会抛出CommandExecutionError。refresh默认True同步完成后是否刷新对应资源。文档明确说明即使没有新模块被同步也会执行刷新设False可跳过。例如sync_modules的 refresh 会调用refresh_modules()sync_grains的 refresh 会调用refresh_pillar()因为 pillar 刷新内部会完成模块刷新。extmod_whitelist/extmod_blacklist默认None逗号分隔的模块名单按类型限定只同步哪些或排除哪些。对于sync_all这两个参数则是字典形式如extmod_whitelist{modules: [custom_module]}。clean_pillar_cache默认Falsesync_grains、sync_pillar、sync_all、refresh_grains独有设为True时同时刷新 pillar 缓存。1.3 底层同步机制所有同步函数最终都汇聚到私有辅助函数_sync()salt/modules/saltutil.py它调用 salt/utils/extmods.py 中的salt.utils.extmods.sync()完成实际工作解析白名单/黑名单字符串会被按逗号拆分字典则按类型分别匹配通过fileclient.cache_dir()从salt://_form下载文件到本地缓存只匹配.py、.pyx、.so、.zip后缀对比目标文件哈希hash_type默认取自 opts有变化才覆盖写入并将form.relname追加到返回列表若设置了clean_dynamic_modules: Trueminion 配置项会递归清理扩展模块目录中已从文件服务器消失的文件与空目录保持两侧严格一致返回(ret, touched)touched为真时_sync会在cachedir/module_refresh下创建一个占位文件作为需要重载模块的信号同步 grains 时还会清除磁盘上的grains.cache.p见_clear_grains_cache()salt/modules/saltutil.py防止grains_cache开启时读到过期数据对应 tests/pytests/functional/modules/test_saltutil.py 中针对 issue #55667 的回归测试。1.4 特别注意事项masterless 限制sync_pillar、sync_tops、sync_wrapper在传统非 masterlessminion 上执行会直接抛出CommandExecutionError因为__opts__[file_client] ! local。其中sync_tops在refreshTrue时还会先清除TOP_ENVS_CKEY缓存再同步salt://_tops。state 中调用必须带 refresh文档特别强调如果用module.runstate 调用sync_modules/sync_all由于 SLS 渲染已完成新同步的模块在本次运行中不可见必须显式传refresh: Trueload_my_custom_module: module.run: - name: saltutil.sync_modules - refresh: True1.5 一键同步全部sync_allsync_all在一个调用里按依赖顺序同步所有扩展模块类型salt/modules/saltutil.pymasterless minion 先同步 tops因为它可能影响后续同步的环境选择随后依次同步 clouds、beacons、modules、states、sdb、grains、renderers、returners、output、utils、log_handlers、executors、proxymodules、engines、thorium、serializers、matchers、resourcesmasterless minion 再追加 pillar 与 wrapper。refreshTrue时最后统一执行一次refresh_pillar()内部已完成模块刷新避免重复刷新。返回的字典以类型为键、以各自同步结果为值。salt * saltutil.sync_all salt * saltutil.sync_all saltenvdev salt * saltutil.sync_all saltenvbase,dev salt * saltutil.sync_all extmod_whitelist{modules: [custom_module]}1.6 查看已同步的扩展模块list_extmodslist_extmods遍历cachedir/extmods目录按模块类型分组列出所有已同步到本 minion 的外部模块名文件去扩展名便于核对哪些扩展确实已落地salt * saltutil.list_extmods二、运行时资源刷新refresh_*家族刷新类函数不涉及文件传输而是向 minion 自身的事件总线发送事件让 minion 内部重新加载对应数据。2.1refresh_modules异步与同步两种模式向 minion 发送module_refresh事件以重载执行模块与 grains。默认异步salt * saltutil.refresh_modules立即返回。如需阻塞等待刷新完成传asyncFalse——此时函数会先挂起一个事件监听器再触发携带notify: True的刷新事件并阻塞等待MINION_MOD_REFRESH_COMPLETE事件超时 30 秒后返回salt/modules/saltutil.py。2.2refresh_pillar发送pillar_refresh事件刷新 minion 内存中的 pillar 数据详见文档引用的 pillar-in-memory 机制wait默认False设为True时阻塞等待刷新完成timeout默认30waitTrue时最多等待的秒数clean_cache默认True3005 版本新增清理 pillar 缓存仅在pillar_cache开启时生效。salt * saltutil.refresh_pillar salt * saltutil.refresh_pillar waitTrue timeout60注意本模块同时用pillar_refresh salt.utils.functools.alias_function(refresh_pillar, pillar_refresh)导出了别名salt/modules/saltutil.py文档页通过:exclude-members: pillar_refresh将别名排除在 API 列表之外避免重复展示但两者完全等价、均可调用。2.3refresh_grains刷新 minion 的 grains但不从salt://_grains同步新模块文档提醒该过程会顺带重载可用执行模块因为 grains 可能影响模块是否可用。参数refresh_pillar默认True设为False阻止 pillar 一并刷新clean_pillar_cache默认False设为True刷新 pillar 缓存。实现上先清除磁盘 grains 缓存再刷新salt/modules/saltutil.py这正是 tests/pytests/functional/modules/test_saltutil.py 所覆盖的 #55667 回归场景。salt * saltutil.refresh_grains2.4refresh_beacons与refresh_matchers分别发送beacons_refresh与matchers_refresh事件让 minion 重新加载 beacon 配置与匹配器matchers定义。若事件模块不可用如某些 proxy 场景会记录错误并返回False等效于 no-opsalt * saltutil.refresh_beacons salt * saltutil.refresh_matchers2.5refresh_resources触发resource_refresh事件minion 收到后基于当前 pillar 数据重新执行_discover_resources()并将发现的资源重新注册到 master 的minion_resources缓存中——适用于需要动态上报托管资源的场景通常与sync_resources配合后者同步salt://_resources自定义资源模块后自动触发一次该刷新salt * saltutil.refresh_resources三、作业Job管理与进程信号控制3.1 查询运行状态running返回 minion 上所有正在运行的 Salt 进程数据含 jid、fun、pid、tgt 等字段底层委托 salt/utils/minion.py 的running()实现。is_running fun参数支持glob 通配返回匹配函数名的运行作业。例如salt * saltutil.is_running state.highstate可判断 highstate 是否正在执行。3.2 定位单个作业find_job jid返回指定 jid 的运行中作业信息。文档给出了完整输出示例含arg、fun、jid、pid、tgt、tgt_type、user字段若作业已完成则返回空字典。从源码看salt/modules/saltutil.py它先扫描running()随后还会检查cachedir下的state_queue与job_queue排队目录——队列文件按queued_timestamp_jid.p命名命中后返回带queued: True、pid: 0的结构避免把排队中作业误报为不存在。find_cached_job jid返回已缓存的作业结果。前提是 minion 配置了cache_jobs: True否则返回提示信息Local jobs cache directory not found; you may need to enable cache_jobs on this minion。数据从cachedir/minion_jobs/jid/return.p读取并反序列化。3.3 信号与终止signal_job jid sig向作业进程发送任意信号如15即 SIGTERM。若安装了psutil会递归向进程的所有子进程发送否则仅发送给主进程及其记录的child_pids。当目标进程已不存在时会清理cachedir/proc/jid残留文件并返回提示。未安装 psutil 时记录警告仍尝试以os.kill发送。term_job jid等价于signal_job jid SIGTERM终止单个作业。term_all_jobs向所有正在运行的作业发送 SIGTERM。kill_job jid发送 SIGKILL9。注意源码顶部兼容 Win32salt_SIGKILL在平台不支持SIGKILL时回退为SIGTERMsalt/modules/saltutil.py。kill_all_jobs向所有运行作业发送 SIGKILL。salt * saltutil.running salt * saltutil.is_running state.highstate salt * saltutil.find_job 20160503150049487736 salt * saltutil.term_job 20160503150049487736 salt * saltutil.kill_all_jobs四、缓存清理与密钥管理4.1clear_cache强制删除 minion 的所有缓存遍历整个cachedir。文档给出了明确的安全警告最安全的清缓存方式是先停止 minion、删除缓存文件、再重启 minion。执行时若某个文件删除失败会立即返回False。该函数自 2014.7.0 引入。4.2clear_job_cache按时间阈值清理作业缓存目录cachedir/minion_jobs下超过指定小时数的子目录目录 mtime 早于now - hours * 3600即被整目录删除默认hours24自 2018.3.0 引入。适合在长期运行的 minion 上回收磁盘空间salt * saltutil.clear_cache salt * saltutil.clear_job_cache hours124.3regen_keys与revoke_authregen_keys删除pki_dir通常为/etc/salt/pki/minion下的所有密钥文件随后重建与 master 的请求通道ReqChannel以强制重新生成 minion 密钥。典型用途是重命名/迁移 minion 或重置认证执行后 minion 需重新在 master 上被接受。revoke_authminion 主动向 master 发送revoke_auth请求让 master 撤销它自己的密钥。文档特别提醒该命令执行后 minion 会话被吊销可能无法把执行结果返回给 master。可选参数preserve_minion_cache默认False设为True时 master 保留该 minion 的缓存。实现会遍历master_uri_list多 master 场景逐个发送请求任一通道超时则整体返回False。salt * saltutil.regen_keys salt * saltutil.revoke_auth salt * saltutil.revoke_auth preserve_minion_cacheTrue五、Master 侧能力反调runner、wheel、cmd与mmodule这组函数允许运行在 master 之上的 minion或在 master 上执行salt-call反哺 master把 master 侧能力以执行模块的形式暴露出来。5.1runner name在 master 上执行 runner 函数自 2014.7.0 引入。文档要求必须通过运行在 master 上的 minion或在 master 上执行 salt-call来调用。支持arg、kwarg、full_return、saltenv默认base、jid等参数runner 函数若接受saltenv参数会自动注入对state.orchestrate/state.orch/state.sls会注入orchestration_jid以衔接编排作业。salt master_minion saltutil.runner jobs.list_jobs salt master_minion saltutil.runner test.arg arg[baz] kwarg{foo: bar}5.2wheel name [args]在 master 上执行 wheel 模块函数自 2014.7.0 引入要求目标 minion与 master 位于同一主机。文档明确指出若对非本机 minion 调用将得到空返回——远程 minion 无法访问 wheel 函数及其返回数据。salt my-local-minion saltutil.wheel key.accept jerry salt my-local-minion saltutil.wheel minions.connected5.3 权限对齐细节源码级补充从源码看runner/wheel在 minion 进程内执行 master 侧函数而自 3006 起 master 默认以salt用户运行见_master_user_runas注释中的 issue #67716。为让 master 侧函数如 git_pillar/gitfs 缓存、pki 目录访问以 master 配置用户而非 root 执行模块实现了完整的降权运行链路salt/modules/saltutil.py_master_user_runas()校验opts[user]是否为真实账号——因为state.orchestrate会把发布用户如sudo_login写入__opts__[user]这类伪用户会被pwd.getpwnam校验拦截并跳过降权issue #69600_client_cmd_as()用fork上下文创建子进程在子进程中执行chugid降权并通过队列回传结果子进程刻意不守护化daemon 进程不允许再派生子进程会影响编排中的parallel: True状态父进程同时监听结果队列与子进程存活子进程异常退出os._exit、OOM、libgit2 段错误时抛出CommandExecutionError而非永久阻塞_align_runas_environment()在降权后修正HOME/USER/LOGNAME并刷新 libgit2/pygit2 的全局配置搜索路径避免 gitfs/git_pillar 读取到 root 的/root/.gitconfig而出错。5.4cmd与cmd_iter假设当前 minion 同时也是 master执行一条完整的 salt 命令并聚合所有目标 minion 的返回。参数包括tgt、fun、arg元组、timeout、tgt_type目标匹配类型默认glob2017.7.0 起由expr_form更名而来、retreturner、kwarg、ssh是否走 salt-ssh另支持batch与subset模式源码_exec分别切换到client.cmd_batch与client.cmd_subset。cmd_iter以生成器逐批产出返回适合流式处理。cmd在返回为空且配置文件为 minion 时还会尝试读取同目录的master配置重试一次。5.5mmodule saltenv fun加载指定环境下的 minion 模块使该环境的 pillar 在渲染时能使用其自定义_modules中的函数。实现依赖单例类_MMinionsalt/modules/saltutil.py按saltenv缓存MasterMinion实例构建时将file_roots中该环境的_modules目录注入module_dirs并重新生成模块同时保存/恢复全局__grains__保证调用上下文仍是 minion 视角salt * saltutil.mmodule base test.ping六、minion 自升级updateupdate从opts[update_url]更新 minion 自身文档示例指向 Broadcom 提供的官方构建源https://packages.broadcom.com/artifactory/saltproject-generic/windows/。前提与限制源码可印证salt/modules/saltutil.py依赖eskyPython 模块模块头声明:depends: - esky未安装则返回Esky not available as importminion 必须运行bdist_esky 构建否则返回Minion is not running an Esky build必须配置update_url版本号可选缺省时通过app.find_update()查找最新版文档提醒 2014-8-11 起 esky 存在缺陷只能下载安装 update_url 中的最新版本更新完成后按update_restart_services配置逐个service.restart重启服务并返回Updated from 旧版本 to 新版本及重启结果。salt * saltutil.update salt * saltutil.update 0.10.3七、实战场景速查发布新自定义模块salt * saltutil.sync_all一键同步所有扩展类型只同步执行模块用salt * saltutil.sync_modules指定环境saltenvdev多环境saltenvbase,dev。自定义模块只改了一行不想同步时仅重载——salt * saltutil.refresh_modules同步并刷新——salt * saltutil.sync_utils。修改了 pillar 数据salt * saltutil.refresh_pillar需要同步_pillar自定义模块masterless minion——salt * saltutil.sync_pillar。业务代码临时变更 grainssalt * saltutil.refresh_grains refresh_pillarFalse只刷 grains 不动 pillar。highstate 卡住排查salt * saltutil.is_running state.*定位确认 jid 后salt * saltutil.term_job jid紧急情况salt * saltutil.kill_all_jobs。minion 证书过期/更换salt * saltutil.regen_keys随后在 master 重新salt-key -a。master 侧运维操作在 master 本机salt-call saltutil.runner jobs.list_jobs或salt my-local-minion saltutil.wheel key.list_all。长期运行 minion 磁盘回收salt * saltutil.clear_job_cache hours24彻底清理salt * saltutil.clear_cache先停 minion 更安全。八、延伸阅读模块完整源码salt/modules/saltutil.py底层文件同步实现salt/utils/extmods.py官方 API 文档页doc/ref/modules/all/salt.modules.saltutil.rst功能级测试含 grains 缓存回归tests/pytests/functional/modules/test_saltutil.py与模块加载机制相关的集成测试tests/integration/loader/test_ext_modules.py赞分享运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载相关推荐Sway 如何用 [test(should_revert)] 编写预期回滚的单元测试Sway 如何用 test should_revert 编写预期回滚的单元测试 在 Sway 中给本应失败的代码路径写单元测试时断言应当不成立、合约调用运维配置管理后端Salt 执行模块 gpg 完全指南密钥链管理、加密签名与信任模型实战Salt 执行模块 gpg 完全指南密钥链管理、加密签名与信任模型实战 本文围绕 Salt 的 gpg 执行模块 salt/modules/gpg.py h运维配置管理后端Salt macOS keychain 模块实战指南用 Salt 管理 macOS 钥匙串中的证书Salt macOS keychain 模块实战指南用 Salt 管理 macOS 钥匙串中的证书 Salt 的 keychain 执行模块 salt/mo运维配置管理后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考