An environment is a branch that gets turned into a directory on your Puppet master. Environments are turned on by default.
The structure of an environment follows several conventions.
When you create an environment, you give it the following structure:
It contains a
modulesdirectory, which becomes part of the environment’s default module path.
It contains a
manifestsdirectory, which will be the environment’s default main manifest.
If you are using Puppet 5, it can optionally contain a
It can optionally contain an
environment.conffile, which can locally override configuration settings, including
manifest.Note: Environment names can contain lowercase letters, numbers, and underscores. They must match the following regular expression rule:
\A[a-z0-9_]+\Z. If you are using Puppet 5, remove the
An environment specifies resources that the master will
use when compiling catalogs for agent nodes. The
modulepath, the main manifest, Hiera data, and the config version script, can all be
modulepath is the list of directories will load modules from. By
default, will load modules first from the environment’s directory, and second from
basemodulepath setting, which can be multiple
directories. If the modules directory is empty or absent, Puppet will only use modules from directories in the
Related topics: module path.
The main manifest
The main manifest is the starting point for compiling a catalog.
Unless you say otherwise in
environment.conf, an environment will use the global
default_manifest setting to determine its main
manifest. The value of this setting can be an absolute path to a manifest that all
environments will share, or a relative path to a file or directory inside each
The default value of
./manifests — the environment’s own manifests directory. If the file
or directory specified by
default_manifest is empty or absent, Puppet will not fall back to any other manifest.
Instead, it behaves as if it is using a blank main manifest. If you specify a value
for this setting, the global manifest setting from
puppet.conf will not be used by an environment.
Related topics: main manifest, environment.conf, default_manifest setting, puppet.conf.
Each environment can use its own Hiera hierarchy and provide its own data.
Related topics: Hiera config file syntax.
The config version script
Puppet automatically adds a config version to every catalog it compiles, as well as to messages in reports. The version is an arbitrary piece of data that can be used to identify catalogs and events. By default, the config version will be the time at which the catalog was compiled (as the number of seconds since January 1, 1970).
The environment.conf file
An environment can contain an
environment.conf file, which can
override values for certain settings.
environment.conf file overrides
Related topics: environment.conf
Create an environment
Create an environment by adding a new directory of configuration data.
- Inside your code directory, create a directory called environments.
Inside the environments directory, create a directory with the name of your new
environment using the structure:
modulesdirectory and a
manifestsdirectory. These two directories will contain your Puppet code.
environment.conffile . If you set a value for this setting, the global
puppet.confwill not be used by an environment.
modulepathby specifying the environment when requesting the setting value:
$ sudo puppet config print modulepath --section master --environment test /etc/puppetlabs/code/environments/test/modules:/etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules.Note: In Puppet Enterprise (PE), every environment must include
modulepath, since PE uses modules in that directory to configure its own infrastructure.
Configure a main manifest:
Set manifest in its
environment.conffile. As with the global
default_manifestsetting, you can specify a relative path (to be resolved within the environment’s directory) or an absolute path.
Lock all environments to a single global
manifest with the
disable_per_environment_manifestsetting — preventing any environment setting its own main manifest.
- Set manifest in its
To specify an executable script that will determine an
environment’s config version:
Note: If you’re using a system binary like git
Specify a path to the script in the
config_versionsetting in its
environment.conffile. Puppet runs this script when compiling a catalog for a node in the environment, and uses its output as the config version. If you specify a value here, the global
puppet.confwill not be used by an environment.
rev-parse, specify the absolute path to it. If
config_versionis set to a relative path, Puppet will look for the binary in the environment, not in the system’s PATH.
- Specify a path to the script in the
Related topics: Deploying environments with r10k, Code Manager control repositories, disable_per_environment_manifest
Assign nodes to environments via an ENC
You can assign agent nodes to environments by using an external node classifier (ENC). By default, all nodes are assigned to a default environment named production.
The interface to set the environment for a node will be different for each ENC. Some ENCs cannot manage environments. When writing an ENC:
- Ensure that the environment key is set in the YAML output that the ENC returns. If the environment key isn’t set in the ENC’s YAML output, the master will use the environment requested by the agent.
Assign nodes to environments via the agent's config file
You can assign agent nodes to environments by using the agent’s config file. By default, all nodes are assigned to a default environment named production.
To configure an agent to use an environment:
Open the agent's
puppet.conffile in an editor.
environmentsetting in either the agent or main section.
Set the value of the
environmentsetting to the name of the environment you want the agent to be assigned to.
When that node requests a catalog from the master, it will request that environment. If you are using an ENC and it specifies an environment for that node, it will override whatever is in the config file.
Global settings for configuring environments
The settings in the master’s
puppet.conf file configure how Puppet finds and uses environments.
environmentpath setting is the list of directories where Puppet will look for environments. The default
$codedir/environments. If you have more than
one directory, separate them by colons and put them in order of precedence.
temp_environmentswill be searched before
If environments with the same name exist in both paths, Puppet uses the first environment with that name that it encounters.
environmentpath setting in the main section of the
setting lists directories of global modules that all environments can access by default.
Some modules can be made available to all environments. The
basemodulepath setting configures the global module
By default, it includes
$codedir/modules for user-accessible modules and
/opt/puppetlabs/puppet/modules for system
Add additional directories containing global modules
by setting your own value for
Related topics: modulepath.
setting sets how often the master refreshes information about environments. It can be
This setting defaults to 0 (caching disabled), which 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 unlimited.All code in Ruby and Puppet loaded from the environment is cached. Inputs to compilation (for example, facts and looked up values) and the resulting catalog, are not cached.
lets you specify that all environments use a shared main manifest.
disable_per_environment_manifest is set to true, Puppet will use the same global manifest for every
environment. If an environment specifies a different manifest in
environment.conf, Puppet will not compile catalogs nodes in that
environment, to avoid serving catalogs with potentially wrong contents.
If this setting is set to true, the
default_manifest value must be an absolute path.
default_manifest setting specifies the main manifest for any environment
that doesn’t set a manifest value in
environment.conf. The default value of
./manifests — the environment’s own manifests directory.
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.
Related topics: default_manifest setting.
Configure the environment timeout setting
enviroment_timeout setting determines how often the Puppet master caches the data it loads from an environment. For
best performance, change the settings once you have a mature code deployment
environment_timeout = unlimitedin
Change your code deployment process to refresh the
master whenever you deploy updated code. For example, set a postrun command in your
r10k config or add a step to
your continuous integration job.
With Puppet Server, refresh environments by calling the
environment-cacheAPI endpoint. Ensure you have write access to the puppet-admin section of the
With a Rack master, restart the web server or the application server. Passenger lets you touch a
restart.txtfile to refresh an application without restarting Apache. See the Passenger docs for details.
environment-timeoutsetting can be overridden per-environment in