Configuring Environments
Included in Puppet Enterprise 2015.2. A newer version is available; see the version menu above for details.
Global Settings for Configuring Environments
Puppet uses five settings in puppet.conf to configure the behavior of environments:
environmentpath
is the list of directories where Puppet will look for environments.basemodulepath
lists directories of global modules that all environments can access by default.default_manifest
specifies the main manifest for any environment that doesn’t set amanifest
value in environment.conf.disable_per_environment_manifest
lets you specify that all environments should use a shared main manifest. This requiresdefault_manifest
to be set to an absolute path.environment_timeout
sets how often the Puppet will refresh information about environments. It can be overridden per-environment.
environmentpath
The Puppet master will only look for environments in certain directories, listed by the environmentpath
setting in puppet.conf. The default value for environmentpath
is $codedir/environments
. (See here for info on the codedir.)
If you need to manage environments in multiple directories, you can set environmentpath
to a colon-separated list of directories. (For example: $codedir/temporary_environments:$codedir/environments
.) When looking for an environment, Puppet will search these directories in order, with earlier directories having precedence.
Note that if multiple copies of a given environment exist in the environmentpath
, Puppet will use the first one. It won’t use any content from the other copies.
The environmentpath
setting should usually be set in the [main]
section of puppet.conf.
basemodulepath
Although environments should contain their own modules, you might want some modules to be available to all environments.
The basemodulepath
setting configures the global module directories. By default, it includes $codedir/modules
for user-accessible modules and /opt/puppetlabs/puppet/modules
for system modules.
To add additional directories containing global modules, you can set your own value for basemodulepath
. See the page on the modulepath for more details.
Note: In Puppet Enterprise, the
basemodulepath
must always include the system module directory.
default_manifest
(See also: Full description of default_manifest
setting.)
The default main manifest to use for environments that don’t specify a manifest in environment.conf.
The default value of default_manifest
is ./manifests
— that is, the environment’s own manifests
directory. (In Puppet versions prior to 3.7, this wasn’t configurable.)
The value of this setting can be:
- An absolute path to one manifest that all environments will share
- A relative path to a file or directory inside each environment’s directory
disable_per_environment_manifest
Setting disable_per_environment_manifest = true
will cause Puppet to use the same global manifest for every environment. If an environment specifies a different manifest in environment.conf, Puppet will refuse to compile catalogs nodes in that environment (to avoid serving catalogs with potentially wrong contents).
This requires default_manifest
to be an absolute path.
environment_timeout
(See also: Full description of environment_timeout
setting.)
How long the Puppet master should cache the data it loads from an environment. For performance reasons, we recommend changing this setting once you have a mature code deployment process.
This setting defaults to 0
(caching disabled), which lowers the performance of your Puppet master but makes it easy for new users to deploy updated Puppet code.
For best performance, you should:
- Set
environment_timeout = unlimited
in puppet.conf. - Change your code deployment process to refresh the Puppet master whenever you deploy updated code. (For example, set a
postrun
command in your r10k config or add a step to your CI job.)- With Puppet Server, refresh environments by calling the
environment-cache
API endpoint. You may need to allow access in puppetserver.conf’spuppet-admin
section. - With a Rack Puppet master, restart the web server or the
application server. Passenger lets you touch a
restart.txt
file to refresh an application without restarting Apache; see the Passenger docs for details.
- With Puppet Server, refresh environments by calling the
This setting can be overridden per-environment in environment.conf, but most users should avoid doing that.
Note: We don’t recommend using any value other than
0
orunlimited
, since most Puppet masters use a pool of Ruby interpreters which all have their own cache timers. When these timers drift out of sync, agents can be served inconsistent catalogs. To avoid that inconsistency, you have to refresh your Puppet master when deploying anyway, which means there’s no benefit to not usingunlimited
.