Puppet exec 资源类型完全指南：幂等命令设计、条件执行与刷新事件机制

• 运维
• DevOps
• IaC

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，无法保证命令只运行一次，因此命令本身必须可重入。

实现幂等的三种主要途径

其中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 => '...', # 超时秒数（默认 300，0 表示禁用） tries => '...', # 重试次数（默认 1） try_sleep => '...', # 重试间隔秒数（默认 0） umask => '...', # 执行命令时使用的 umask unless => '...', # 测试命令，退出码为 0 则不执行主命令 user => '...', # 以该用户身份运行命令 # ...以及任何适用的 metaparameters（如 notify、subscribe、loglevel 等） }

command（namevar）

要执行的实际命令。必须使用绝对路径，或通过path属性提供搜索路径，否则会在校验阶段直接失败——provider 基类的validatecmd方法（lib/puppet/provider/exec.rb）会抛出 "'xxx' is not qualified and no path was specified" 错误。

• 命令成功时，其输出按资源正常日志级别（通常为notice）记录；失败时输出按err级别记录。
• 允许重复：尽管command是 namevar，Puppet 允许多个 exec 资源使用相同的command值，只以资源 title 保证唯一性。源码中@isomorphic = false（lib/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', 'MAIL=root@example.com']。要点：

• 若用此属性设置 PATH，会覆盖path属性的值（provider 的environment方法会先放入path拼出的PATH，随后用environment中的同名变量覆盖，见 lib/puppet/provider/exec.rb）。
• 每个条目必须形如VAR=value，源码校验正则/^\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 追加 root）：

exec { '/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 != 0（lib/puppet/type/exec.rb）。

path

命令执行的搜索路径。未指定path时命令必须全限定。可指定为数组或以File::PATH_SEPARATOR（Unix 为冒号:、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 timeout"（lib/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 users"（lib/puppet/type/exec.rb）。
• 使用该属性时，错误输出无法被捕获（Ruby 已知 bug）。
• 若你用 Puppet 创建该用户（且以名称而非数字 UID 指定），exec 会自动 require 该 user 资源。
• 使用此属性时$HOME环境变量不会自动设置，需要时请通过environment显式指定。

刷新（Refresh）行为：五种场景全解析

exec可通过notify、subscribe或~>箭头响应刷新事件。exec 的刷新行为是非标准的，受refresh和refreshonly属性影响，共有五种情况：

简言之：只要 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 及对应源码为：posix（lib/puppet/provider/exec/posix.rb）、shell（lib/puppet/provider/exec/shell.rb）、windows（lib/puppet/provider/exec/windows.rb）。

posix（POSIX 默认）

通过调用 Ruby 的Kernel.exec执行外部二进制程序：

• 字符串命令：若命令不含元字符、shell 保留字或特殊内建命令，则直接执行而不经过 shell。
• 数组命令：以[cmdname, arg1, ...]形式直接执行，首元素为命令名，其余作为参数，无 shell 展开。这是更安全、更可预测的执行方式，但无法使用通配符（globbing）和 shell 内建逻辑（如for、if语句）。
• 需要通配符或 shell 内建时，请改用shellprovider。
• 约束：feature == posix；平台默认 provider；支持的 feature：umask。
• 额外行为：checkexe会校验命令文件存在、是普通文件且可执行（lib/puppet/provider/exec/posix.rb）。

shell（POSIX 专用）

将命令通过/bin/sh -c传递（源码 lib/puppet/provider/exec/shell.rb 直接构造['/bin/sh', '-c', command]）：

• 仅 POSIX 系统可用。
• 允许 shell 通配符与内建命令，命令无需全限定（validatecmd直接返回 true）。
• 比posix更便捷，但转义要求更严格，需要小心处理。
• 该 provider 行为接近 Puppet 0.25.x 时代的 exec 类型。

windows（Windows 默认）

在 Windows 上直接以给定参数调用命令，不经过 shell、不做任何插值，行为类似posix：

• 需要使用 shell 内建（模拟shellprovider）时，必须显式调用 shell：

exec { '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 == windows；Windows 平台默认 provider。

常见误区与最佳实践

结合文档警示与源码实现，使用 exec 时有几点值得注意：

1. 不要用 exec 堆积管理本可用现有类型管理的资源。文档明确告诫：用一堆 exec 管理现有资源类型未覆盖的对象在小规模时没问题，但一旦 exec 堆积到需要费心理解的程度，就应考虑开发自定义资源类型，它更可预测、更易维护。
2. 对可能收到刷新事件的 exec，务必收紧运行条件（onlyif/unless/creates/refreshonly），否则可能出现命令运行两次等非预期行为。
3. 优先使用数组形式的command，规避 shell 注入与转义问题；只有确实需要管道、通配符或控制逻辑时才选用shellprovider。
4. 理解 noop 语义：onlyif/unless在 noop 运行中也会真实执行，用于判断同步状态，因此这些测试命令本身也应是安全的、无副作用的。
5. 对敏感命令使用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 单元测试中逐一验证。

• 运维
• DevOps
• IaC