运维高效部署 Puppet 完整方案

Puppet 两种模式：Master-Agent（集中式，生产大规模首选）、Masterless 单机模式（小规模测试，puppet apply）。高效部署核心思路：代码 Git 托管、r10k 自动分发、Hiera 解耦数据、证书自动化、Agent 批量安装、CI 验证 + 灰度发布，避免手动写 manifest、手动签证书。

一、架构选型（先确定规模）

开源版：Puppet Server；商业版：Puppet Enterprise（PE，自带 Console、CodeManager、一键 Agent 安装、图形化证书管理）Puppet

核心组件说明：

1. Puppet Server：Master，编译 catalog、CA 证书签发，监听 8140 端口

2. Puppet Agent：每台被管节点，默认 30min 拉取配置，puppet agent -t手动触发

3. Facter：采集节点 facts（OS、IP、硬件）

4. Hiera：数据与代码分离，分层变量（环境 / 角色 / 节点）

5. r10k：从 Git 自动拉取 Puppet 代码，多环境管理（prod/staging/dev）

6. PuppetDB：存储节点 facts、catalog、执行报告，支持跨节点查询（exported resource）

二、前置准备（避坑重点）

1. DNS/hosts 解析：必须保证 master 主机名可被所有 agent 解析，证书基于主机名，解析异常是最高发故障

2. 防火墙：放行 Master 8140 端口

3. 时间同步：所有节点统一 NTP，证书依赖时间

4. 系统：推荐 Rocky/EL、Debian/Ubuntu；Windows 可做 Agent

5. 内存：Puppetserver 非常吃内存，最低 2C4G；生产建议 4C8G，JVM 堆内存-Xms4g -Xmx4g

三、部署步骤（开源 Master-Agent，高效流水线）

1. 安装 Puppet Server（Master 节点）

1. 导入 Puppet 官方 YUM/APT 源

2. 安装puppetserver，修改/etc/puppetlabs/puppetserver/puppetserver.conf调整 JVM 内存

3. 启动并开机自启：systemctl enable --now puppetserver

4. 安装 PuppetDB，配置 puppet.conf、postgresql 数据库，puppetserver 对接 puppetdb

5. 安装 r10k，配置 r10k.yaml 指向 Git 代码仓库

puppet.conf（master 侧）

[main]
  environmentpath = /etc/puppetlabs/code/environments
  basemodulepath = /etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules
[master]
  storeconfigs = true
  storeconfigs_backend = puppetdb

2. 代码仓库与 r10k（高效核心，告别手动改代码）

把所有 puppet 代码放到 Git，分多环境分支 dev/staging/prod，r10k 自动拉取生成环境目录。

• 目录规范（标准 control repo）

control-repo/
├── environments/
├── manifests/site.pp      # 入口
├── hiera.yaml             # Hiera层级配置
├── modules/               # 自定义模块
└── Puppetfile             # r10k，声明forge第三方模块

• 更新代码只需要：git push → r10k deploy environment -p，自动同步到 puppetserver，不用登录 master 拷贝文件

3. Hiera5 数据分离（提升可维护性）

不要硬编码变量在 manifest 里。按层级：节点 > 角色 > 环境 > 全局默认，统一管理主机名、端口、账号、版本。

4. Agent 批量自动化安装（最高效，不手动一台台装）

两种主流批量方案：

1. 一键 bootstrap 脚本（推荐） Puppet 官方提供一键安装脚本，在目标节点执行一行命令，自动安装 agent、写入 server 地址、发起证书 CSR 请求。

curl -k https://puppet-master:8140/packages/current/install.bash | sudo bash

2. 配合 Ansible / 脚本批量推送：先通过 Ansible 在所有机器执行安装脚本，一次性部署大量 agent。

Agent 配置 /etc/puppetlabs/puppet/puppet.conf

[main]
server = puppet-master.example.com
environment = production

5. 证书自动化（运维最大痛点，批量签证书）

• 查看待签证书：puppet cert list

• 单节点签发：puppet cert sign agent01.example.com

• 批量签发（自动化）：puppet cert sign --all（测试环境可用；生产谨慎，优先自动签名策略或 PE 控制台审批）

生产安全最佳实践：不要永久自动签名，使用证书白名单或 PE 控制台人工审批 CSR。

Agent 安装完成后执行测试：

puppet agent -t --noop    # 先noop模拟执行，不改动系统！！生产必做
puppet agent -t           # 真实应用catalog

四、代码规范 & 最佳实践（保证长期高效）

1. 角色与配置分离（Roles & Profiles 模式）

   • Profile：封装具体服务（nginx、mysql），调用模块

   • Role：一个主机角色，包含多个 profile（web 角色 = nginx+sysbaseline） 节点只分配 role，不写大量资源，大规模环境极易维护。

2. 优先使用 Puppet Forge 现成模块，不要从零手写。

3. CI/CD 校验：Git 提交前自动跑puppet-lint、puppet validate、rspec-puppet单元测试，禁止坏代码上线。

4. 灰度发布：先 staging 环境验证，再少量生产节点，全量滚动。

5. 资源瘦身：减少昂贵资源（大量 file 递归、exec），优化 catalog 编译耗时。

6. 定时调优：分散 agent 执行时间，不要所有节点同一时刻并发请求 master（splay = true）。

五、扩容 & 高可用方案

1. 4000 节点以内：单机 master+puppetdb，优化 JVM、数据库调优

4000 节点：增加Compiler 编译节点，前端加 LB，Agent 请求打到 LB，编译节点分担 catalog 编译；主节点仅做 CA、控制台、puppetdb

• PuppetDB 数据库做主从，保证数据持久化

六、常见坑

1. 证书问题：主机名、FQDN 不一致，重装节点证书残留，需要puppet cert clean清理旧证书

2. 8140 端口不通、DNS 解析失败，agent 无法连接 master

3. Puppetserver 内存不足，catalog 编译超时，大量 agent 排队

4. 代码没有 noop 测试，上线直接改生产系统，引发故障

5. 变量硬编码，没有使用 Hiera，多环境维护成本爆炸

七、极简快速上手（测试环境，快速验证）

1. 安装 puppetserver

2. 建 control repo + r10k 拉取

3. 写 site.pp，简单基线（设置 motd、ntp、包）

4. 用 bootstrap 脚本批量装 agent

5. puppet agent -t --noop验证，再正式执行

本文原创作者：易君召，详见：https://www.yijunzhao.cn/authors/yijunzhao，转载请注明出处。

原文链接 https://www.yijunzhao.cn/archives/ops-efficient-puppet-deployment-complete-guide

欢迎访问 小易撩挨踢