运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载exec是 Puppet 中用于执行外部命令的核心资源类型它弥补了内置资源类型无法覆盖的操作空白。本篇指南以仓库中 references/types/exec.md 官方类型参考为骨架结合 lib/puppet/type/exec.rb 及三个平台 provider 的源码实现系统讲解 exec 的幂等性设计、全部 17 个属性参数、三种 provider 的行为差异以及最容易出错的刷新refresh事件语义。读完本文你将能够写出可安全重复运行、行为可预期的 exec 资源并理解 Puppet 在幕后如何判断这条命令是否需要执行。exec 是什么管理需要执行的状态exec资源类型的核心作用是执行外部命令。在 Puppet 中大多数资源类型管理的是系统对象的最终状态如文件内容、服务是否运行而exec管理的状态是一个抽象问题这条命令在当前 catalog run 中是否需要被执行。从源码看exec的目标状态永远是命令不需要执行。如果初始状态是命令需要执行那么成功执行命令就会将其转换到目标状态如果因onlyif、unless、creates等条件判断出命令不需要执行则系统已处于目标状态该 exec 被视为成功且不会真正执行命令。这种检查-执行模型由 lib/puppet/type/exec.rb 中returns属性的retrieve方法实现它先调用check_all_attributes逐一验证所有条件检查checks若全部通过则返回:notrun触发执行否则直接返回期望值should让资源表现为in_sync?从而跳过执行。一个必须遵守的铁律是任何 exec 命令都必须能够安全地重复运行多次幂等idempotent。Puppet 会在每次 catalog run 中评估 exec无法保证命令只运行一次因此命令本身必须可重入。实现幂等的三种主要途径途径机制适用场景命令本身幂等命令重复执行不产生副作用如apt-get update、touch等条件守卫用onlyif、unless、creates判断是否执行大多数自定义命令仅刷新执行设refreshonly true仅在收到刷新事件时运行依赖其他资源变化的触发动作其中onlyif与unless命令在判断 exec 是否已同步的过程中使用因此在 noop试运行模式下也必须执行——这一点在文档和源码中均有强调见 lib/puppet/type/exec.rb 中unless检查的实现。全部属性参数详解exec 资源的完整声明形式如下文档 references/types/exec.md 中的属性骨架exec { resource title: command ..., # (namevar) 要执行的实际命令 creates ..., # 运行前检查的文件文件不存在才执行 cwd ..., # 命令运行的工作目录 environment ..., # 附加环境变量数组 group ..., # 以该组身份运行命令 logoutput ..., # 是否记录命令输出默认 on_failure onlyif ..., # 测试命令退出码为 0 才执行主命令 path ..., # 命令搜索路径 provider ..., # 后端实现posix / shell / windows refresh ..., # 收到刷新事件时运行的替代命令 refreshonly ..., # 仅作为刷新机制运行 returns ..., # 期望的退出码默认 0 timeout ..., # 超时秒数默认 3000 表示禁用 tries ..., # 重试次数默认 1 try_sleep ..., # 重试间隔秒数默认 0 umask ..., # 执行命令时使用的 umask unless ..., # 测试命令退出码为 0 则不执行主命令 user ..., # 以该用户身份运行命令 # ...以及任何适用的 metaparameters如 notify、subscribe、loglevel 等 }commandnamevar要执行的实际命令。必须使用绝对路径或通过path属性提供搜索路径否则会在校验阶段直接失败——provider 基类的validatecmd方法lib/puppet/provider/exec.rb会抛出 xxx is not qualified and no path was specified 错误。命令成功时其输出按资源正常日志级别通常为notice记录失败时输出按err级别记录。允许重复尽管command是 namevarPuppet 允许多个 exec 资源使用相同的command值只以资源 title 保证唯一性。源码中isomorphic falselib/puppet/type/exec.rb正是这一语义的体现。数组形式的更安全调用在 *nix 平台命令可指定为字符串数组[/bin/echo, hello world; rm -rf /]Puppet 将采用参数化的系统调用直接执行不经过 shell 解析从而避免注入风险——上面的示例只会原样输出hello world; rm -rf /而不会真的执行删除命令。这是比拼接 shell 字符串更安全、行为更可预测的调用方式。creates运行命令前检查的文件路径文件不存在才执行命令。该参数不会让 Puppet 创建文件它只对命令自身会创建文件的场景有用。例如从 tar 包解压exec { tar -xf /Volumes/nfs02/important.tar: cwd /var/tmp, creates /var/tmp/myfile, path [/usr/bin, /usr/sbin,], }该示例中myfile被假定为 tar 包内的文件一旦它被删除exec 会重新解压 tar 包来恢复。若important.tar中实际上不包含myfile则该 exec 每次 Puppet 运行都会执行。creates也接受文件数组任一文件存在即不执行creates [/tmp/file1, /tmp/file2],只有两个文件都不存在时命令才会运行。其底层检查实现在 lib/puppet/type/exec.rb!Puppet::FileSystem.exist?(value)即文件不存在则检查通过。cwd命令运行的起始目录。若该目录不存在命令将执行失败。注意 provider 基类lib/puppet/provider/exec.rb在cwd为 nil 时不会尝试切换目录——因为无意义的 chdir 在某些环境下反而会失败。environment为命令设置的附加环境变量数组例如[HOME/root, MAILrootexample.com]。要点若用此属性设置 PATH会覆盖path属性的值provider 的environment方法会先放入path拼出的PATH随后用environment中的同名变量覆盖见 lib/puppet/provider/exec.rb。每个条目必须形如VARvalue源码校验正则/^\w\w*/不匹配的条目会抛出Invalid environment setting错误。多个环境变量以数组形式指定。group以指定组身份运行命令。文档明确指出该功能在不同平台上的表现差异较大这属于平台问题而非 Ruby 或 Puppet 的问题——与在 shell 中以不同用户运行命令时的差异同源。校验由SUIDManager类处理。logoutput是否在记录退出码之外记录命令输出。默认on_failure即仅当命令退出码与returns指定的值不匹配执行失败时记录输出。可选值true、false、on_failure。日志级别可通过loglevelmetaparameter 控制。在源码的sync方法lib/puppet/type/exec.rb中可以看到输出日志化的完整逻辑logoutput true时按资源 loglevel 输出每一行on_failure时依据退出码决定是否输出若command被标记为 sensitive则输出内容会被替换为[output redacted]。onlyif一个测试命令用于检查目标系统状态、限制 exec 的执行时机。Puppet 会先运行该测试命令仅当测试退出码为 0 时才运行主命令。示例exec { logrotate: path /usr/bin:/usr/sbin:/bin, provider shell, onlyif test du /var/log/messages | cut -f1 -gt 100000, }只有当日志文件超过 100000 单位时才运行logrotate。测试命令与主命令使用相同的provider、path、user、cwd、group若未设path测试命令必须使用全限定名。由于该命令参与是否已同步的判断在 noop 运行中也必须执行。支持命令数组全部退出码为 0 才执行以及数组的数组混合字符串命令与参数化命令onlyif [test -f /tmp/file1, test -f /tmp/file2] onlyif [[test, -f, /tmp/file1], test -f /tmp/file2]底层实现见 lib/puppet/type/exec.rb调用provider.run(value, true)执行检查超时则记录错误并返回 false视为检查失败最终以status.exitstatus 0作为判定。unless与onlyif相反Puppet 先运行测试命令除非测试退出码为 0否则运行主命令。经典示例Solaris 下向 cron.allow 追加 rootexec { /bin/echo root /usr/lib/cron/cron.allow: path /usr/bin:/usr/sbin:/bin, unless grep ^root$ /usr/lib/cron/cron.allow 2/dev/null, }若grep已发现 root 存在退出码 0则不再追加。同样支持命令数组与数组的数组语义为每个命令退出码均非 0 时才执行主命令。其判定实现为status.exitstatus ! 0lib/puppet/type/exec.rb。path命令执行的搜索路径。未指定path时命令必须全限定。可指定为数组或以File::PATH_SEPARATORUnix 为冒号:、Windows 为分号;分隔的字符串例如path /usr/bin:/usr/sbin:/bin。源码中value方法lib/puppet/type/exec.rb会把字符串按分隔符拆分为数组存储。posixprovider 在查找命令时会临时将 PATH 设置为该值并调用which确认可执行文件存在lib/puppet/provider/exec/posix.rb。refresh当 exec 从其他资源收到刷新事件时运行的替代命令。默认行为是再次运行主命令。注意替代命令与主命令使用相同的provider、path、user、group未设path时必须全限定。该参数的校验会调用provider.validatecmd确保命令可被找到或可全限定lib/puppet/type/exec.rb。refreshonly设置命令仅作为刷新机制运行——只在依赖对象变化时触发。它只有与subscribe或notify配合才有意义因为只有subscribe和notify能触发动作require不能。经典示例aliases 文件变化后重建 newaliases 数据库file { /etc/aliases: source puppet://server/module/aliases, } exec { newaliases: path [/usr/bin, /usr/sbin], subscribe File[/etc/aliases], refreshonly true, }从源码看refreshonly是一个特殊的检查check而非普通参数其check方法总是返回不通过因为该 exec 只应在刷新时运行lib/puppet/type/exec.rb。不过在refresh流程中会跳过该检查check_all_attributes(true)时跳过:refreshonly从而允许刷新事件触发执行。returns期望的退出码property表示目标系统上的具体状态。命令返回其他退出码时视为失败并报错。可指定为单个值或可接受退出码数组。POSIX 系统上退出码恒为 0~255 的整数。Windows 上大多数退出码应为 0~2147483647 的整数。更大的退出码在不同工具间表现不一致Win32 API 将退出码定义为 32 位无符号整数但 cmd.exe shell 和 .NET 运行时会将其转换为有符号整数因此部分工具会报告负数如 cmd.exe 将 4294967295 报告为 -1。Puppet 使用原生 Win32 API会报告非常大的正数而非负数——如果你从 cmd.exe 会话中拿到的是负数结果可能与你预期不符。Microsoft 建议避免使用负数/超大退出码。若需将负数退出码转换为 Puppet 使用的正数可加上 4294967296。默认值0。源码中returns以:array_matching :all定义lib/puppet/type/exec.rb其sync方法会执行provider.run并比对should.include?(status.exitstatus.to_s)判断是否达到期望。测试用例 spec/unit/type/exec_spec.rb 验证了退出码在 returns 数组中不报错、不在数组中则报错以及敏感命令失败时输出[command redacted]的行为。timeout命令允许的最大执行时间单位为秒。超过时限则命令被视为失败并被终止。默认 300 秒设置为 0 可禁用超时。注意timeout作用于每一次尝试而非整组 tries。源码将其munge为Float并取[value, 0.0].max且在sync中通过Timeout::Error捕获超时并报 Command exceeded timeoutlib/puppet/type/exec.rb。tries命令执行的尝试次数。会重复尝试直到获得可接受的返回码。timeout参数作用于单次尝试而不是全部 tries 的总和。默认1。源码要求值必须为大于等于 1 的整数并在sync中以tries.times循环执行lib/puppet/type/exec.rb每次尝试之间可选try_sleep秒的间隔。try_sleep两次tries之间的睡眠秒数。默认0。源码同样做类型校验不允许负数。umask执行命令时使用的 umask。该参数需要 provider 支持umaskfeature目前仅posixprovider 声明支持。源码将其munge为八进制整数匹配/^0?[0-7]{1,4}$/的合法八进制表示posixprovider 在执行时通过Puppet::Util.withumask包装lib/puppet/provider/exec/posix.rb。user以指定用户身份运行命令。要点Windows 上 Puppet 无法以其他用户执行命令源码校验会直接self.fail。非 root 用户若试图以他人身份执行命令校验会报 Only root can execute commands as other userslib/puppet/type/exec.rb。使用该属性时错误输出无法被捕获Ruby 已知 bug。若你用 Puppet 创建该用户且以名称而非数字 UID 指定exec 会自动 require 该 user 资源。使用此属性时$HOME环境变量不会自动设置需要时请通过environment显式指定。刷新Refresh行为五种场景全解析exec可通过notify、subscribe或~箭头响应刷新事件。exec 的刷新行为是非标准的受refresh和refreshonly属性影响共有五种情况场景行为refreshonly trueexec仅在收到事件时运行这是使用 exec 刷新最可靠的方式已运行过、收到事件、无 refresh 命令命令最多运行两次。若第一次运行后onlyif/unless/creates条件不再满足则第二次运行不发生已运行过、有refresh命令、收到事件先运行正常命令若onlyif/unless/creates条件仍满足再运行refresh命令被onlyif/unless/creates阻止而未运行、收到事件仍然不会运行noop true、本来会运行、收到来自非 noop 资源的事件运行一次若有refresh命令则运行refresh命令而非正常命令简言之只要 exec 有可能收到刷新事件就必须严格限制其运行条件。refresh方法的实现lib/puppet/type/exec.rb会先以跳过refreshonly的方式重新检查所有条件通过后运行refresh命令若指定或再次sync主命令。自动依赖Autorequires为保障执行顺序正确exec 会自动产生依赖关系若 Puppet 正在管理 exec 的cwd目录或命令中使用的可执行文件exec 会自动 require 这些file资源lib/puppet/type/exec.rb 中通过正则从命令、onlyif、unless中提取绝对路径。若 Puppet 正在管理 exec 的运行用户exec 会自动 require 该user资源按名称指定时数字 UID 不会触发自动依赖见 lib/puppet/type/exec.rb。这意味着你无需手动为 先创建目录/用户再执行命令 编写require关系Puppet 会按需自动建立。Provider 详解三种执行后端provider属性指定 exec 的底层实现通常无需手动指定Puppet 会按平台自动选择。可用 provider 及对应源码为posixlib/puppet/provider/exec/posix.rb、shelllib/puppet/provider/exec/shell.rb、windowslib/puppet/provider/exec/windows.rb。posixPOSIX 默认通过调用 Ruby 的Kernel.exec执行外部二进制程序字符串命令若命令不含元字符、shell 保留字或特殊内建命令则直接执行而不经过 shell。数组命令以[cmdname, arg1, ...]形式直接执行首元素为命令名其余作为参数无 shell 展开。这是更安全、更可预测的执行方式但无法使用通配符globbing和 shell 内建逻辑如for、if语句。需要通配符或 shell 内建时请改用shellprovider。约束feature posix平台默认 provider支持的 featureumask。额外行为checkexe会校验命令文件存在、是普通文件且可执行lib/puppet/provider/exec/posix.rb。shellPOSIX 专用将命令通过/bin/sh -c传递源码 lib/puppet/provider/exec/shell.rb 直接构造[/bin/sh, -c, command]仅 POSIX 系统可用。允许 shell 通配符与内建命令命令无需全限定validatecmd直接返回 true。比posix更便捷但转义要求更严格需要小心处理。该 provider 行为接近 Puppet 0.25.x 时代的 exec 类型。windowsWindows 默认在 Windows 上直接以给定参数调用命令不经过 shell、不做任何插值行为类似posix需要使用 shell 内建模拟shellprovider时必须显式调用 shellexec { echo foo: command cmd.exe /c echo foo, }命令未指定扩展名时Windows 使用PATHEXT环境变量定位可执行文件。PowerShell 脚本注意PowerShell 默认的restricted执行策略不允许运行保存的脚本。要运行 PowerShell 脚本需在命令中指定remotesigned执行策略exec { test: path C:/Windows/System32/WindowsPowerShell/v1.0, command powershell -executionpolicy remotesigned -file C:/test.ps1, }约束os.name windowsWindows 平台默认 provider。常见误区与最佳实践结合文档警示与源码实现使用 exec 时有几点值得注意不要用 exec 堆积管理本可用现有类型管理的资源。文档明确告诫用一堆 exec 管理现有资源类型未覆盖的对象在小规模时没问题但一旦 exec 堆积到需要费心理解的程度就应考虑开发自定义资源类型它更可预测、更易维护。对可能收到刷新事件的 exec务必收紧运行条件onlyif/unless/creates/refreshonly否则可能出现命令运行两次等非预期行为。优先使用数组形式的command规避 shell 注入与转义问题只有确实需要管道、通配符或控制逻辑时才选用shellprovider。理解 noop 语义onlyif/unless在 noop 运行中也会真实执行用于判断同步状态因此这些测试命令本身也应是安全的、无副作用的。对敏感命令使用sensitive_parameters源码会在命令失败时将输出与命令文本替换为[output redacted]/[command redacted]避免泄露密钥等敏感信息。总结exec是 Puppet 中最灵活也最容易被误用的资源类型。理解其管理是否需要执行的状态这一抽象、掌握onlyif/unless/creates三种条件守卫与五条刷新规则、分清posix/shell/windows三种 provider 的执行语义是写出安全、幂等、可维护的 exec 资源的关键。上述全部参数与行为均可在本仓库 references/types/exec.md 官方参考、lib/puppet/type/exec.rb 类型实现及 spec/unit/type/exec_spec.rb 单元测试中逐一验证。赞分享运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载相关推荐HASS.Agent多语言支持如何为全球用户提供本地化体验HASS.Agent多语言支持如何为全球用户提供本地化体验 HASS.Agent是一款基于Windows的Home Assistant客户端提供通知、快捷操桌面应用物联网x64dbg 条件断点控制命令完全指南条件、日志、命令与命中计数x64dbg 条件断点控制命令完全指南条件、日志、命令与命中计数 x64dbg 是一款面向 Windows 的开源用户态调试器专为逆向工程与恶意软件分析而优逆向工程调试器开发工具应用安全Puppet tidy 资源类型完全指南基于 age / size / matches 条件的自动化文件清理Puppet tidy 资源类型完全指南基于 age / size / matches 条件的自动化文件清理 导读 tidy 是 Puppet 内置的声明式资运维DevOpsIaC上一篇蚂蚁开源Ring-flash-linear-2.0混合架构实现1/10推理成本长文本处理能力跃升下一篇AutoGen多智能体框架5分钟快速搭建AI应用开发平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考