An environment is a branch that gets turned into a directory on your primary Puppet server. 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 is 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 primary server uses 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 Puppet loads modules from. By default, Puppet loads modules first from the environment’s
directory, and second from the primary server's
setting, which can be multiple directories. If the modules directory is empty or
absent, Puppet only uses modules from directories in
Related topics: module path.
The main manifest
The main manifest is the starting point for compiling a catalog. Unless you say
environment.conf, an environment uses 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
share, or a relative path to a file or directory inside each environment.
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 does 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
not be used by an environment.
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 is 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
which can override values for certain settings.
environment.conf file overrides these
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 contain your Puppet code.
environment.conffile . If you set a value for this setting, the global
puppet.confis not used by an environment.
modulepathby specifying the environment when requesting the setting value:
$ sudo puppet config print modulepath --section server --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, because 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 determines an environment’s config
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.confis not used by an environment.
rev-parse, specify the absolute path to it. If
config_versionis set to a relative path, Puppet looks for the binary in the environment, not in the system’s PATH.
- Specify a path to the script in the
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 is 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 primary server uses 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 primary server, it requests that environment. If you are using an ENC and it specifies an environment for that node, it overrides whatever is in the config file.
Global settings for configuring environments
The settings in the primary server's
puppet.conf file configure how
Puppet finds and uses environments.
environmentpath setting is the list of directories where
Puppet looks for environments. The default value
you have more than one directory, separate them by colons and put them in order of
temp_environmentsis 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
basemodulepath setting lists directories of global modules that
all environments can access by default. Some modules can be made available to all
basemodulepath setting configures the global
By default, it includes
$codedir/modules for user-accessible modules
/opt/puppetlabs/puppet/modules for system modules.
Add additional directories containing global modules by setting your own value for
Related topics: modulepath.
environment_timeout setting sets how often the primary
server refreshes information about environments. It can be overridden
This setting defaults to 0 (caching disabled), which lowers the performance of your primary server but makes it easy for new users to deploy updated Puppet code. After 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.
disable_per_environment_manifest setting lets you specify
that all environments use a shared main manifest.
disable_per_environment_manifest is set to true, Puppet uses the same global manifest for every
environment. If an environment specifies a different manifest in
environment.conf, Puppet does
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 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 primary Puppet server caches the data it loads from an environment.
For best performance, change the settings after you have a mature code deployment
environment_timeout = unlimitedin
Change your code deployment process to refresh the primary server whenever you
deploy updated code. For example, set a postrun command in your r10k config or add a step to your continuous
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 primary server, 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