简介这份 Puppet 管理模块面向配置管理与 DevOps 工程师用于安装和管理 Puppet Master、The Foreman 与 smart-proxy并支持一体机aio、目录服务catalog和 CA 服务ca三种 Master 角色可按需单独部署目录或证书节点。与常见基于 yum 包和系统 Ruby 的同类方案不同它使用 RVM、git 仓库与 gem 管理整套软件栈模块化程度更高升级和 Ruby 安全补丁维护也更可控。压缩包为 zip 格式共 60 个文件、约 64KB主要包括 Puppet 清单.pp、ERB 模板.erb、Ruby 脚本.rb和 YAML 配置前两类分别用于声明资源状态与生成服务配置适合直接改造成自己的部署基线。目录按 foreman、smartproxy、puppet 等角色组织附带 spec 测试、Rakefile 与 Gemfile可串联自动化测试和依赖管理已有 133 人学习下载适合希望摆脱系统 Ruby 限制、对 Puppet 栈做精细化版本控制的团队参考。1. puppet_stack 这个名字为什么把三件套放在一起才有意义puppet_stack 把 Puppet Master、The Foreman 和 smart-proxy 三个词绑在同一个标题里很多人第一反应是“装一个 Master 就够了”。真到生产环境里批量加节点、区分开发与生产环境、处理证书续期时你会发现光有一个会编译目录的 Master 远远不够。这套栈真正提供的是一条完整链路配置能发出去、证书有人签、节点有人管、基础设施操作有统一出口。下面从组件职责讲到安装命令再落到日常维护和几个高频事故适合手上已经有三五十台到上千台 Linux 主机、正在为配置管理工具本身发愁的从业者。2. 职责边界Puppet Master、The Foreman、smart-proxy 各自在管什么2.1 Puppet Master 负责配置编译但不是管理入口Puppet Master有些部署方式下叫 Puppet Server是整个栈里唯一真正编译目录、给 Agent 下发的角色。它不面向运维人员提供操作界面也不负责审批本质上是一个后端服务。Agent 按约定时间来找它请求 catalogMaster 编译后返回Agent 在本地执行并回传报表。这个模型的好处是幂等坏处是运维对“谁来了、谁还没来、证书是否有效”没有任何直观感受。Master 端口固定是 8140日志一般在 /var/log/puppetlabs/puppetserver/ 下。针对 Master 的资源我的建议是单独准备一台机器内存视节点规模决定。节点数到几百台之后编译线程数和 JVM 堆需要按比例调。我一般会把 puppetserver 的-Xmx和-Xms设成同一个值避免运行中反复调整堆大小带来额外停顿。节点的请求频率也要控制默认 30 分钟一个周期是常见配置不要为了“实时生效”把所有 Agent 的runinterval调成 1 分钟那会把 Master 编译队列直接打满。2.2 The Foreman把主机生命周期和证书审批收口到网页The Foreman 不是一个来和 Puppet 抢活的配置引擎它是管理控制面。Foreman 提供主机登记、主机组归类、组织与位置划分、用户权限、以及最关键的报表查看。所谓“组织与位置”你可以理解成顶层隔离同一个 Foreman 里可以同时放多个客户或机房主机按组织归属主机组按位置归属互不串数据。还有一个能力在大量使用后会非常刚需它和 Puppet 的 CA 集成让证书审批可以在页面上点击完成不用在每个 Master 上都保留一批命令行活。几十台实验机的情况不装 Foreman 也能活着。节点一旦过百或者需要分环境、分团队让非核心运维也能自助看报表和触发任务Foreman 的价值就非常明显。它的 Web 服务走 443 端口和 Master 的 8140 分开API 也走同一套 HTTPS日常自动化脚本都可以直接对接。它解决的其实是一个很原始的问题配置管理原本的入口近乎为零而 Foreman 把入口补上了。2.3 smart-proxy 是 Foreman 的“手”不是网络出口这个组件是标题里最容易被误解的部分。smart-proxy 是 Foreman 的一组扩展服务用来操作 DNS、DHCP、TFTP 等基础设施同时承担证书签发的 relay 功能。比如在 Foreman 页面上给新主机分配网段并让它从 TFTP 启动这些动作最终通过 smart-proxy 在对应服务器上真实执行。它的 API 端口通常是 8443和 Foreman 的 443、Master 的 8140 并立。官方默认的安装器会按模块把证书、DHCP、DNS、TFTP 拆开。实操中我建议先只开证书模块跑通后续真需要 DHCP/DNS 联动再逐个模块打开。很多人的页面一片红就是因为默认把全部模块启用但底层服务根本没有或权限不合报警滚成一片反而掩盖了真问题。还要注意smart-proxy 可以直接和 Foreman 装在同一台机器上也可以放在某个目标网段的服务器上关键是它必须能被 Foreman 用可信的证书或 token 访问。2.4 选型考量单独 Master 与完整 puppet_stack 的边界能力单独 Puppet Master完整 puppet_stack配置下发有有证书签发入口命令行Foreman 页面 API主机与主机组管理没有有报表与历史检索没有有多环境切换的操作入口手动改目录主机组映射DHCP/DNS/TFTP 联动做不到smart-proxy 对应模块由此可以得出一个比较简单的判断只有几台实验机、不区分环境单独 Master 更快生产环境里“证书到期”“环境切换”“新节点上线”这三件事会反复出现靠命令行处理每一次都做不干净累积成本会随时间上升。还建议不要在同一个组织里混用两套方案否则 Master 上手工操作的证书记录和 Foreman 的管理记录会脱节后面排查会怀疑人生。2.5 组件之间的信任关系决定了很多坑的根源Puppet Agent 找 Master 要目录时采用的是 Puppet 自己的 CA 体系证书在 Agent 首次运行后生成必须经过 Master 或 Foreman 签名才有效。Foreman 和 Master 之间的通信用的是同一台机器上安装器自动生成的本地证书靠配置里的 SSL 参数互相校验Foreman 访问 smart-proxy 时则依赖代理侧预先注册的证书或 token。这三层信任链互相独立又彼此纠缠是后续绝大多数证书类报错的根源。实际排查时脚本里遇到的“connection reset”“certificate verify failed”“http 401”都不是同一个层面的问题需要先判断是 Agent 与 Master 的 CA 信任断了还是 Foreman 访问 smart-proxy 的凭证失效。这一步判断错了后面所有处理都是白做。3. 空服务器上跑通 puppet_stack安装步骤与第一个 Agent 上线3.1 环境准备主机名、DNS、时间约束安装前我会先处理三个基础项这三项不做好后面证书大概率出问题。第一是主机名必须固定为完整 FQDN 格式最好把 IP 也写进 /etc/hosts第二是每台机器都要启用时间同步第三是放行 8140、443、8443 三个端口。# 设置 FQDN 主机名改为你规划的正式名称 hostnamectl set-hostname master01.example.internal echo 192.0.2.10 master01.example.internal /etc/hosts # 启用时间同步证书签发强依赖时钟偏差不能太大 systemctl enable --now chronyd chronyc tracking | head -5 # 放行核心端口按实际使用的防火墙管理方式调整 firewall-cmd --permanent --add-port{8140/tcp,443/tcp,8443/tcp} firewall-cmd --reload主机名写在 hosts 里是保底方案避免内网 DNS 解析不可用时 Agent 找不到 Master。时间同步常被忽略但证书有效期判断和请求时间戳都建立在对时之上偏差超过几分钟就会看到各种难以理解的握手失败。3.2 添加软件源并安装 foreman-installer安装这套栈的入口不是分别装三个包而是装 foreman-installer由它在最后统一生成配置并拉起服务。先确认当前发行版支持哪种软件源方式再用包管理器安装安装器本体。# 先安装扩展包部分依赖组件在扩展源里 sudo dnf install -y epel-release # 添加对应发行版的 foreman 软件源并刷新缓存 sudo dnf install -y foreman-release sudo dnf update -y这里要强调的是官方安装器只负责把 Foreman、Puppet Master、smart-proxy 组合起来它不负责替你决定哪些模块要开。如果你在前面没有想清楚证书、DHCP、DNS 哪些要启用安装后大概率要往回改配置那时候每一步都牵一发动全身。3.3 执行安装器最小化参数先跑通首次安装一定要做最小化。把组织、位置定了再显式关闭用不到的基础设施模块。sudo foreman-installer \ --foreman-initial-organization myorg \ --foreman-initial-location myloc \ --puppet-server true \ --foreman-proxy-puppet true \ --foreman-proxy-register-in-foreman true \ --enable-foreman-proxy-plugin-dhcp false \ --enable-foreman-proxy-plugin-dns false \ --enable-foreman-proxy-plugin-tftp falseorganization 和 location 是 Foreman 的顶层隔离维度后面可以在页面里继续建但初始值最好一次写对。puppet-server true 让本机把 Master 一起拉起来三个 plugin 全 false是因为这一阶段目标是证明链路能走通。安装过程通常要几分钟到十几分钟结束时会打印默认 admin 密码和访问地址先保存好再关窗口。提示安装完成后不要立刻重启机器等证书全部生成、服务先跑一遍正常了再做重启验证。3.4 首次登录与健康检查安装器结束后第一步是先看服务状态而不是急着打开页面。# 分别查看三个核心服务的状态 systemctl status httpd --no-pager -l systemctl status puppetserver --no-pager -l systemctl status foreman-proxy --no-pager -l # 确认三个端口都在监听 ss -lntp | grep -E :(8140|8443|443)\b如果 8140 没出现说明 puppetserver 没有正常起来大概率是 JVM 内存参数或主机名解析问题。8443 缺失则去查 foreman-proxy 的日志最直观的判断方式就是这三个端口必须同时存在。页面访问用 https://master01.example.internal/首次登录时用安装器打印的 admin 账号密码系统会要求改掉初始密码这一步在自动化脚本里经常被落下导致后面所有 API 调用一直返回 401 认证失败。3.5 接入第一个 Agent从证书请求到完成首次运行Agent 端的接入套路是从安装 puppet-agent 包开始先配好 server 地址再触发一次预演。# 在目标节点上安装并指向 Master sudo dnf install -y puppet-agent sudo vim /etc/puppetlabs/puppet/puppet.conf # [main] # server master01.example.internal # 第一次运行用预演模式目的是触发证书请求 sudo /opt/puppetlabs/bin/puppet agent -t --noop第一次运行大概率会卡在“等待证书签发”的状态这很正常因为服务端还没有放行。此时回到 Master 端查看待签列表并完成签发# 查看待签名证书确认识别出真实节点 /opt/puppetlabs/bin/puppet cert list # 确认无误后签发对应名称的证书 /opt/puppetlabs/bin/puppet cert sign agent01.example.internal签发完成后再次执行puppet agent -t应该就能拿到 catalog 并按目录完成预演。这里的 agent 名称默认取自节点主机名所以主机名在安装前就固化下来非常关键临时换过名的节点证书签发后往往出现名称不匹配只能清掉重签。4. 日常管理证书、环境、主机组和 smart-proxy 健康检查4.1 用一组命令管理 Agent 证书的完整生命周期证书是这个栈里最不能靠感觉处理的资产。日常无非四类操作查看、签发、撤销、清理重签我习惯全部用命令行兜底虽然 Foreman 页面也能做但脚本和自查时命令行更快。# 查看所有证书带 --all 才会同时显示已签发和待签发 /opt/puppetlabs/bin/puppet cert list --all # 撤销并移除某节点的证书记录 /opt/puppetlabs/bin/puppet cert clean agent01.example.internal # 重新签发节点端必须先清空旧证书 /opt/puppetlabs/bin/puppet cert sign agent01.example.internalcert clean删除的是服务端记录节点端还握着旧证书和私钥如果不去清节点端 SSLDir下一次请求会报出各种验证失败。常见做法是登录节点后删除 /etc/puppetlabs/puppet/ssl 整个目录再重新跑puppet agent -t生成新请求。较新版本也可以直接用puppet ssl bootstrap重置但旧路径同样可行优先用目录清理法最稳。4.2 Foreman 里的主机组和环境划分Foreman 的管理基本单元是主机组。常见做法是建一个 base 主机组放通用配置再在它下面派生 dev、staging、production 子组把 Puppet environment 映射到各子组。这样新增节点时只要选对主机组环境归属就自动正确不需要在 Agent 端手动改配置文件。# 用 API 建主机时指定主机组和环境示例结构 curl -k -u admin:password \ -H Content-Type: application/json \ -d {host:{name:app01,hostgroup_id:9,environment_id:3}} \ https://master01.example.internal/api/hosts在页面操作时主机组和环境都是下拉选项。要注意 Agent 端 /etc/puppetlabs/puppet/puppet.conf 里的 environment 必须和主机组一致否则会陷入“我明明改了环境节点跑完还是旧配置”的困惑。API 里的环境字段实际上对应 environment id这个 id 可以在页面或 API 里查。4.3 分清 puppetserver、foreman、foreman-proxy 三类日志服务日志路径常见问题puppetserver/var/log/puppetlabs/puppetserver/编译报错、CA 异常foreman/var/log/foreman/production.log页面报错、API 401foreman-proxy/var/log/foreman-proxy/proxy.log证书 relay、DHCP/DNS 操作失败遇到 Agent 报错时先看 Agent 端日志再往 Master 侧看这个顺序不能反。大多数时候服务端其实是正常的问题出在证书或环境名不匹配。快速确认 smart-proxy 状态可以用# 输出各模块启用状态和监听情况比页面上的红色警告更快定位 sudo foreman-proxy status这套栈的三段日志里foreman-proxy 的日志最容易被忽略。它的报错大多会有明确的 timeout 或 connection refused先看它能迅速把问题边界从“Foreman 坏了”缩小到“某个模块没起来”。4.4 用 runinterval 控制 Agent 的请求节奏Agent 默认每 30 分钟连接一次 Master我在生产上不会把这个值调得太小。瞬时大量节点同时来请求Master 的编译线程会被占满表现是页面正常但节点全部超时。# Agent 端配置示例 [agent] runinterval 1800 splay true splaylimit 300runinterval 单位是秒1800 就是半小时。splay 让各节点在区间内随机分散启动避免所有机器在同一秒发起请求splaylimit 限制随机范围的上限。不要图省事在高峰期大批量手动触发puppet agent -t一定要分批次比如拆成每批五十台间隔几分钟。Foreman 页面的远程执行功能在设计上是按主机组或主机列表分发的适合定向操作不适合全量刷。5. 上线后最常见的五个坑现象、原因、排查顺序5.1 证书过期后 Agent 重签不生效现象Agent 报证书过期运维在 Master 端执行 clean 后重新 sign节点仍然报无法连接。原因服务端记录删了但节点端 SSLDir 里还是旧证书和旧私钥。节点再次请求时拿着旧身份Master 按新签发的记录校验不通过。处理先清理节点端旧证书再触发新请求。# 节点端先清顺序不能反 rm -rf /etc/puppetlabs/puppet/ssl /opt/puppetlabs/bin/puppet agent -t执行完再回 Master 端 sign 一次。顺序是关键先节点端清理、再服务端清理、最后重签。反过来操作时表面上每次都能“签成功”但节点一直用旧身份连接问题会反复出现。5.2 页面一片红smart-proxy 模块全开但服务没起来现象Foreman 页面里 Smart Proxies 列表大面积红色只有证书模块正常。原因安装时没有显式关闭用不到的模块默认把 DHCP、DNS、TFTP 相关模块全部启用了但对应服务或权限并未准备。处理编辑 /etc/foreman-proxy/settings.d/ 下对应模块的配置文件把 enabled 改为 false再重启 foreman-proxy。用不到的模块一定要关干净半关闭状态会让页面持续报警反而掩盖证书模块之外的真实故障。5.3 改了 Foreman 里的环境节点却不动现象在页面把节点从 dev 主机组切到 prod 主机组Agent 跑完后节点配置还是 dev 的。原因environment 最终以 Agent 配置文件里的 environment 字段为准主机组只是管理侧标注并不会自动改写 Agent 端的配置。处理在节点上打开 /etc/puppetlabs/puppet/puppet.conf把 environment 改成和主机组一致改完再验证 /etc/puppetlabs/code/environments/ 下是否存在对应名称的目录。目录不存在时 Master 会退回 production 环境这也是环境切换无效的另一半原因。5.4 报表不更新但 Agent run 是成功的现象节点配置生效Agent 运行也报 Completed但 Foreman 的 Reports 页面已经几天没新数据。原因报表上报链路上出了问题。常见是 Master 的 report 配置仍指向 localhost没有指向 Foreman或者 report 功能被关掉了。处理# 在 Master 上检查 report 与上报地址 /opt/puppetlabs/bin/puppet config print report report_server如果 report 不是 true或者 report_server 是 localhost、空值就修改 puppet.conf 的 [master] 段把 report 打开并指向 Foreman 的 FQDN然后重启 puppetserver。报表功能恢复后历史数据一般会陆续补回不用手工干预。5.5 服务重启顺序有讲究现象维护或升级后Agent 全部连接失败Foreman 页面也登录不上但逐个查看服务状态又是正常。原因三个服务之间互相依赖启动顺序错了会陷入证书与注册状态互相等不到的局面。最常见的是把 Web 服务放在最前导致 Foreman 启动时以错误的凭证去访问 smart-proxy。处理按我这个顺序重启一次。systemctl restart foreman-proxy systemctl restart puppetserver systemctl restart httpd先让 smart-proxy 的证书通道就绪再拉起 Master最后让 Foreman 通过 Web 端口对外服务。这是我在某内部管理项目里连续踩了两次跟头才固定的顺序之后每次维护都按它执行没有再出现过“服务全正常但整体瘫痪”的怪状态。6. 进阶一步把环境划分和代码入库做成常规流程6.1 环境目录与主机组静态映射多环境的基础是目录不是配置文件。我在 Master 上维护 /etc/puppetlabs/code/environments/ 下的 dev、staging、production 三个目录每个目录里都有独立的 manifests/site.pp 和 hieradataForeman 的主机组名与它们一一对应。新增节点的动作就收敛为两步在 Foreman 建主机、选主机组。第一次 run 会自动进入对应环境人工干预点只剩“建组、选组”两个地方。6.2 发布前先做三层检查改代码不能直接丢进生产目录。我一般先做语法校验再做预演最后才同步。cd /etc/puppetlabs/code/environments/staging /opt/puppetlabs/bin/puppet parser validate manifests/site.pp /opt/puppetlabs/bin/puppet apply --noop manifests/site.pp --modulepath modulesparser validate 负责语法层预演模式会列出将要变更的资源。看预演结果时如果只有一两个操作说明改动可控如果显示要动几十甚至上百处文件必须回到代码里找原因。版本控制工具可以按团队习惯选关键是生产目录不能被直接手改。我曾因为贪图省事把 dev 目录的代码直接软链到 production第二天所有生产节点都跑上了未验证配置。从那以后我坚持目录分离和预演并希望帮到你。本文还有配套的精品资源点击获取