Puppet 配置参数详解

系统梳理 Puppet 配置体系——puppet.conf 配置节、site.pp 清单、Hiera 查找、roles/profiles 分层及 file/package/service/user/exec/cron 资源类型参数，并给出生产配置模板，默认值基于 Puppet 8 实测

PuppetPuppetDevOps配置管理2026/10/09

Puppet 配置参数详解

目标：系统梳理 Puppet 的配置体系——puppet.conf 配置节、site.pp 清单、Hiera 数据查找、roles/profiles 分层，以及 file/package/service/user/exec/cron 常用资源类型的参数，并给出生产配置模板。所有命令均已实测，默认值以 Puppet 8 真实输出为准。

一、环境信息

  • Puppet Server 8.7.0 / Puppet Agent 8.10.0（Puppet 8 系，facter 4.10.0）
  • 主配置文件：/etc/puppetlabs/puppet/puppet.conf
  • 环境目录：/etc/puppetlabs/code/environments/production/
  • 主清单：/etc/puppetlabs/code/environments/production/manifests/site.pp
  • Hiera 配置：/etc/puppetlabs/puppet/hiera.yaml
  • Server 数据：/opt/puppetlabs/server/data/puppetserver

二、前置条件

  • 已按《Ubuntu 22.04 安装 Puppet 指南》部署 Server 与 Agent
  • Server/Agent 证书已签发互通

三、参数查看与修改方式

查看当前生效配置（Agent 侧）：

export PATH=$PATH:/opt/puppetlabs/bin
puppet config print certname server environment
# certname = puppet-agent
# environment = production
# server = puppet-server

修改配置：

puppet config set server puppet-server     # 写入 [main]
puppet config set certname puppet-agent    # 写入 [main]

puppet config 写入的即 /etc/puppetlabs/puppet/puppet.conf。

四、参数总览

分类配置项实测默认/推荐说明
连接serverpuppet-serverServer 地址（Agent 侧）
身份certname主机名证书与节点匹配名
环境environmentproduction当前目录环境
环境目录environmentpath/etc/puppetlabs/code/environments环境根目录
认证autosign无autosign 配置文件路径
运行模式noopfalse空跑不生效
运行间隔runinterval1800Agent 守护运行间隔（秒）
证书目录ssldir/etc/puppetlabs/puppet/sslSSL/证书存放目录
数据/日志vardir/logdir/opt/puppetlabs/puppet/cache 等运行时数据与日志

五、puppet.conf 配置节详解

5.1 配置节类型

puppet.conf 按 [节名] 分组，常用节有：

配置节作用
[main]全局默认，所有命令都会读取
[server]（或 [master]）Server 端专用
[agent]Agent 端专用
[apply]puppet apply 专用

5.2 实测示例

Server 端 puppet.conf（配置 server/certname 与 Server 目录）：

[main]
server = puppet-server
certname = puppet-server

[server]
vardir = /opt/puppetlabs/server/data/puppetserver
logdir = /var/log/puppetlabs/puppetserver
rundir = /var/run/puppetlabs/puppetserver
codedir = /etc/puppetlabs/code

Agent 端 puppet.conf：

[main]
server = puppet-server
certname = puppet-agent

💡 说明：codedir 指向环境与清单目录（/etc/puppetlabs/code）；environment 未指定时默认 production。

六、site.pp 主清单详解

6.1 结构与节点

site.pp 是每个环境的入口清单，用 node 节点块定义各主机应用资源：

node 'puppet-agent' {
  package { 'nginx':
    ensure => installed,
  }
}
  • node default { } 匹配未命中其他节点块的主机。
  • 一个 node 块内可声明多个资源，彼此用依赖链（require/before/notify/subscribe）关联。

6.2 校验

export PATH=$PATH:/opt/puppetlabs/bin
puppet parser validate /etc/puppetlabs/code/environments/production/manifests/site.pp
# 无输出即语法正确

七、Hiera 数据查找详解

Hiera 用于把"配置数据"与"清单逻辑"分离。/etc/puppetlabs/puppet/hiera.yaml（Puppet 5 以上 version: 5）定义查找层级：

version: 5
defaults:
  datadir: data
  data_hash: yaml_data
hierarchy:
  - name: "Per-node data (yaml version)"
    path: "nodes/%{trusted.certname}.yaml"
  - name: "Common data"
    path: "common.yaml"

数据文件放在环境目录 data/ 下（common.yaml 全局、nodes/<主机名>.yaml 按节点覆盖）：

data/common.yaml：

profile::web::port: 8080
profile::web::worker_processes: 2

data/nodes/puppet-agent.yaml：

profile::web::port: 9090

用 puppet lookup 查询：

export PATH=$PATH:/opt/puppetlabs/bin
puppet lookup profile::web::worker_processes --environment production
# --- 2

puppet lookup profile::web::port --environment production
# --- 8080

