puppet resource 命令完全指南：用 Puppet RAL 直接查询与修改系统状态

运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载puppet resource是 Puppet 的命令行核心工具之一被称为资源抽象层Resource Abstraction LayerRAL的 Shell它能把当前系统的真实状态直接翻译成等价的 Puppet 声明式代码也能在命令行上通过attributevalue参数直接对系统资源进行增删改。本文基于本仓库中由 Puppet 源码自动生成的手册页 references/man/resource.md其 roff 版本见 man/man8/puppet-resource.8结合命令入口实现 lib/puppet/application/resource.rb 与 RAL 间接层 lib/puppet/indirector/resource/ral.rb完整讲解语法、选项、典型用法与底层执行原理读完即可上手用它完成查状态、生成清单、就地修改三类日常工作。一、命令概述什么是 RAL Shell在 Puppet 的官方手册索引 references/man/overview.md 中puppet resource与puppet agent、puppet apply、puppet lookup、puppet module并列为Core Tools核心工具是所有用户都应理解其用途的基础命令。手册页对其 NAME 与 SYNOPSIS 的定义如下NAMEpuppet-resource— The resource abstraction layer shell资源抽象层 ShellSYNOPSISUses the Puppet RAL to directly interact with the system.使用 Puppet RAL 直接与系统交互所谓 RAL是 Puppet 的核心抽象lib/puppet/type.rb中的Puppet::Type是所有资源类型的基类它把被管理的实体如文件、用户、服务、包建模为type并区分两类属性Property属性描述实体的真实状态同时拥有当前状态is与期望状态should两个值例如文件的 owner、group、modeParameter参数只影响管理行为本身、与实体实例无关的配置例如文件资源是否递归recurse、从哪里查找等Meta-Parameter元参数对所有类型普遍可用的参数例如require、before这类关系元参数。type 的行为由provider提供者具体实现provider 通常与平台相关在运行时根据合适性suitability被选中。puppet resource正是站在这一抽象层之上让用户用完全一致的语言风格去查询和修改异构系统上的资源。二、命令语法USAGE手册页给出的完整用法为puppet resource [-h|--help] [-d|--debug] [-v|--verbose] [-e|--edit] [-p|--param parameter] [-t|--types] [-y|--to_yaml] type [name] [attributevalue ...]参数位置规则type是必须提供的资源类型名如user、file、package、servicename可选指定要操作的单个实例名如用户名、文件路径、服务名attributevalue ...可选提供后命令将修改该资源的状态而非仅查询各--xxx长选项均有单字母短形式-d、-v、-e、-p、-t、-y、-f。三、三种核心用法1. 列出某类型的所有资源只给 type默认情况下至少提供一个 typepuppet resource就会列出它所知道的该类型所有资源实例并把它们输出为 Puppet 声明式代码。底层调用的是间接层Indirector的search操作# lib/puppet/indirector/resource/ral.rb def search(request) conditions request.options.dup conditions[:name] resource_name(request) if resource_name(request) type(request).instances.map(:to_resource).find_all do |res| conditions.all? do |property, value| res.copy_as_resource[property].to_s value.to_s end end.sort_by(:title) end即先通过type(request).instances枚举该类型的全部实例再按条件过滤并按 title 排序。2. 查询单个实例type name只给出 type 和一个实例名时命令只描述该实例。对应间接层find实现# lib/puppet/indirector/resource/ral.rb def find(request) res type(request).instances.find { |o| o.name resource_name(request) } res || type(request).new(:name resource_name(request), :audit type(request).properties.collect(:name)) res.to_resource end先在系统现有实例中按 name 查找若找不到则新建一个开启audit审计全部属性的实例从而也能尽量读出可获取的状态。3. 就地修改资源状态type name attributevalue 对如果同时给出 type、name 和一组attributevalue对puppet resource会把参数构造成一个资源并直接应用即真正改变机器状态。例如修改用户的 shell 或创建一个文件。4. 交互式编辑--edit如果给出 type、name 和--edit标志命令会把查询结果写入一个临时文件在编辑器中打开该文件将保存后的文件当作 Puppet 事务transaction应用执行。这一流程对应 lib/puppet/application/resource.rb 中的handle_editing实现临时文件以x2puppet为前缀创建在当前目录Tempfile.new(x2puppet, Dir.pwd)以 UTF-8 编码并同步写入随后调用ENV[EDITOR]指定的编辑器未设置时回退为vi最后执行puppet apply -v 临时文件路径把编辑结果作为一次真实的 Puppet 事务应用完成后安全删除临时文件。四、选项详解OPTIONS手册页完整列出以下选项语义如下选项短形式说明--debug-d启用完整调试输出--edit-e将查询结果写入文件、在编辑器中打开再作为可执行的 Puppet 清单读回并应用--help-h打印帮助信息--param-p在查询输出中额外加入指定的参数--types-t列出所有可用的资源类型--verbose-v打印额外信息--to_yaml-y以 YAML 格式输出找到的资源适合配合 Hiera 与create_resources使用--fail-f若资源未能被修改则失败并返回退出码 1在入口实现 lib/puppet/application/resource.rb 中可以看到这些选项的注册方式option(--debug, -d) option(--verbose, -v) option(--edit, -e) option(--to_yaml, -y) option(--fail, -f) option(--types, -t) do |_arg| env Puppet.lookup(:environments).get(Puppet[:environment]) || create_default_environment types [] Puppet::Type.typeloader.loadall(env) Puppet::Type.eachtype do |t| next if t.name :component types t.name.to_s end puts types.sort exit(0) end option(--param PARAM, -p) do |arg| extra_params arg.to_sym end值得注意的实现细节--types会加载当前环境下的全部类型Puppet::Type.typeloader.loadall跳过内部的:component类型按字母排序后输出并立即退出--param把参数累加到extra_params数组而preinit中默认值为[:provider]——也就是说provider 默认就会出现在查询输出中这是从源码结构可见的默认行为--edit与--to_yaml互斥main中会直接抛出Editing with Yaml output is not supported错误见 lib/puppet/application/resource.rb。另外手册页还强调任何在配置文件puppet.conf中合法的设置项都可以作为长参数传给命令。例如ssldir是合法设置因此可以写--ssldir directory。完整参数列表可通过运行puppet --genconfig生成一份带注释的配置选项清单。五、典型示例手册页给出的官方示例是查询用户luke并得到等价 Puppet 声明$ puppet resource user luke user { luke: home /home/luke, uid 100, ensure present, comment Luke Kanies,,,, gid 1000, shell /bin/bash, groups [sysadmin,audio,video,puppet] }在此基础上可举一反三列出系统中所有用户puppet resource user查询单个文件资源puppet resource file /etc/passwd查询单个服务puppet resource service sshd列出全部可用类型puppet resource --types查询单个实例并额外输出 providerpuppet resource user luke --param provider以 YAML 输出供 Hiera / create_resources 使用puppet resource user luke --to_yaml修改资源状态puppet resource user luke shell/bin/zsh修改失败时以退出码 1 报错puppet resource --fail ...注意事项手册页与实现都提到file类型不支持列出全部文件实例——因为文件系统上文件数量巨大且无明确边界必须显式给出路径。源码中对应的守卫逻辑位于 lib/puppet/application/resource.rbif type file raise _(Listing all file instances is not supported. Please specify a file or directory, e.g. puppet resource file /etc) end六、命令入口与执行流程整个子命令由Puppet::Application::Resource类实现入口文件为 lib/puppet/application/resource.rb。一次典型执行经历以下阶段preinit初始化extra_params [:provider]setup将日志目标设为控制台Puppet::Util::Log.newdestination(:console)并按选项设置日志级别对应--debug/--verbose生效的位置main解析环境 → 解析参数 → 查询或保存资源 → 按输出格式渲染。main方法核心逻辑lib/puppet/application/resource.rbtype, name, params parse_args(command_line.args) raise _(Editing with Yaml output is not supported) if options[:edit] and options[:to_yaml] resources find_or_save_resources(type, name, params) if options[:to_yaml] data resources.map do |resource| resource.prune_parameters(:parameters_to_include extra_params).to_hiera_hash end.inject(:merge!) text YAML.dump(type.downcase data) else text resources.map do |resource| resource.prune_parameters(:parameters_to_include extra_params).to_manifest.force_encoding(Encoding.default_external) end.join(\n) end options[:edit] ? handle_editing(text) : (puts text)参数解析parse_argsparse_args 依次取出 type缺失即报You must specify the type to display校验类型存在Puppet::Type.type(type)不存在报Could not find type %{type}再逐个解析attributevalue对if setting ~ /^(\w)(.)$/ params[::Regexp.last_match(1)] ::Regexp.last_match(2) else raise _(Invalid parameter setting %{setting}) % { setting: setting } end注意属性名必须是单词字符\w不符合namevalue格式的输入会直接报错这是命令保持严格输入契约的体现。环境回退执行前会先获取当前环境若指定的环境在文件系统上不存在则回退到默认的production环境create_default_environmentlib/puppet/application/resource.rb并以 debug 日志说明。这一点也有集成测试覆盖见下文测试验证。七、底层机制查询、保存与输出格式查询与保存走 Indirectorpuppet resource的查询与修改都通过Puppet Indirector完成其 terminus 为Puppet::Resource::Rallib/puppet/indirector/resource/ral.rb类注释明确写着 Manipulate resources with the resource abstraction layer. Only used internally.仅内部使用并且allow_remote_requests?返回false即不允许远程请求只能操作本机资源。在 find_or_save_resources 中有 name 且无参数 →Puppet::Resource.indirection.find(key)纯查询有 name 且有参数 → 构造Puppet::Resource.new(type, name, :parameters params)后执行Puppet::Resource.indirection.save(resource, key)就地修改无 name →Puppet::Resource.indirection.search(key, {})列举。save 如何真正改变系统Ral#save是理解命令行改系统的关键lib/puppet/indirector/resource/ral.rbdef save(request) # In RAL-land, to save means to actually try to change machine state res request.instance ral_res res.to_ral catalog Puppet::Resource::Catalog.new(nil, request.environment) catalog.add_resource ral_res transaction catalog.apply [ral_res.to_resource, transaction.report] end可以看到所谓 save 在 RAL 语境下就是真正尝试改变机器状态——把资源转为 RAL 资源to_ral见 lib/puppet/resource.rb放入一个临时 catalog执行catalog.apply产生一次事务transaction并同时返回修改后的资源与事务报告。这也是--fail选项的落点入口代码会检查report.resource_statuses[resource.ref]的状态若failed?且指定了--fail则抛出Failed to manage resource ...并以退出码 1 结束lib/puppet/application/resource.rb。输出渲染to_manifest 与 to_hiera_hash两种输出模式分别对应 lib/puppet/resource.rb 中的两个方法Puppet 声明输出to_manifestlib/puppet/resource.rb把属性排序、将ensure提到最前、按最长属性名对齐并转义 title 中的单引号最终生成形如user { luke:\n home /home/luke,\n ...}的代码YAML 输出to_hiera_hashlib/puppet/resource.rb先经to_data_hash转成安全的 Data 类型无 Symbol、无替换字符再把ensure单独提取到最前其余参数按名排序产出{ title { ensure ..., ... } }结构最后以YAML.dump(type.downcase data)包装——这正是它适合配合 Hiera 与 create_resources的原因。两种输出前都会调用prune_parameterslib/puppet/resource.rb做裁剪删除值为空、数组为空的属性删除值为absent且属性不是ensure的属性并且只保留 type 的 properties 与应包含参数parameters_to_include含--param累加的内容与默认的:provider中的属性。这保证了输出干净、无冗余噪声。八、配置项的通用规则手册页特别说明除了上述专用选项外任何在配置文件中合法的设置都可以作为长参数传给puppet resource例如--ssldir directory。这得益于 Puppet 统一的命令行参数体系所有配置项conf 目录、环境、modulepath、ssldir 等都能以--key value形式覆盖。如需查看本机全部可配置项及其注释说明可运行puppet --genconfig九、测试验证从集成测试理解行为契约本仓库的集成测试 spec/integration/application/resource_spec.rb 对命令行为给出了可验证的契约包括无效环境回退设置环境为badenv后运行命令会输出Debug: Specified environment badenv does not exist on the filesystem, defaulting to production并在缺少 type 时以错误You must specify the type to display退出码 1 结束列出资源resource.command_line.args [file, Puppet[:confdir]]时输出形如file { confdir:的清单列出类型向模块路径写入一个自定义类型test_resource_spec后--types输出中会出现该类型名file/tidy 特殊行为对文件目录执行file dir ensuredirectory recursetrue不会报错并能生成目录tidy dir rmdirstrue recursetrue则真正清理指定路径并产生Notice: /File[dir]/ensure: removed输出。这些用例直接印证了前文所述的参数解析、环境回退、类型枚举与 RAL 应用行为。附作者与版权AUTHORLuke KaniesCOPYRIGHTCopyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License手册页本身由 Puppet 源码在构建时自动生成生成时间 2024-11-04因此始终与当前源码版本保持一致阅读 roff 格式版本可参考 man/man8/puppet-resource.8。赞分享运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载相关推荐Puppet 命令行手册总览puppet 二进制与其子命令体系完整指南Puppet 命令行手册总览puppet 二进制与其子命令体系完整指南 本指南以 Puppet 仓库中的 references/man/overview.md运维DevOpsIaCPuppet 证书状态 HTTP API 深度指南/puppet-ca/v1/certificate_status 端点的查询、签发与吊销Puppet 证书状态 HTTP API 深度指南/puppet ca/v1/certificate_status 端点的查询、签发与吊销 本篇文章以 Pup运维DevOpsIaCPuppet项目中的puppet-apply命令详解本地应用Puppet清单指南Puppet项目中的puppet apply命令详解本地应用Puppet清单指南 概述 Puppet apply是Puppet项目中一个强大的命令行工具它允运维DevOpsIaC上一篇COLMAP与游戏开发快速创建游戏场景的 photogrammetry 工作流下一篇gaze-detection API完整参考loadModel、setUpCamera与getGazePrediction三大核心方法详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考