运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载catalog端点是 Puppet 配置管理体系中连接 agent 与 master 的核心枢纽agent 把本机 facts 提交给服务端服务端依据节点声明与环境配置编译出该节点的资源目录Catalog并返回 JSON。本篇指南以仓库中的 http_catalog.md 为骨架结合 catalog.json、facts.json 两份 schema 以及lib/puppet/indirector/catalog/compiler.rb、lib/puppet/http/service/compiler.rb等源码实现完整讲解该端点的请求方法、参数语义、静态目录static catalog扩展字段与响应结构读完即可独立构造一次目录请求并对响应做逐字段解析。端点概述一次请求拿到整台节点的“期望状态”catalog端点根据给定的节点名nodename与 facts返回针对该节点的资源目录。一次典型的请求链是agent 收集 facts → 通过 HTTP 调用本端点 → 服务端 compiler 根据 facts、节点声明ENC、环境与清单manifests编译目录 → 以application/json返回。Puppet 随后依据该目录完成资源收敛converge。POST /puppet/v3/catalog/:nodename GET /puppet/v3/catalog/:nodename?environment:environment支持的 HTTP 方法POSTGET支持的响应格式application/json为什么 POST 与 GET 等价却仍要保留两种按原文档说明POST 与 GET功能上完全等价两者都提供下文列出的参数POST 将参数放入请求体GET 将参数放入查询字符串。Puppet 最初只使用 GET之所以后来增加 POST是因为部分 Web 服务器对 URI 长度有上限典型如 1024 字节而facts参数序列化后很容易超过该上限。因此本文示例统一使用 POST 方法。这一“双重转义”的细节在源码中可以得到印证客户端在 compiler.rbHTTP Service 中先用Puppet::Util.uri_query_encode(facts_as_string)编码一次拼入application/x-www-form-urlencoded请求体服务端 catalog/compiler.rb 的convert_wire_facts再执行CGI.unescape(facts)还原同时兼容已废弃的pson格式Puppet::Node::Facts.convert_from(pson, CGI.unescape(facts))以支持旧版 agent。请求参数详解POST 与 GET 需要提供四类核心参数另有若干可选参数参数必需性说明environment必需环境名称例如productionfacts_format必需必须是application/jsonfacts必需facts 哈希的 JSON 序列化。由于 facts 中可能包含同时也是 HTTP 查询参数分隔符因此 facts 必须双重转义transaction_uuid必需标识整个事务的 UUID该值也会出现在 report 中用于把目录与报表关联起来静态目录static catalog场景下还需两个可选参数参数必需性说明static_catalog静态目录必需布尔值请求服务端在可用时返回静态目录实践中应始终为truechecksum_type静态目录必需以点号分隔的、agent 支持的校验和类型列表用于静态目录中 File 资源的校验顺序表示优先级越靠前优先级越高其他可选参数参数说明configured_environment客户端上配置的环境名称。可提供给 ENC外部节点分类器用于告知其客户端请求了特定环境而该环境可能与客户端自认为的当前环境不一致job_id触发本次目录请求的编排orchestration任务 ID请求参数的客户端实现细节从源码看agent 侧 compiler.rbHTTP Service 的post_catalog会把参数组装成keyvalue...形式的请求体body { facts_format: facts_format, facts: Puppet::Util.uri_query_encode(facts_as_string), environment: environment, configured_environment: configured_environment || environment, check_environment: !!check_environment, transaction_uuid: transaction_uuid, job_uuid: job_uuid, static_catalog: static_catalog, checksum_type: checksum_type.join(.) }.map do |key, value| #{key}#{Puppet::Util.uri_query_encode(value.to_s)} end.join()值得注意的几点出于历史兼容原因environment即使已放入请求体也会同时作为查询参数再发送一次见该文件第 120-121 行注释for legacy reasons we always send environment as a query parameter too。job_uuid即文档中的job_id用于把目录与 orchestrator 发起的任务经 pxp-agent关联。check_environment控制是否让服务端校验请求环境与节点声明的服务端环境是否一致服务端在 catalog/compiler.rb 中检测到不一致时会打印告警并返回一个空目录仅含节点名与环境避免 agent 在错误环境下执行资源。facts_format在默认配置下取自 JSON 格式化器的 mime 类型application/json若preferred_serialization_format设为pson则回退为pson文件第 85-92 行。facts 参数的 schema 约束facts参数需要符合 facts schema。该 schema 要求对象包含四个必需字段namestring节点名valuesobject该节点的 facts 哈希键名须匹配^[a-z][a-z0-9_]*$且不允许额外属性timestampstringfacts 收集时间注意不遵循 JSON 标准的date-time格式expirationstringfacts 过期时间同样不遵循标准date-time格式。服务端 catalog/compiler.rb 的extract_facts_from_request会校验 facts 中的节点名必须与请求 key 一致否则抛错Catalog for ... was requested with fact definition for the wrong node若提供了 facts 但没有facts_format则直接报Facts but no fact format provided。随后save_facts_from_request会把 facts 通过Puppet::Node::Facts.indirection.save存入服务端带transaction_uuid供后续报表关联使用。完整请求与响应示例示例一普通目录Catalog foundPOST /puppet/v3/catalog/elmo.mydomain.com environmentenvconfigured_environmentcanary_envfacts_formatapplication%2Fjsonfacts%257B%2522name%2522%253A%2522elmo.mydomain.com%2522%252C%2522values%2522%253A%257B%2522architecture%2522%253A%2522x86_64%2522%257D%257Dtransaction_uuidaff261a2-1a34-4647-8c20-ff662ec11c4c响应HTTP 200 OK Content-Type: application/json{ tags: [settings, multi_param_class, class], name: elmo.mydomain.com, version: 1377473054, code_id: null, catalog_uuid: 827a74c8-cf98-44da-9ff7-18c5e4bee41e, catalog_format: 1, environment: production, resources: [ { type: Stage, title: main, tags: [stage], exported: false, parameters: { name: main } }, { type: Class, title: Settings, tags: [class, settings], exported: false }, { type: Class, title: main, tags: [class], exported: false, parameters: { name: main } }, { type: Class, title: Multi_param_class, tags: [class, multi_param_class], line: 10, exported: false, parameters: { one: hello, two: world } }, { type: Notify, title: foo, tags: [notify, foo, class, multi_param_class], line: 4, exported: false, parameters: { message: One is hello, two is world } } ], edges: [ { source: Stage[main], target: Class[Settings] }, { source: Stage[main], target: Class[main] }, { source: Stage[main], target: Class[Multi_param_class] }, { source: Class[Multi_param_class], target: Notify[foo] } ], classes: [settings, multi_param_class] }响应中的edges数组刻画了目录中的包含关系containmentStage[main]包含Class[Settings]、Class[main]与Class[Multi_param_class]而Class[Multi_param_class]又包含Notify[foo]这正是 Puppet 依赖图dependency graph的序列化形态。示例二静态目录Static Catalog foundPOST /puppet/v3/catalog/elmo.mydomain.com environmentenvconfigured_environmentcanary_envfacts_formatapplication%2Fjsonfacts%7B%22name%22%3A%22elmo.mydomain.com%22%2C%22values%22%3A%7B%22architecture%22%3A%22x86_64%22%7Dtransaction_uuidaff261a2-1a34-4647-8c20-ff662ec11c4cstatic_catalogtruechecksum_typesha256.md5响应节选核心差异部分{ code_id: arbitrary_code_id_string, resources: [ { type: File, title: /tmp/foo, tags: [file, class], line: 12, exported: false, parameters: { ensure: file, source: puppet:///modules/a_module/foo } }, { type: File, title: /tmp/bar, tags: [file, class], line: 16, exported: false, parameters: { ensure: present, source: puppet:///modules/a_module/bar, recurse: true } } ], metadata: { /tmp/foo: { checksum: { type: sha256, value: {sha256}5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 }, content_uri: puppet:///modules/a_module/files/foo, destination: null, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/environments/production/modules/a_module/files/foo.txt, relative_path: null, source: puppet:///modules/a_module/foo, type: file } }, recursive_metadata: { /tmp/bar: { puppet:///modules/a_module/bar: [ { checksum: { type: ctime, value: {ctime}2016-02-19 17:38:36 -0800 }, content_uri: puppet:///modules/a_module/files/bar, destination: null, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/environments/production/modules/a_module/files/bar, relative_path: ., source: null, type: directory }, { checksum: { type: sha256, value: {sha256}962dbd7362c34a20baac8afd13fba734d3d51cc2944477d96ee05a730e5edcb7 }, content_uri: puppet:///modules/a_module/files/bar/baz, destination: null, group: 20, links: manage, mode: 420, owner: 501, path: /etc/puppetlabs/code/environments/production/modules/a_module/files/bar, relative_path: baz, source: null, type: file } ] } } }静态目录与普通目录的关键差异在于code_id普通目录中为null静态目录中携带一个代码版本标识示例为arbitrary_code_id_string用于标识本次编译对应的代码版本metadata非递归non-recursiveFile 资源到其元数据的映射内含checksum、content_uri、owner/group/mode等使 agent 无需二次请求即可校验文件内容recursive_metadata递归 File 资源如示例中recurse true的/tmp/bar按“source → 元数据数组”组织的映射数组中包含目录本身relative_path为.type为directory及其下每个文件如baz的元数据。静态目录的服务端生成逻辑静态目录并非单纯的数据透传而是由 catalog/compiler.rb 的compile方法在普通编译之后额外完成的“元数据内联”inline后处理当node.environment.static_catalogs?、请求带static_catalog且提供code_id时先通过common_checksum_type第 141-149 行在 agent 提供的checksum_type列表以.分隔与服务端known_checksum_types之间求第一个交集找不到公共校验和类型则直接抛错避免后续阶段失败inline_metadata第 207-306 行遍历目录中所有File资源跳过ensure absent、无source或 source 非puppet://协议的资源对recurse资源走Puppet::FileServing::Metadata.indirection.search填充recursive_metadata对单文件资源走indirection.find填充metadata内联只对位于environmentpath之下、形如$codedir/environments/$environment/*/*/files/**的模块文件生效inlineable_metadata?第 183-190 行环境之外的资源会被跳过并记录 profiler 事件log_file_outside_environmentcontent_uri由get_content_uri第 151-161 行基于源文件相对环境目录的真实路径构造保留用户指定的 server 与端口。agent 侧 catalog/rest.rbindirector terminus 在发起请求前同样会处理checksum_type若请求显式提供了则以.拆分否则使用Puppet[:supported_checksum_types]配置值随后调用Puppet::HTTP::Service::Compiler#post_catalog完成网络请求并把 404 响应转换为可读的 Puppet 错误fail_on_404为 false 时返回nil。响应 Schemacatalog.json 逐字段说明目录响应的结构由 catalog schema 定义其顶层required字段为tags、name、version、code_id、catalog_uuid、catalog_format、environment、resources、edges、classes且不允许额外属性。各字段含义如下字段类型说明tagsarray[string]目录标签tag 需匹配\A[[:alnum:]_][[:alnum:]_:.-]*\Znamestring目录所属节点名versionstring 或 integer目录版本示例中为整数时间戳1377473054code_idstring 或 null代码版本标识静态目录中非空catalog_uuidstring本次目录的唯一标识用于与报表关联catalog_formatinteger目录格式版本号当前示例为1environmentstring编译目录所用环境resourcesarray目录中的资源数组edgesarray目录中的包含关系数组classesarray[string]目录中包含的类名列表resources 与 edgesresources中每个资源的required字段为type、title、tags、exported可选字段包括line清单行号、kind、file清单文件路径、sensitive_parameters需按敏感参数处理的参数名列表与parameters参数名须匹配^[a-z][a-z0-9_]*$。edges中每条边由source与target组成例如Stage[main] → Class[Settings]描述资源的包含/依赖层级。metadata 与 recursive_metadata静态目录专属metadata是“非递归 File 资源标题 → file_metadata 对象”的映射recursive_metadata是“递归 File 资源标题 →source → file_metadata 数组”的两层映射。file_metadata定义schema 中definitions.file_metadata的必需字段为path、relative_path、links、owner、group、mode、type、destination、checksum并含可选的source、content_urilinks取值限于manage/followtype取值限于file/directory/linkchecksum.type取值限于md5/sha256/ctimevalue为带类型前缀的校验和字符串如{sha256}...mode、owner、group均为整数示例中的420即八进制0644的十进制表示。常见调试路径与延伸阅读服务端编译入口catalog/compiler.rbfind→compile→inline_metadata的完整链路agent 端 REST 终结器catalog/rest.rbindirectorHTTP 客户端封装compiler.rbHTTP Service其中post_catalogv3与post_catalog4v4 私有接口展示了两种请求装配方式数据约束catalog.json 与 facts.json相关端点节点信息见 http_node.mdfacts 上报见 http_facts.md报表提交见 http_report.md全部 HTTP API 总览见 http.md。小结/puppet/v3/catalog端点是 Puppet 编译与分发流程的事实标准接口POST/GET 两种方法等价四类核心参数environment、facts_format、facts、transaction_uuid配以静态目录扩展参数static_catalog、checksum_type与两个可选参数configured_environment、job_id即可驱动服务端完成从节点定位、facts 校验、目录编译到可选文件元数据内联的完整流程。响应体结构完全由 catalog.json 约束resources/edges描述期望状态metadata/recursive_metadata则为静态目录场景下的文件校验提供一站式元数据——理解这些字段与源码实现无论是排查 agent 编译问题、二次开发外部工具还是深入理解 Puppet 的“期望状态引擎”都能做到有的放矢。赞分享运维DevOpsIaC【免费下载链接】puppetServer automation framework and application项目地址https://gitcode.com/gh_mirrors/pu/puppet点击查看免费下载相关推荐Puppet HTTP API 完全指南/puppet/v3 与 /puppet-ca/v1 端点架构、调用方式与源码解析Puppet HTTP API 完全指南 /puppet/v3 与 /puppet ca/v1 端点架构、调用方式与源码解析 Puppet 服务端Puppe运维DevOpsIaCPuppet Catalog 深度解析Resource Catalog 与 RAL Catalog 两种形态及其在测试与 Settings 中的应用Puppet Catalog 深度解析Resource Catalog 与 RAL Catalog 两种形态及其在测试与 Settings 中的应用 导读P运维DevOpsIaCPuppet Certificate HTTP API 详解通过 /puppet-ca/v1/certificate 端点获取与管理证书Puppet Certificate HTTP API 详解通过 /puppet ca/v1/certificate 端点获取与管理证书 本指南以 Puppe运维DevOpsIaC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考