Configuring Puppet Server

After you've installed Puppet Enterprise, optimize it for your environment by configuring Puppet Server settings as needed.

Tune the Ruby load path

The ruby_load_path setting determines where Puppet Server finds components such as Puppet and Facter.

The default setting is located at $puppetserver_jruby_puppet_ruby_load_path = ['/opt/puppetlabs/puppet/lib/ruby/vendor_ruby', '/opt/puppetlabs/puppet/cache/lib'].
Note: If you change the libdir you must also change the vardir.

To change the path to a different array in pe.conf:

  1. Add the following to your pe.conf file on your primary server and set your new load path parameter.
    puppet_enterprise::master::puppetserver::puppetserver_jruby_puppet_ruby_load_path
  2. Run puppet agent -t

Tune the multithreaded server setting

The jruby_puppet_multithreaded setting allows you to enable multithreaded mode, which uses a single JRuby instance to process requests, like catalog compiles, concurrently. The setting defaults to false.

To enable or disable the setting using Hiera:

  1. Add the following code to your default .yaml file and set the parameter to true (enable) or false (disable). For example:
    puppet_enterprise::master::puppetserver::jruby_puppet_multithreaded: <true or false>
  2. To compile the changes, run puppet agent -t

Enable or disable cached data when updating classes

The optional environment-class-cache-enabled setting specifies whether cached data is used when updating classes in the console. When true, Puppet Server refreshes classes using file sync, improving performance.

The default value for environment-class-cache-enabled depends on whether you use Code Manager.

  • With Code Manager, the default value is enabled (true). File sync clears the cache automatically in the background, so clearing the environment cache manually isn't required when using Code Manager.

  • Without Code Manager, the default value is disabled (false).

Note: If you're not using Code Manager and opt to enable this setting, make sure your code deployment method — for example r10k — clears the environment cache when it completes. If you don't clear the environment cache, the Node Classifier doesn't receive new class information until Puppet Server is restarted.

To enable or disable the cache using Hiera:

  1. Add the following code to your default .yaml file and set the parameter to the appropriate setting.
    puppet_enterprise::master::puppetserver::
               jruby_environment_class_cache_enabled: <true OR false>
  2. To compile the changes, run puppet agent -t

Change the environment_timeout setting

The environment_timeout setting controls how long the primary server caches data it loads from an environment, determining how much time passes before changes to an environment's Puppet code are reflected in its environment.

In PE, the environment_timeout is set to 0. This lowers the performance of your primary server but makes it easy for new users to deploy updated Puppet code. Once your code deployment process is mature, change this setting to unlimited.
Note: When you install Code Manager and set the code_manager_auto_configure parameter to true, environment_timeout is updated to unlimited

To change the environment_timeout setting using pe.conf:

  1. Add the following to your pe.conf file on your primary server and specify either 0 or unlimited:
    puppet_enterprise::master::environment_timeout:<time>
  2. Run puppet agent -t
Results

For more information, see Environments limitations

Add certificates to the puppet-admin certificate allowlist

Add trusted certificates to the puppet-admin certificate allowlist.

To add allowed certificates using pe.conf:

  1. Add the following code to your pe.conf file on your primary server and add the desired certificates.
    puppet_enterprise::master::puppetserver::puppet_admin_certs:'example_cert_name'
  2. Run puppet agent -t

Disable update checking

Puppet Server (pe-puppetserver) checks for updates when it starts or restarts, and every 24 hours thereafter. It transmits basic, anonymous info to our servers at Puppet by Perforce to get update information. You can optionally turn this off.

Specifically, it transmits:

  • Product name

  • Puppet Server version

  • IP address

  • Data collection timestamp

To turn off update checking using the console:

  1. Open the console, click Node groups, and select the PE Master node group.
  2. On the Classes tab, find the puppet_enterprise::profile::master class, add the check_for_updates parameter from the list, and change its value to false.
  3. Click Add parameter and commit changes.
  4. On the nodes hosting the primary server and console, run Puppet.

Puppet Server configuration files

At startup, Puppet Server reads all of the .conf files in the conf.d directory (/etc/puppetlabs/puppetserver/conf.d).

The conf.d directory contains the following files:

