An environment is a branch that gets turned into a directory on your Puppet master. They follow several conventions.
When you create an environment, you give it the following structure:
It contains a
modules directory, which becomes part of the environment’s default module path.
It contains a
manifests directory, 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.conf file, which can locally override configuration settings, including
Note: Environment names can contain lowercase letters, numbers, and underscores. They must match the following regular expression rule: \A[a-z0-9_]+\Z
An environment specifies resources that the Puppet master will use when compiling catalogs for agent nodes. The
modulepath, the main manifest, hiera data, and the config version script, can all be specified in
modulepath is the list of directories Puppet will load modules from.
By default, Puppet will load modules first from the environment’s
modules directory, and second from the master’s
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: The modulepath (default config)
The main manifest is Puppet’s starting point for compiling a catalog.
Unless you say otherwise in
environment.conf, an environment will use Puppet’s global
default_manifest setting to determine its main manifest.
The default value of
./manifests - the environment’s own manifests directory.
default_manifestis 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.confwill not be used by an environment.
Related topics: Hiera: Config file syntax.
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).
An environment can contain an
environment.conf file, which can override values for certain settings.
environment.conf file overrides these settings:
Related topics: environment.conf
Environments are turned on by default. Create an environment by adding a new directory of configuration data.
To create a new environment:
environmentsdirectory, 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.
modulepath in its
environment.conf file (If you set a value for this setting, the global
modulepath setting from
puppet.conf will not be used by an environment).
modulepath by 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, every environment must include
modulepath, since PE uses modules in that directory to configure its own infrastructure.
Configure a main manifest:
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.
disable_per_environment_manifestsetting - preventing any environment setting its own main manifest.
To specify an executable script that will determine an environment’s config version:
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).
Note: If you’re using a system binary like git
rev-parse, make sure to 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.
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:
environmentkey is set in the YAML output that the ENC returns. If the
environmentkey isn’t set in the ENC’s YAML output, the Puppet master will use the environment requested by the agent.
Note: The value from the ENC is authoritative, if it exists. If the ENC doesn’t specify an environment, the node’s config value is used.
Related topics: writing ENCs
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.
Configure an agent to use an environment by editing the agent’s
puppet.conffile in an editor.
environmentsetting in either the agent or main section.
environmentsetting to the name of the environment you want the agent to be assigned to.
When that node requests a catalog from the Puppet 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.
Note: Nodes can’t be assigned to unconfigured environments. If a node is assigned to an environment that doesn’t exist — no directory of that name in any of the environment path directories — the Puppet master will fail to compile its catalog. The one exception to this is if the default production environment doesn’t exist. In this case, the agent will successfully retrieve an empty catalog.
The settings in the master’s
puppet.conf file configure how Puppet finds and uses environments.
environmentpathis the list of directories where Puppet will look for environments. The default value for
temp_environmentswill be searched before
environmentpathsetting in the main section of the
basemodulepathlists directories of global modules that all environments can access by default.
basemodulepathsetting configures the global module directories. By default, it includes
$codedir/modulesfor user-accessible modules and
/opt/puppetlabs/puppet/modulesfor system modules.
Related topics: modulepath.
default_manifestspecifies the main manifest for any environment that doesn’t set a manifest value in
./manifests- the environment’s own manifests directory.
Related topics: default_manifest setting.
disable_per_environment_manifestlets you specify that all environments use a shared main manifest.
disable_per_environment_manifestis set to true, Puppet will use the same global manifest for every environment.
environment.conf, Puppet will not compile catalogs nodes in that environment, to avoid serving catalogs with potentially wrong contents.
default_manifestvalue must be an absolute path.
environment_timeoutsets how often the Puppet master refreshes information about environments. It can be overridden per-environment.
enviroment_timeout is how often the Puppet master should cache the data it loads from an environment. For best performance, change the settings once you have a mature code deployment process.
environment_timeout = unlimitedin
environment-cacheAPI endpoint. Ensure you have write access to the puppet-admin section of the
restart.txtfile to refresh an application without restarting Apache. See the Passenger docs for details.
environment-timeout setting can be overridden per-environment in
Note: Only use the value 0 or unlimited. Most Puppet masters use a pool of Ruby interpreters, which all have their own cache timers. When these timers are out of sync, agents can be served inconsistent catalogs. To avoid that inconsistency, refresh the Puppet master when deploying.