💡 说明：Hiera 按 hierarchy 从上到下优先命中。若该主机名匹配不到 nodes/*.yaml，则取 common.yaml 值（实测由于 Server 自身 certname 非 puppet-agent，puppet lookup 在 Server 上返回的是 common 的 8080，属正确的层级行为）。若需按节点查询，需在目标节点上报事实的上下文编译。

八、roles / profiles 分层详解

推荐用"角色-档案"两级封装，避免在 node 块里铺大量资源：

  • profile（档案）：把某类功能的资源组合成一个 class，直接声明资源与参数默认值。
  • role（角色）：把一个节点的多个 profile 聚合。

目录布局：

/etc/puppetlabs/code/environments/production/modules/
├── profile/manifests/web.pp      # class profile::web
└── role/manifests/web_node.pp    # class role::web_node

profile/manifests/web.pp：

class profile::web (
  Integer $port = 8080,
) {
  package { 'nginx': ensure => installed }
  service { 'nginx':
    ensure => running,
    enable => true,
    require => Package['nginx'],
  }
}

role/manifests/web_node.pp：

class role::web_node {
  include profile::web
}

site.pp 收敛为角色引用：

node 'puppet-agent' {
  include role::web_node
}

💡 说明：Hiera 的数据可回填 profile 参数（如 profile::web::port），配合 include profile::web 即在模块默认值基础上做参数覆盖。

九、常用资源类型参数详解

9.1 file（文件/目录）

参数说明实测示例
ensurefile/directory/present/absentensure => directory
path/name标题即路径（path 可省略）name => '/opt/web'
content内容（优先于 source）content => '<h1>Hi</h1>'
owner/group属主/属组owner => 'root'
mode权限，八进制字符串mode => '0755'
require依赖其他资源require => File['/opt/web/']

实测：

puppet resource file /opt/web/index.html
# file { '/opt/web/index.html':
#   ensure   => 'file',
#   content  => '{sha256}b609bb64723a35e854a4ca50ab2801bb35863d98ad6e67fcc4058d1c4465557d',
#   mode     => '0644',
#   owner    => 0,
#   provider => 'posix',
#   type     => 'file',
# }

9.2 package（软件包）

参数说明实测示例
ensureinstalled/present/latest/absentensure => installed
name包名name => 'nginx'
provider包管理器（apt/yum/dnf）自动识别

实测（目录应用）：

Notice: /Stage[main]/Main/Node[puppet-agent]/Package[nginx]/ensure: created

9.3 service（服务）

参数说明实测示例
ensurerunning/stoppedensure => running
enable是否开机自启enable => true
providersystemd/init 等provider => 'systemd'
require依赖（如安装了才有服务）require => Package['nginx']

实测：

puppet resource service nginx
# service { 'nginx':
#   ensure   => 'running',
#   enable   => 'true',
#   provider => 'systemd',
# }

9.4 user（用户）

参数说明实测示例
ensurepresent/absentensure => present
uid/gid用户/组 IDuid => 3001, gid => 3001
shell/home登录 shell 与家目录shell => '/bin/bash', home => '/home/deploy'
managehome是否创建家目录managehome => true
require依赖先建组require => Group['deploy']

⚠️ 建用户前若指定 gid，需先用 group 资源建组，否则报 useradd: group '3001' does not exist（实测遇到）。

实测资源展示：

puppet resource user deploy
# user { 'deploy':
#   ensure             => 'present',
#   gid                => 3001,
#   home               => '/home/deploy',
#   shell              => '/bin/bash',
#   uid                => 3001,
#   provider           => 'useradd',
# }

9.5 exec（命令执行）

参数说明实测示例
command要执行的命令command => '/bin/touch /opt/x'
creates该文件已存在则跳过creates => '/opt/x'
user/cwd执行用户与工作目录user => 'root'
onlyif/unless条件执行unless => 'test -f /opt/x'

9.6 cron（计划任务）

参数说明实测示例
command执行的命令command => '/bin/date >> /var/log/h.log'
minute/hour/weekday调度字段minute => '0', hour => '2'
user以哪个用户运行user => 'root'

⚠️ 提示：Puppet 的 cron 资源依赖系统 cron provider。若目标主机未装 cron，会报 Could not find a suitable provider for cron（实测遇到）。先 package { 'cron': ensure => installed } 即可解决。

实测（装 cron 后）：

puppet apply -e 'cron { "hello-daily": command => "/bin/date >> /var/log/hello.log", user => "root", minute => "0", hour => "2" }'
# Notice: /Stage[main]/Main/Cron[hello-daily]/ensure: created
# Notice: Applied catalog in 0.03 seconds

十、生产配置模板

适用业务场景：2–4GB 内存、SSD、数十台 Agent 节点的配置管理控制平面。

/etc/puppetlabs/puppet/puppet.conf：

[main]
server = puppet-server
certname = puppet-server

[server]
autosign = /etc/puppetlabs/puppet/autosign.conf
environment = production

/etc/default/puppetserver（JVM 内存，务必收敛大堆）：

JAVA_ARGS="-Xms256m -Xmx512m -Djna.tmpdir=/opt/puppetlabs/server/data/puppetserver/jnatmp -Djruby.logger.class=com.puppetlabs.jruby_utils.jruby.Slf4jLogger"

autosign.conf：

*.example.com

💡 说明：生产建议开启 autosign 按域名白名单自动签发，减少人力；同时用 roles/profiles + Hiera 收敛清单，降低耦合。磁盘与内存充足时可将 -Xmx512m 提到 1G，但仍不建议沿用包默认的 2G。

十一、常见问题

11.1 问题 1：puppet lookup 查不到 nodes/<主机名>.yaml 的覆盖值？

层级按 trusted.certname 匹配；在 Server 上手工 puppet lookup 用的是 Server 自身 certname，不会读到 Agent 的节点文件。请在目标 Agent 上下文编译或在该主机上执行 lookup。

11.2 问题 2：cron 资源报 Could not find a suitable provider for cron？

目标机未安装 cron。package { 'cron': ensure => installed } 后再应用。

11.3 问题 3：puppet parser validate 校验不通过？

多数是清单语法/缩进/引号问题。可用 puppet apply --noop 试编译并查看报错定位。

十二、参考链接

本文档由 www.quzuo.net 平台开发