Puppet Agent获取的Catalog与Master不一致，请求排查原因

问题现象 #

• Agent执行puppet agent --test显示配置应用成功，但耗时仅0.01秒，实际无任何配置生效
• Master本地执行puppet catalog find grid.lan能生成正确Catalog，但Agent端执行相同命令或puppet catalog find返回空结果
• 重启Master和Agent服务后问题依旧
• Master日志显示已接收并编译Agent的Catalog请求，但Agent始终获取空Catalog

环境信息 #

Agent配置与安装步骤 #

Agent采用默认配置，安装命令如下：

cd /tmp
wget https://apt.puppet.com/puppet8-release-jammy.deb
sudo dpkg -i puppet8-release-jammy.deb
apt-get update -y && apt-get install puppet-agent -y
export PATH=/opt/puppetlabs/bin:$PATH

puppet agent --test

Master配置信息 #

Master将manifest存储在NFS共享目录（挂载于/puppet），相关配置如下：

/etc/puppetlabs/puppet/puppet.conf

# This file can be used to override the default puppet settings.
# See the following links for more details on what settings are available:
# - https://puppet.com/docs/puppet/latest/config_important_settings.html
# - https://puppet.com/docs/puppet/latest/config_about_settings.html
# - https://puppet.com/docs/puppet/latest/config_file_main.html
# - https://puppet.com/docs/puppet/latest/configuration.html
[server]
vardir = /opt/puppetlabs/server/data/puppetserver
logdir = /var/log/puppetlabs/puppetserver
rundir = /var/run/puppetlabs/puppetserver
pidfile = /var/run/puppetlabs/puppetserver/puppetserver.pid
codedir = /etc/puppetlabs/code
 
[main]
environment = production
basemodulepath = /puppet/modules
[agent]
runinterval = 1m

/etc/puppetlabs/code/environments/production/environment.conf

modulepath = /puppet/production/modules/
manifest = /puppet/production/manifests/

已通过puppet config print manifest --section main --environment production验证路径配置正确。

问题排查与解决方案 #

1. 核对Agent端核心配置 #

执行以下命令确认Agent的Master地址和环境配置：

puppet config print server --section agent
puppet config print environment --section agent

• 确保server值与Master主机名完全一致，且Agent能正常解析该主机名的IP
• 确认environment值为production，与Master配置匹配

2. 检查NFS目录权限 #

Puppetserver进程以puppet用户运行，需确保NFS挂载目录对该用户有读取权限：

ls -ld /puppet
ls -ld /puppet/production/manifests
sudo -u puppet cat /puppet/production/manifests/site.pp  # 替换为你的主manifest文件

若puppet用户无法读取manifest文件或目录，需在NFS服务端调整共享权限（如设置anonuid/anongid为puppet用户的UID/GID）。

3. 查看Master编译日志细节 #

修改Master日志级别，捕获编译过程的报错信息：

• 编辑/etc/puppetlabs/puppetserver/logback.xml，将com.puppetlabs的日志级别改为DEBUG
• 重启服务：sudo systemctl restart puppetserver
• 触发Agent请求后，查看/var/log/puppetlabs/puppetserver/puppetserver.log，搜索Compiled catalog for相关内容，确认是否存在文件读取失败、语法错误等问题

4. 验证SSL证书信任关系 #

执行puppet agent --test --debug，查看Agent端输出中关于证书验证、Catalog传输的细节；同时在Master端执行puppet cert list，确认Agent证书已被签署：

puppet cert sign grid.lan  # 若证书未签署，执行此命令

5. 修正environment.conf路径格式 #

去掉路径末尾的斜杠，修改为：

modulepath = /puppet/production/modules
manifest = /puppet/production/manifests

部分Puppet版本对路径末尾的斜杠解析存在异常，会导致无法识别manifest目录。

6. 确认manifest节点匹配规则 #

检查/puppet/production/manifests下的文件，确保存在匹配Agent节点grid.lan的规则：

# 示例：匹配指定节点
node 'grid.lan' {
  # 配置内容
}

# 或匹配所有节点
node default {
  # 配置内容
}

若没有匹配的节点规则，Master会生成空Catalog。

内容的提问来源于stack exchange，提问作者Jens Sels