Configuring and tuning Puppet Server
After you've installed Puppet Enterprise, optimize it for your environment by configuring and tuning Puppet Server settings as needed.
See the configuration methods docs for information on how to configure settings.
Tune the maximum number of JRuby instances
jruby_max_active_instances setting controls the maximum number of JRuby instances to allow on the Puppet Server.
The default used in PE is the number of CPUs - 1, expressed as
$::processorcount - 1. One instance is the minimum value and four instances is the maximum value. Four JRuby instances work for most environments.
Increasing the JRuby instances increases the amount of RAM used by
pe-puppetserver. When you increase JRuby instances, increase the heap size. We conservatively estimate that a JRuby process uses 512MB of RAM.
- To change the number of instances using Hiera, add the following to your default
.yamlfile and set the desired number of instances:
puppet_enterprise::master::puppetserver::jruby_max_active_instances: <number of instances>
- Compile and view overrides.
Tune the Ruby load path
ruby_load_path setting determines where Puppet Server finds components such as Puppet and Facter.
The default setting is located here:
$puppetserver_jruby_puppet_ruby_load_path = ['/opt/puppetlabs/puppet/lib/ruby/vendor_ruby', '/opt/puppetlabs/puppet/cache/lib'].
- To change the path to a different array in
pe.conf, add the following to your
pe.conffile on your master and set your new load path parameter:
puppet agent -t.
Note that if you change the
libdir you must also change the
Tune the maximum requests per JRuby instance
max_requests_per_instance setting determines the maximum number of requests per instance of a JRuby interpreter before it is killed.
The appropriate value for this parameter depends on how busy your servers are and how much you are affected by a memory leak. By default,
max_requests_per_instance is set to 100,000 in PE.
When a JRuby interpreter is killed, all of its memory is reclaimed and it is replaced in the pool with a new interpreter. This prevents any one interpreter from consuming too much RAM, mitigating Puppet code memory leak issues and keeping Puppet Server up.
Starting a new interpreter has a performance cost, so set the parameter to get a new interpreter no more than every few hours. There are multiple interpreters running with requests balanced across them, so the lifespan of each interpreter varies.
- To increase
max_requests_per_instanceusing Hiera, add the following code to your default
.yamland set the desired number of requests:
puppet_enterprise::master::puppetserver::jruby_max_requests_per_instance: <number of requests>
- Compile and view overrides.
Enable or disable cached data when updating classes
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 (
- To enable or disable cached data using Hiera, add the following to your default
.yamlfile and set the parameter to
puppet_enterprise::master::puppetserver:: jruby_environment_class_cache_enabled: <true OR false>
- Compile and view overrides.
environment_timeout setting controls how long the master 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 master but makes it easy for new users to deploy updated Puppet code. Once your code deployment process is mature, change this setting to
environment_timeoutis updated to
pe.conf,add the following to your
pe.conffile on your master, then run
puppet agent -t.:
For more information, see Environments limitations.
Add certificates to the puppet-admin certificate whitelist
puppet-admin certificate whitelist as needed.
- To modify whitelist certificates using
pe.conf, insert the following in your
pe.conffile on your master and add certificates.
puppet_enterprise::master::puppetserver::puppet_admin_certs: - 'example_cert_name'
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, Inc. to get update information. You can optionally turn this off.
Specifically, it transmits:
Puppet Server version
Data collection timestamp
To turn off update checking using the console:
- Open the console, clickClassification, and select the node group that contains the class you want to work with.
- On the Configuration tab, find the
puppet_enterprise::profileclass and find the
check_for_updatesparameter from the list and change its value to
- Click Add parameter and commit changes.
- On the nodes hosting the master and console, run Puppet.
Puppet Server configuration files
At startup, Puppet Server reads all of the
.conf files in the
conf.d directory (
conf.d directory contains the following files:
||Contains authentication rules and settings for agents and API endpoint access.|
||Contains global configuration settings for Puppet Server, including logging settings.|
||Contains settings for Puppet Server metrics services.|
||Contains Puppet Server settings specific to Puppet Enterprise.|
||Contains SSL service configuration settings.|
||(Deprecated) Contains rules for Certificate Authority services. Superseded by
For information about Puppet Server configuration files, see Puppet Server's config files and the Related topics below.
This file contains Puppet Server settings specific to Puppet Enterprise, with all settings wrapped in a
- Determines where JRuby looks for gems. It is also used by the
puppetserver gemcommand line tool.
- Sets the Puppet configuration directory's path.
- Sets the Puppet variable directory's path.
Optional. Sets the maximum number of requests that may be queued waiting to borrow a from the pool. Once this limit is exceeded, a
503 Service Unavailableresponse is returned for all new requests until the queue drops below the limit.If
max-retry-delayis set to a positive value, then the 503 response includes a
Retry-Afterheader indicating a random sleep time after which the client may retry the request.Note: Don't use this solution if your managed infrastructure includes a significant number of agents older than Puppet 5.3. Older agents treat a 503 response as a failure, which ends their runs, causing groups of older agents to schedule their next runs at the same time, creating a thundering herd problem.
- Optional. Sets the upper limit in seconds for the random sleep set as a
Retry-Afterheader on 503 responses returned when
- Controls the maximum number of JRuby instances to allow on the Puppet Server.
- Sets the maximum number of requests per instance of a JRuby interpretor before it is killed.
- Sets the Puppet configuration directory's path. The agent's
libdirvalue is added by default.