Puppet配置出错怎么排查

Puppet 配置出错时，可以按「从本地到服务端、从语法到逻辑」的思路逐步排查。下面是一套比较系统的排查方法：

一、先看清楚错误本身

1. 在 Agent 上手动运行

puppet agent -t

或开启调试：

puppet agent -t --debug --verbose

重点看：

• 错误信息（Error / Warning）
• 出错的 manifest 文件 + 行号
• 是 编译阶段 还是 执行阶段 出错

二、区分错误类型

✅ 1. 语法错误（最常见）

表现：

• Syntax error
• Could not parse
• Unknown variable

排查：

puppet parser validate init.pp

或对整个环境：

puppet apply --parseonly site.pp

常见原因：

• 少了 { }、:
• = 和 => 混用
• 变量未定义就使用

✅ 2. 模板 / ERB 错误

表现：

• Could not evaluate
• undefined method
• .erb 报错

排查：

erb -x -T '-' template.erb | ruby -c

检查：

• 变量是否传进模板
• Ruby 语法是否正确

✅ 3. 资源冲突 / 重复定义

表现：

• Duplicate declaration
• Already defined

原因：

• 同一资源在多个 class 中定义
• include 和 require 混用

解决：

• 使用 resource 或 contain
• 统一在 profile / role 中管理

✅ 4. 依赖关系问题

表现：

• Could not find dependency
• 执行顺序不对

排查：

require => File['/etc/xxx']

确认：

• 被依赖资源 存在且名字一致
• 不在 if 里被跳过

三、服务端（Puppet Server）排查

1. 查看 server 日志

tail -f /var/log/puppetlabs/puppetserver/puppetserver.log

常见：

• catalog 编译失败
• hiera 数据找不到
• module 路径错误

2. 检查 environment

puppet config print environmentpath
ls /etc/puppetlabs/code/environments/

确认：

• agent 和 server 使用同一 environment
• module 已同步

四、Hiera 问题排查

1. 查看变量解析结果

puppet lookup xxx --explain

2. 常见问题

• hiera.yaml 层级写错
• YAML 缩进错误
• key 拼错

五、模块 / 路径问题

puppet module list

检查：

• 模块是否在 modulepath
• 版本是否冲突
• 是否缺失依赖

六、快速自查清单 ✅

• [ ] puppet agent -t --debug 看具体错误
• [ ] puppet parser validate
• [ ] 检查 .erb 模板
• [ ] 查看 server 日志
• [ ] hiera lookup 是否正常
• [ ] 是否有重复资源定义
• [ ] 环境 / modulepath 是否一致

七、如果你愿意，可以直接发我：

• 报错原文（完整）
• 相关 .pp 或 .erb 片段
• Puppet 版本

我可以帮你精准定位问题。