Salt 官方 dsc_resource 执行模块实战：绕过 LCM 直接调用 PowerShell DSC 资源

运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载导读dsc_resource是 Salt 在 3008.1 版本引入的 Windows 执行模块Execution Module它让 Salt 可以直接调用系统中已安装的任意 PowerShell DSCDesired State Configuration期望状态配置资源而无需编译 MOF 文件、也无需经过 DSC 的 Local Configuration ManagerLCM。本指南基于仓库中的 win_dsc_resource.py 及其配套单元测试 test_win_dsc_resource.py完整讲解该模块的三大核心函数get/test/set、Python 与 PowerShell 之间的类型转换机制、安装 DSC 资源的前置步骤以及底层PowerShellSession的运行原理。读完本文你将能在自己的 Salt Windows 环境中直接查询、校验并应用任意 DSC 资源。一、模块定位DSC 资源的三种执行方式Windows PowerShell DSC 有两种经典的配置应用路径完整 Configuration 方式把 DSC 配置写成.ps1脚本或编译成 MOF 文件再由 LCM 调度执行。Salt 中对应的传统模块是 win_dsc.py虚拟名dsc它通过dsc.compile_configdsc.apply_config把脚本推到 Minion 上执行直接调用资源方式绕过 MOF 与 LCM直接在 PowerShell 中用Invoke-DscResource命令对某个已安装的 DSC 资源执行Get/Test/Set三种方法。dsc_resource模块实现的就是第二种方式。模块 docstring 明确指出其价值见 win_dsc_resource.py该模块允许 Salt 在不编译 MOF 文件、不涉及 Local Configuration ManagerLCM的前提下直接应用apply、测试test并读取get任何已安装的 PowerShell DSC 资源的状态。这一设计让 DSC 资源变成与 Salt 原生执行模块一样可直接调度的能力既可以在 Salt CLI 上即时执行也可以被 State 模块如 win_dsc 状态若存在或其他编排逻辑复用同时避免了 MOF 编译、LCM 元配置等额外复杂度。二、安装与依赖检查2.1 硬性依赖dsc_resource的加载依赖有三个见 win_dsc_resource.py依赖作用安装/前置条件Windows 平台模块仅在 Windows 上可用由__virtual__强制校验pythonnetclr库让 Python 进程内加载 .NET 程序集pip install pythonnetPowerShell SDKSystem.Management.Automation提供进程内 PowerShell Runspace随 Windows PowerShell 5.0 提供__virtual__()函数win_dsc_resource.py依次检查这三项任一不满足都会返回(False, 原因)拒绝加载非 Windows 系统返回DSC Resource: Only available on Windows systems缺少 pythonnet 返回DSC Resource: Requires pythonnet (pip install pythonnet)缺少 PowerShell SDK 返回DSC Resource: Requires the PowerShell SDK (System.Management.Automation)。2.2 使用 psget 安装 DSC 资源模块 docstring 明确指出在使用某个 DSC 资源前先用psget模块从 PowerShell Gallery 安装对应的资源模块见 win_dsc_resource.py。psget是 Salt 的 PowerShellGet 管理模块win_psget.py常用操作包括# 引导 NuGet 包提供程序 salt win01 psget.bootstrap # 查看可用的 DSC 资源模块 salt win01 psget.avail_modules # 从 PowerShell Gallery 安装某个资源模块例如 xPSDesiredStateConfiguration salt win01 psget.install xPSDesiredStateConfiguration # 指定版本 / 作用域 / 私有仓库安装 salt win01 psget.install MyModule required_version1.23.2 scopeCurrentUser repositoryMyRepo # 更新已安装的模块 salt win01 psget.update MyModulepsget.install底层调用Install-Module -Force并将minimum_version/required_version/scope/repository等参数透传给 PowerShell见 win_psget.py。安装成功后dsc_resource即可按模块名引用其中的资源。三、核心函数get / test / setdsc_resource的三个公开函数与 DSC 资源的三个标准方法一一对应均由Invoke-DscResource实现。三者共享相同的前三个参数参数类型必填说明namestr是DSC 资源名如File、WindowsFeature、Servicemodule_namestr是资源所属的 PowerShell 模块名内置资源用PSDesiredStateConfiguration第三方资源用其模块名如xPSDesiredStateConfigurationpropertiesdict是资源属性字典用于标识资源实例或描述期望状态具体键随资源而异三个函数都会先做参数校验name/module_name为空或properties不是 dict 时抛出SaltInvocationError见 win_dsc_resource.py 等。此外模块通过__func_alias__win_dsc_resource.py把内部函数名set_对外暴露为set从而避开 Python 关键字冲突。3.1 get —— 查询资源当前状态get调用Invoke-DscResource -Method Get返回资源当前属性的完整字典见 win_dsc_resource.py# 查询 C:\Temp\test.txt 当前状态 salt * dsc_resource.get File PSDesiredStateConfiguration \ properties{DestinationPath: C:\\Temp\\test.txt, Ensure: Present} # 查询 Web-Server 功能IIS是否已安装 salt * dsc_resource.get WindowsFeature PSDesiredStateConfiguration \ properties{Name: Web-Server, Ensure: Present}实现上properties会先被转换为 PowerShell 哈希表见下文第四节随后拼接出如下命令并通过PowerShellSession.run_json执行win_dsc_resource.pyInvoke-DscResource -Name File -ModuleName PSDesiredStateConfiguration -Method Get -Property {...} | Select-Object * -ExcludeProperty Cim*, PSComputerName注意末尾的Select-Object * -ExcludeProperty Cim*, PSComputerName它把 CIM 相关的元数据属性和PSComputerName从结果中剔除让返回给 Salt 的字典更干净、更可序列化。3.2 test —— 校验资源是否处于期望状态test调用Invoke-DscResource -Method Test返回布尔值True表示资源已在期望状态False表示需要变更见 win_dsc_resource.py# 校验文件是否已存在 salt * dsc_resource.test File PSDesiredStateConfiguration \ properties{DestinationPath: C:\\Temp\\test.txt, Ensure: Present} # 校验 Web-Server 功能是否已启用 salt * dsc_resource.test WindowsFeature PSDesiredStateConfiguration \ properties{Name: Web-Server, Ensure: Present}与get不同test执行的是外层包了圆括号取.InDesiredState属性的表达式win_dsc_resource.py(Invoke-DscResource -Name File -ModuleName PSDesiredStateConfiguration -Method Test -Property {...}).InDesiredState随后通过session.run(cmd)拿到结果并做类型兜底如果返回不是 Python 布尔值则把字符串小写后与true比较win_dsc_resource.py保证返回值始终是严格的bool。3.3 set —— 把资源应用到期望状态set调用Invoke-DscResource -Method Set执行成功返回True失败则抛出CommandExecutionError见 win_dsc_resource.py# 创建/更新 C:\Temp\test.txt内容为 hello salt * dsc_resource.set File PSDesiredStateConfiguration \ properties{DestinationPath: C:\\Temp\\test.txt, Ensure: Present, Contents: hello} # 安装 Web-Server 功能IIS salt * dsc_resource.set WindowsFeature PSDesiredStateConfiguration \ properties{Name: Web-Server, Ensure: Present}set是三者中唯一使用run_strict的函数win_dsc_resource.py。这是因为Set方法会对系统产生实际变更如果脚本中途出错系统可能停留在未知状态此时必须把错误升级为异常而不能静默吞掉详见下文第五节对run_strict的分析。3.4 三个方法的命令构造对比函数Method返回处理关键执行方式getGetSelect-Object * -ExcludeProperty Cim*, PSComputerName后run_jsonrun_jsonJSON 序列化testTest取.InDesiredState布尔值run原生类型 布尔兜底setSet成功即返回Truerun_strict出错即抛异常四、Python ↔ PowerShell 类型转换机制dsc_resource之所以能把任意 Python dict 安全地送进Invoke-DscResource的-Property参数依赖三个私有辅助函数_ps_quote、_ps_value、_dict_to_ps_hashtablewin_dsc_resource.py。这三个函数被设计为无平台依赖的纯字符串转换并有完整的单元测试覆盖test_win_dsc_resource.py。4.1 类型映射表_ps_value把单个 Python 值映射为 PowerShell 字面量win_dsc_resource.pyPython 类型PowerShell 字面量说明bool$true/$false注意在bool分支之前处理避免与int混淆int/float裸数字如42、1.5None$nulldict{Key Value}递归调用_dict_to_ps_hashtablelist(item, ...)每个元素递归调用_ps_value元素可混合不同类型strvalue内部单引号翻倍转义_dict_to_ps_hashtable把整个 dict 转换为形如{Name Web-Server; Ensure Present}的哈希表字符串键与值都经过单引号转义win_dsc_resource.py。由此支持标量str、int、float、bool、None数组由上述类型或嵌套 dict 组成的list嵌套哈希表dict嵌套。4.2 安全性防注入设计单引号转义不仅是语法需要更是安全边界。_ps_quote把字符串内所有单引号翻倍→这是 PowerShell 单引号字符串内的标准转义规则win_dsc_resource.py。单元测试中专门有一条注入攻击用例验证这一点test_win_dsc_resource.py# 输入的 key 试图闭合哈希表并注入一条 Remove-Item 命令 result win_dsc_resource._dict_to_ps_hashtable( {} ; Remove-Item C:\\Windows ; $x {dummy: val} ) # 因为 key 被包在单引号里整段内容只是一个字面量 assert result {} ; Remove-Item C:\\Windows ; $x {dummy val}即使用户提供的属性键或值包含}、;等 PowerShell 元字符也会被当作单引号字符串字面量的一部分无法逃逸出哈希表或注入新语句。测试同时验证了空字符串、多单引号、非字符串强制转换如_ps_quote(42) 42等边界情况test_win_dsc_resource.py。4.3 测试用例对照单元测试对转换结果做了精确断言可作为理解行为的最佳样例test_win_dsc_resource.py# 混合类型 _ps_value({A: 1}) {A 1} _ps_value([a, b]) (a, b) _ps_value([True, 1, None, x]) ($true, 1, $null, x) _ps_value([{K: v}]) ({K v}) _ps_value({Props: {A: 1, B: x}}) {Props {A 1; B x}} # 布尔与整数的区分Python 中 bool 是 int 子类必须先处理 bool _ps_value({Val: True}) {Val $true} _ps_value({Val: 1}) {Val 1}五、底层支撑PowerShellSession 运行原理所有Invoke-DscResource调用都发生在一个进程内、有状态的 PowerShell Runspace 中即 win_pwsh.py 中的PowerShellSession类。理解它有助于判断模块的行为与错误语义。5.1 有状态进程内 Runspace与run_dict每次调用都启动powershell.exe子进程不同PowerShellSession通过 pythonnet 加载System.Management.Automation程序集在 Salt Minion 的 Python 进程内创建并复用同一个 Runspacewin_pwsh.py。因此同一个会话内导入的模块、定义的函数和会话变量都会持续存活——这对 DSC 资源调用是必要的因为资源模块只需在会话内加载一次。模块要求使用者以上下文管理器方式使用保证 Runspace 被确定性释放win_pwsh.pywith PowerShellSession() as session: result session.run_json(Get-NetAdapter | Select-Object Name, Status)5.2 会话级默认策略__init__在创建会话时设置三个全局偏好win_pwsh.py$ProgressPreference SilentlyContinue抑制进度条污染输出流$ErrorActionPreference Stop把所有非终止性 cmdlet 错误提升为终止性异常避免错误被静默忽略$WarningPreference SilentlyContinue抑制自动化场景中无操作价值的告警。由于$ErrorActionPreference Stop期望返回空结果的命令需要自行加-ErrorAction SilentlyContinue或用try/catch包裹否则会被当作错误处理。5.3 三种执行方法与错误语义方法用途错误语义run返回原生 Python 标量/列表PowerShell 报错时仅记日志并返回错误字符串不抛异常保持会话存活run_json通过ConvertTo-Json -Compress -Depth 4序列化后解析为 Python 对象PowerShell 进入Failed状态时抛CommandExecutionErrorrun_strict同run但任何错误都抛异常使用$__salt_ok__哨兵变量区分“脚本跑完但有被捕获的错误”与“脚本中途终止”run_strict的哨兵机制值得一提win_pwsh.py执行前把$__salt_ok__ $false拼接在脚本前执行后拼接$__salt_ok__ $true。若脚本因未捕获错误中途终止哨兵保持$false此时才会抛出CommandExecutionError若脚本完整跑完错误都被脚本内部try/catch捕获哨兵为$true则不抛异常。此外针对 PowerShell 5.1 SDK 中终止性错误不一定填充Streams.Error的情况还会回退查询$Error[0].Exception.Messagewin_pwsh.py。这正是dsc_resource.set选择run_strict的原因配置应用失败必须显式暴露给上层而不是让 Minion 静默继续。六、实战把 WindowsFeature 装进状态文件虽然dsc_resource是执行模块但完全可以组合进 Salt State实现幂等的配置管理。以安装 IIS 的 Web-Server 功能为例一个典型的 State 如下思路可参考 win_dsc.py 中dsc模块的配置管理理念实际 State 中可直接调用dsc_resource.set# C:\salt\srv\salt\iis\init.sls ensure-web-server: module.run: - name: dsc_resource.set - name_arg: WindowsFeature - module_name: PSDesiredStateConfiguration - properties: Name: Web-Server Ensure: Present - require: - psget: install-xpsmodule # 若使用第三方模块先安装执行salt win01 state.apply iis配合dsc_resource.test可在应用前先做检查、避免不必要的变更或结合dsc_resource.get在事后核对实际生效的属性值形成查询 → 校验 → 应用 → 复核的闭环。七、注意事项与限制平台与运行环境强约束模块只在 Windows pythonnet PowerShell SDK 三者齐备时加载win_dsc_resource.py模块文档标注依赖 PowerShell 5.0实际由 SDK 可用性决定。版本标记本模块与三个公开函数均标注.. versionadded:: 3008.1如 win_dsc_resource.py即 Salt 3008.1 及以后版本才提供。属性键的多样性properties的必需键随资源类型变化必须参照目标 DSC 资源的 schema 构造模块本身不做 schema 校验。错误处理差异get/test在会话报错时可能只记日志返回错误字符串而set会因run_strict直接抛异常——编排时应对set的失败显式处理。Type 转换已内建无需手动把 Python 布尔值写成$true也无需手动转义单引号但反过来不要在properties中直接传 PowerShell 表达式字符串它们会被当作字面量处理。结语dsc_resource把 Windows PowerShell 的Invoke-DscResource能力完整、安全地接入 Salt 生态get查询、test校验、set应用三件套覆盖了 DSC 资源的标准操作闭环_ps_quote/_ps_value/_dict_to_ps_hashtable组成的转换层既处理了 Python 与 PowerShell 的类型鸿沟又提供了单引号转义层面的注入防护底层PowerShellSession的进程内 Runspace 与严格错误语义则保证了执行的可靠性与可观测性。配合psget安装资源模块即可在任意托管 Windows 节点上零 MOF、零 LCM 地消费整个 PowerShell DSC 资源生态。赞分享运维配置管理后端【免费下载链接】saltSoftware to automate the management and configuration of infrastructure and applications at scale.项目地址https://gitcode.com/gh_mirrors/sa/salt点击查看免费下载相关推荐Salt 执行模块实战用 salt.modules.sqlite3 在 Minion 上直接操作 SQLite 数据库Salt 执行模块实战用 salt.modules.sqlite3 在 Minion 上直接操作 SQLite 数据库 本篇文章以 Salt 开源仓库中的 S运维配置管理后端PowerShell Desired State Configuration (DSC) 资源模块教程PowerShell Desired State Configuration DSC 资源模块教程 1. 项目介绍 PowerShell Desired StaSalt 官方文档深度解析salt.modules.mac_user —— macOS 用户管理执行模块实战指南Salt 官方文档深度解析salt.modules.mac_user —— macOS 用户管理执行模块实战指南 导读 salt.modules.mac_us运维配置管理后端上一篇终极Mac抢票指南如何用原生应用轻松购买火车票下一篇如何彻底解决Visual C运行库缺失问题新手也能掌握的VisualCppRedist AIO完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考