根本原因是模块路径配置错误，puppet仅在默认路径（如/etc/puppetlabs/code/environments/production/modules）或–modulepath指定路径下查找模块；模块名须与目录名一致、小写无下划线，init.pp须位于manifests/子目录。
为什么 puppet apply 总报错说找不到模块？
根本原因不是模块没写，而是 Puppet 默认只在 /etc/puppetlabs/code/environments/production/modules 或当前目录的 modules/ 下找——你把模块放错了位置，它就当不存在。
- 检查模块路径：运行
puppet config print modulepath，看输出是否包含你放模块的实际目录 - 临时指定路径更可靠：用
puppet apply --modulepath ./my_modules site.pp，避免依赖全局配置 - 别用
git clone直接扔进modules/顶层：Puppet 要求每个模块是独立子目录，比如modules/nginx/，而不是modules/puppet-nginx/ - 模块名必须和目录名完全一致（小写、无下划线），
init.pp必须在modules/<strong>nginx</strong>/manifests/init.pp，否则class nginx就加载失败
如何让 file { '/etc/motd': } 真正生效而不被覆盖？
直接写资源声明容易被其他模块或系统服务抢写，关键在控制所有权和触发时机。
- 加
replace => true强制覆盖，但要小心：如果 motd 是其他服务生成的（如issue-generator），Puppet 每次运行都会把它打回原形 - 用
notify => Service['rsyslog']这类链式触发不适用；motd 不是服务，改完不用重启啥——重点是确保它不被后续流程覆盖 - 更稳的做法：配合
exec资源先停掉干扰进程，比如exec { 'stop-motd-gen': command => '/bin/systemctl stop motd-news.service', path => ['/bin', '/usr/bin'] }，再声明file - 注意权限：Puppet 默认以 root 跑，但若用
--user测试，file资源会因权限不足静默失败，错误日志里只显示 “failed to set mode”
puppet agent -t 卡住不动，连 master 都没连上？
不是网络不通，大概率是证书或主机名没对上。Puppet 的 TLS 握手比 http 严格得多。
- 先查证书状态：
puppet cert list --all，如果 agent 主机名不在列表里，master 根本不会响应请求 - 确认
/etc/puppetlabs/puppet/puppet.conf里[agent] server = puppetmaster.local的值，能nslookup解析，且和 master 的证书 CN 完全一致（大小写敏感） - 常见坑：用 IP 当 server 地址，但 master 证书是用域名签发的 → 不匹配，握手直接断开，
-t就卡在 “Applying configuration version” 前 - 调试加
--debug，但别只扫日志末尾：关键线索在 “Could not request certificate: SSL_connect returned=1 errno=0 state=Error: certificate verify failed” 这一行
为什么 class 参数传进去，$myvar 在模板里还是空？
变量作用域没透过去，不是语法错，是 Puppet 的作用域继承规则在起作用。
- 模板里用
，前提是这个变量在调用template()的上下文中已定义；class nginx($myvar = 'default') { ... }里的$myvar不自动暴露给模板 - 正确做法：在 class 内显式传参，比如
content => template('nginx/vhost.erb')改成content => template('nginx/vhost.erb', { 'myvar' => $myvar }) - 或者改用
scope.lookupvar('nginx::myvar')，但强耦合命名空间，维护性差 - 注意：Hiera 数据自动注入只对 class 参数有效，对模板变量无效——别指望
hiera.yaml里配了nginx::myvar，模板就能直接用@myvar
事情说清了就结束。Puppet 的坑不在语法多难，而在它把很多隐式约定（路径、证书、作用域、权限）绑得太紧，改一处常牵出三处失效。