File name Description
auth.conf Contains authentication rules and settings for agents and API endpoint access.
global.conf Contains global configuration settings for Puppet Server, including logging settings.
metrics.conf Contains settings for Puppet Server metrics services.
pe-puppet-server.conf Contains Puppet Server settings specific to Puppet Enterprise.
webserver.conf Contains SSL service configuration settings.
ca.conf (Deprecated) Contains rules for Certificate Authority services. Superseded by webserver.conf and auth.conf.

For information about Puppet Server configuration files, see Puppet Server's config files for the Puppet Server version you're using, and the Related information links below.

pe-puppet-server.conf settings

The pe-puppet-server.conf file contains Puppet Server settings specific to Puppet Enterprise, with all settings wrapped in a jruby-puppet section.

enable-file-sync-locking or file_sync::file_sync_locking_enabled
Controls whether the file sync client locks the JRuby pool (and, by extension, most requests to Puppet Server) while deploying Puppet code.
Default: true
CAUTION: We do not recommend changing the enable-file-sync-locking setting. Instead, enable Lockless code deploys, which allow the file sync client to update code into versioned code directories without blocking Puppet Server requests or overwriting the live code directory.
gem-home
Determines where JRuby looks for gems. It is also used by the puppetserver gem command line tool.
Default: '/opt/puppetlabs/puppet/cache/jruby-gems'
jruby_max_active_instances
Controls the maximum number of JRuby instances to allow on the Puppet Server.
Default: 4
master-conf-dir
Sets the Puppet configuration directory's path.
Default: /etc/puppetlabs/puppet
master-var-dir
Sets the Puppet variable directory's path.
Default: /opt/puppetlabs/server/data/puppetserver
max_requests_per_instance
Sets the maximum number of requests allowed for each JRuby interpretor instance before it is killed.
Default: 100000
max-queued-requests
Sets the maximum number of requests allowed to be queued waiting to borrow from the JRuby pool.
This setting is optional and defaults to 0 (unlimited). If set, specify a positive integer.
After reaching the limit, all new requests receive a 503 Service Unavailable response until the queue drops below the limit. If the max-retry-delay setting is also set to a positive integer, then the 503 response includes a random sleep time after which the client can retry the request.
Don't use this setting if your managed infrastructure includes multiple agents older than Puppet 5.3. Because older agents treat 503 responses as failures, a thundering herd problem occurs when the agents schedule their next runs at the same time.
max-retry-delay
Sets the maximum number of seconds allowed for the random sleep time set when the max-queued-requests limit is exceeded. The random sleep time is returned as a Retry-After header on the 503 response for each rejected request.
Default: 1800 seconds
If max-queued-requests is 0, there is no limit to the number of queued requests and, therefore, the max-retry-delay is irrelevant.
pre-commit-hook-commands or puppetserver::pre_commit_hook_commands
Specify scripts, as an array of strings, that you want the file sync storage server to execute against a repo after receiving a change but before committing and syncing the change across compilers. This is similar to Configuring postrun commands for r10k or Configuring post-environment hooks for Code Manager.
Scripts are executed in the order supplied by the pe-puppetserver process as the pe-puppet user. You must supply scripts as absolute paths. Additionally, the pe-puppet user must be able to execute the scripts, and the scripts must be able to consume stdin (even if the script doesn't do anything with it).
Default: ["/opt/puppetlabs/server/bin/generate-puppet-types.rb"]
CAUTION: Removing the default value disables the generate-puppet-types.rb script. Unless you intentionally want to disable this type generation method, make sure to keep the default path in the array.
The output, error, and exit code for these scripts are logged at the trace level of pe-puppetserver logs when the exit code is 0. If the exit code is not 0, the codes are logged at the error level.
This setting is managed in PE modules, and you can override it by setting the puppet_enterprise::master::puppetserver::pre_commit_hook_commands parameter in Hiera. Make sure to include the default path (for generate-puppet-types.rb) to ensure custom type are correctly cached. If you want to disable all pre-commit commands, supply an empty array in Hiera.
puppet-code-repo
Identifies, as a string, the internal name for the Puppet code repo (the codedir) that contains all code to sync across compilers (including user-supplied code repos).
CAUTION: Do not change this setting.
Default: 'puppet-code'
ruby-load-path
Sets the Puppet configuration directory's path. The agent's libdir path is included by default.
Default: '/opt/puppetlabs/puppet/lib/ruby/vendor_ruby', '/opt/puppetlabs/puppet/cache/lib'