Included in Puppet Enterprise 3.7. A newer version is available; see the version menu above for details.
Config File Environments Are Deprecated
In Puppet 4, directory environments will always be enabled. This means the
environmentpathsetting must point to a valid directory (defaulting to
$confdir/environments), and Puppet won’t allow you to set
In this version of Puppet, the Puppet master will log deprecation warnings if your puppet.conf file:
- Contains any environment config blocks
- Sets global values for the
$environmentvariable won’t log warnings.)
When you have time, you should read up on directory environments and start using them.
This frees you to use different versions of the same modules for different populations of nodes, which is useful for testing changes to your Puppet code before implementing them on production machines. (You could also do this by running a separate Puppet master for testing, but using environments is often easier.)
Directory Environments vs. Config File Environments
There are two ways to set up environments on a Puppet master: directory environments, and config file environments.
This page is about config file environments, which are deprecated and are more complex to use. You should consider moving to directory environments soon.
Setting Up Environments on a Puppet Master
Puppet’s config file provides two ways to configure environments: per-environment config sections, and interpolation of the
$environment variable in settings values (AKA dynamic environments).
Environment Config Sections
The puppet.conf file has four primary config sections. The Puppet master application will usually use settings from the
master section, and will fall back to the
main section for settings that aren’t defined in
You can also make additional config sections for environments. If available, Puppet will use settings from an environment config section when serving nodes assigned to that environment. If an environment-specific section doesn’t exist or doesn’t set values for some settings, Puppet will fall back to the
master and then
main sections as normal.
[main] server = puppet.example.com certname = puppetmaster1.example.com trusted_node_data = true [master] dns_alt_names = puppetmaster1.example.com,puppetmaster1,puppet.example.com,puppet autosign = false [test] modulepath = $confdir/environments/test/modules:$condfir/modules:/usr/share/puppet/modules manifest = $confdir/environments/test/manifests config_version = /usr/bin/git --git-dir $confdir/environments/test/.git rev-parse HEAD
In this example, the
test environment has its own separate values for the
config_version settings, and Puppet will use those when serving nodes in that environment. When serving nodes in other environments, the Puppet master will use the global values for those settings, which in this example are left to their defaults.
Only certain settings can be used in an environment config section. Although Puppet will allow you to set any settings there, it will only actually read and use a few of them. Those usable settings are:
templatedir setting will also work, but we recommend against using the old-style global template directory.
Alternately, you can use the global values for the
manifest settings (via the
main section), but set their values to use the special
$environment variable. (Note that if an environment config section exists for the active environment, it will get priority.)
When getting values for settings, Puppet will replace
$environment with the name of the active environment. This allows you to mimic directory environments:
[master] manifest = $confdir/environments/$environment/manifests modulepath = $confdir/environments/$environment/modules
In this example, you could create a directory for each environment in the
When using dynamic environments, there’s not a very good way to set
config_version. Possibly due to the timing of how settings are loaded, interpolation of
$environment in that setting doesn’t seem to work. In a future version of Puppet, directory environments will provide a cleaner way to do this.
Similarly, you shouldn’t interpolate
$environment into any other settings besides
modulepath; the results are likely to be unpredictable.
Environment names can contain letters, numbers, and underscores. That is, they must match the following regular expression:
Additionally, there are four forbidden environment names:
These names can’t be used because they conflict with the primary config sections. This can be a problem with Git, because its default branch is named
master. You may need to rename the
master branch to something like
git branch -m master production).
No Interaction with Directory Environments
If directory environments are enabled (by setting the
environmentpath setting; see Enabling Directory Environments), any config file environments will be completely ignored.
If you’ve accidentally configured the same environment in multiple ways (see the page on directory environments), the precedence goes like this:
Config sections → directory environments → dynamic (
If an environment config section exists for the active environment, Puppet will ignore the directory environment it would have otherwise used. This means it will use the standard
modulepath settings to serve nodes in that environment. If values for those settings are specified in the environment config section, those will be used; otherwise, Puppet will use the global values.
Similarly, if the global
$environment, any config section environments will override them.
Unconfigured Environments → Global Settings
If a node is assigned to an environment for which a config section doesn’t exist, or if the config section does not specify a value for one or more settings, the Puppet master will use the global
modulepath settings to serve that node.
If the values of the
modulepath settings point to any files or directories that don’t exist (due to interpolating
$environment for an unexpected environment name), Puppet will act as though those directories were empty.
Referencing the Environment in Manifests
In Puppet manifests, you can get the name of the current environment by using the
$environment variable, which is set by the Puppet master.
Tuning Environment Caching
With config file environments, there’s very little performance to be gained by tuning the
environment_timeout setting. It can be ignored until you’re ready to switch to directory environments.
Other Information About Environments
This section of the Puppet reference manual has several other pages about environments:
- Suggestions for Use — common patterns and best practices for using environments.
- Limitations of Environments — environments mostly work, but they can be a bit wobbly in several situations.
- Environments and Puppet’s HTTPS Interface — this page explains how environment information is embedded in Puppet’s HTTPS requests, and how you can query environment data in order to build Puppet extensions.