An environment is a branch that gets turned into a directory on your master.
A master serves each environment with its own main manifest and module path. This lets you use different versions of the same modules for different groups of nodes, which is useful for testing changes to your code before implementing them on production machines.
Access environment name in manifests
If you want to share code across environments, use the
$environment variable in
To get the name of the current environment:
- Use the
$environmentvariable, which is set by the master.
The main uses for environments fall into three categories: permanent test environments, temporary test environments, and divided infrastructure.
Permanent test environments
In a permanent test environment, there is a stable group of test nodes where all changes must succeed before they can be merged into the production code. The test nodes are a smaller version of the whole production infrastructure. They are either short-lived cloud instances or longer-lived virtual machines (VMs) in a private cloud. These nodes stay in the test environment for their whole lifespan.
Temporary test environments
In a temporary test environment, you can test a single
change or group of changes by checking the changes out of version control into the
directory, where it will be detected as a new environment. A temporary test
environment can either have a descriptive name or use the commit ID from the version
that it is based on. Temporary environments are good for testing individual changes,
especially if you need to iterate quickly while developing them. Once you’re done
with a temporary environment, you can delete it. The nodes in a temporary
environment are short-lived cloud instances or VMs, which are destroyed when the
If parts of your infrastructure are managed by different teams that do not need to coordinate their code, you can split them into environments.
Environments have limitations, including leakage and conflicts with exported resources.
Plugins can leak between environments
Environment leakage occurs when different versions of Ruby files, such as resource types, exist in multiple environments. When these files are loaded on the master, the first version loaded is treated as global. Subsequent requests in other environments get that first loaded version. Environment leakage does not affect the agent, as agents are only in one environment at any given time. For more information, see below for troubleshooting environment leakage.
Exported resources can conflict or cross over
Nodes in one environment can collect resources that were exported from another environment, which causes problems — either a compilation error due to identically titled resources, or creation and management of unintended resources. The solution is to run separate masters for each environment if you use exported resources.
Troubleshoot environment leakage
Environment leakage is one of the limitations of environments.
For resource types, you can avoid environment leaks with the the
puppet generate typescommand as described in environment isolation documentation. This command generates resource type metadata files to ensure that each environment uses the right version of each type.
This issue occurs only with the
Puppet::Parser::FunctionsAPI. To fix this, rewrite functions with the modern functions API, which is not affected by environment leakage. You can include helper code in the function definition, but if helper code is more complex, package it as a gem and install for all environments.
Report processors and indirector termini are still affected by this problem, so put them in your global Ruby directories rather than in your environments. If they are in your environments, you must ensure they all have the same content.