An environment-based testing workflow is an effective approach for testing new code before pushing it to production.
- Root All Nodes node group.
All Environments parent node group. All environment node groups must be
children of this group. The Puppet environment
assigned to this group is the default Puppet
environment used for nodes without an assigned or matched default environment.
Tip: If this group doesn't exist, you should create it.
Environment node groups. Environment node groups are used to specify the
Puppet environment that nodes belong to.
Nodes can belong to no more than one environment node group. The group it
belongs to determines its default environment.
Each environment node group must meet these conditions:
- Must be a direct child of the All Environments node group
- Must not include child groups, except any one-time run exception subgroups used for canary testing
- Must be specified as an environment group in the group metadata
- Must not include classes or configuration data
- Optional one-time run exception group. This group acts as a gatekeeper, and when present, permits nodes in the parent environment group to temporarily use Puppet environments other than their normal default environment.
- PE Infrastructure node group and its children. These are built-in classification node groups used to manage infrastructure nodes. Don't modify these groups except when following official documentation or support instructions.
Classification node groups. Classification node groups are used to apply
classes and configuration data to nodes. Nodes can match more than one
classification node group.
Each classification node group must meet these conditions:
- Must be a child of All Nodes or another classification group
- Must not be specified as an environment group in the group metadata
Test and promote a parameter
Test and promote a parameter when using an environment-based testing workflow.
- Create a classification node group with the test environment that is a child of a classification group that uses the production environment.
- In the child group, set a test parameter. The test parameter overrides the value set by the parent group using the production environment.
- If you're satisfied with your test results, manually change the parameter in the parent group.
- Delete the child test group.
Test and promote a class
Test and promote a class when using an environment-based testing workflow.
Create a classification node group with the test environment that is a child
of a classification group that uses the production environment.
The node classifier validates your parameters against the test environment.
- Add the class you would like to test.
- If you're satisfied with your test results, promote your code to production and manually add the class in the parent node group.
- Delete the child test group.
Test code with canary nodes and alternate Puppet environments
You can test new code using one-time Puppet agent runs on select canary nodes.
To enable the canary workflow, configure a one-time run exception child group for each environment group in which you want to test code. This group matches nodes on the fly when you run Puppet with the environment specified.
In this example, we configure a one-time run exception environment group as a child of the Development environment. You can create a similar group for any environment.
Create the one-time run exception group with these options:
- Name — Development one-time run exception
- Parent — Development environment
- Environment — agent-specified
- Environment group — checked
Create a rule to match nodes to this group if they request a Puppet environment other than their
This rule matches any node from the parent group that requests the use of a non-default environment using either the
agent_specified_environmentTip: This fact name doesn't autocomplete.
- Operator — ~
- Value — .+
--environmentflag on the command line or the
- Fact — agent_specified_environment
On any node in the Development environment group, run
puppet agent -t --environment <ENVNAME>, where
<ENVNAME>is the name of the Puppet environment that contains your test code.If you're using Code Manager and a Git workflow,
<ENVNAME>is the name of your Git development or feature branch.During this Puppet run, the agent sets the
<ENVNAME>. The Development one-time run exception group matches the node and permits it to use the requested environment.
Sample rules for one-time run exception groups
These examples show several ways to configure rules for one-time run exception child groups. Where multiple rules are listed, combine the rules by specifying that nodes must match all rules.
|Permit any node in the parent environment group to use any Puppet environment||agent_specified_environment||~||.+|
|Permit RHEL nodes in the parent environment group to use any Puppet environment||agent_specified_environment||~||.+|
|Permit any nodes in the parent environment group to use any Puppet environment except production||agent_specified_environment||~||.+|
|Permit any nodes in the parent environment group to use any Puppet environment that begins with the prefix "feature_||agent_specified_environment||~||^feature_.+|