Puppetserver安装gem后Puppet自定义函数无法调用该gem的问题

问题根源 #

Puppet Server的自定义函数运行在隔离的JRuby子进程中，和puppetserver irb使用的主JRuby环境并非同一上下文——哪怕你通过puppetserver gem install安装了目标gem，自定义函数的运行环境可能并未包含该gem的加载路径，因此会出现找不到文件的报错。

解决办法 #

1. 将gem路径添加到Puppet Server的JRuby全局配置 #

• 执行puppetserver gem environment获取gem的安装目录，通常路径为/opt/puppetlabs/server/data/puppetserver/jruby-gems/gems/
• 编辑配置文件/etc/puppetlabs/puppetserver/conf.d/jruby.conf，在jruby-puppet区块中添加gem-path配置：

  jruby-puppet:
    gem-path: "/opt/puppetlabs/server/data/puppetserver/jruby-gems/gems/activerecord-jdbcsqlite3-adapter-[你的版本号]/lib:/opt/puppetlabs/server/data/puppetserver/jruby-gems/gems/jdbc-sqlite3-[对应依赖版本]/lib"
  

  注意替换成实际的版本号，同时必须包含依赖的jdbc-sqlite3 gem路径，否则仍会加载失败。
• 重启Puppet Server生效：systemctl restart puppetserver

2. 在自定义函数内手动指定加载路径 #

如果不想修改全局配置，可在函数代码中手动将gem的lib目录加入加载路径后再require：

Puppet::Functions.create_function(:你的自定义函数名) do
  def 你的自定义函数名()
    # 替换为实际的gem安装路径
    gem_lib_dir = "/opt/puppetlabs/server/data/puppetserver/jruby-gems/gems/activerecord-jdbcsqlite3-adapter-[版本号]/lib"
    $LOAD_PATH.unshift(gem_lib_dir) unless $LOAD_PATH.include?(gem_lib_dir)
    require 'activerecord-jdbcsqlite3-adapter'
    # 后续业务逻辑代码
  end
end

3. 排查Puppet环境隔离问题 #

如果使用了Puppet多环境（如production、development），需确认gem安装在全局路径而非用户隔离目录。可执行puppetserver gem install --no-user-install activerecord-jdbcsqlite3-adapter强制将gem安装到服务器全局gem目录，避免环境隔离导致的路径不可见。

4. 调试加载路径定位差异 #

若以上方法无效，可在自定义函数中添加调试代码，对比当前环境与puppetserver irb的加载路径差异：

Puppet::Functions.create_function(:debug_gem_env) do
  def debug_gem_env()
    Puppet.notice("当前LOAD_PATH: #{$LOAD_PATH}")
    Puppet.notice("已加载gem列表: #{Gem.loaded_specs.keys}")
  end
end

运行该函数后，查看Puppet Server日志/var/log/puppetlabs/puppetserver/puppetserver.log，将日志中的加载路径和gem列表与puppetserver irb中输出的内容对比，即可定位路径差异点。

内容的提问来源于stack exchange，提问作者Maxim Maximov