Environment-based testing

The environment-based testing workflow lets you test new code before pushing it to production.

Setting up environment-based testing requires a specific node group hierarchy. Before setting up environment-based testing, make sure you understand Environment versus classification node groups and how to Create node groups.

The basic node group hierarchy for environment-based testing is as follows:
  1. All Nodes (root node group of all node groups)
    1. All Environments (parent of all environment node groups)
      1. Production environment node group
      2. Staging environment node group
      3. Test environment node group
        1. Test environment one-time run exception node group (Used to Test code with canary nodes and alternate Puppet environments)
      4. Development environment
        1. Development environment one-time run exception node group (Used to Test code with canary nodes and alternate Puppet environments)
    2. PE Infrastructure node group
    3. Classification node groups and their children (Child groups can be used to Test and promote a parameter or Test and promote a class)
The following screenshot and table explain the environment-based testing node-group hierarchy components:
A node group hierarchy for environment-based testing. Six call-out labels indicate various groups and their functions.
Call-out label Group name or category Description
1 All Nodes Root node group of all node groups. Its direct children are the All Environments node group, the PE Infrastructure node group, and the top-level classification node groups.
2 All Environments Each environment node group must be a child 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, create it.
3 Various environment node groups, each being direct children of All Environments Environment node groups specify the Puppet environment that your nodes belong to. Nodes can belong to only one environment node group, which determines the node's default environment.
4 Optional one-time run exception group, which is a direct child of a specific environment node group Used to Test code with canary nodes and alternate Puppet environments. This group acts as a gatekeeper, and, when present, permits nodes in the parent environment node group to temporarily use Puppet environments other than their normal default environment.

This is the only condition where it is possible for an environment node group to have a child group.
5 PE Infrastructure node group (and its child groups) 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.
6 Various classification node groups and their children Classification node groups apply classes and configuration data to nodes. Nodes can belong to multiple classification node groups. Child classification node groups can be used Test and promote a parameter or Test and promote a class.

Test and promote a parameter

Use an environment-based testing workflow to test and promote a parameter.

  1. Create a classification node group. Set the Environment as the test environment, and set the Parent as the equivalent production environment classification node group.
    By creating a test group associated with the test environment, the node classifier validates parameters against the test environment, rather than the production environment.
  2. In your new test group, set a parameter you want to test.
    Because you're setting the parameter on a child group, the test parameter overrides the value set by the parent group.
  3. If you're satisfied with the results of the test, manually edit the class parameter in the parent group to apply the change to the production environment.
  4. Delete the child group you used for testing.

Test and promote a class

Use an environment-based testing workflow to test and promote a class.

  1. Create a classification node group. Set the Environment as the test environment, and set the Parent as the equivalent production environment classification node group.
    By creating a test group associated with the test environment, the node classifier validates classes and parameters against the test environment, rather than the production environment.
  2. In your new test group, declare a class you want to test.
  3. If you're satisfied with the results of the test, apply the change to the production environment by promoting the code containing the new classes to production (if necessary) and declaring the class in the parent node group.
  4. Delete the child group you used for testing.

Test code with canary nodes and alternate Puppet environments

You can test new code using one-time Puppet agent runs on specific canary nodes.

Before you begin
You must Create environment node groups other than All Environments in which to test code, such as development or test environment node groups.

To enable the canary workflow, create a one-time run exception child group under each environment node group in which you want to test code. This group matches nodes on the fly when you run Puppet with the environment specified.

For example, the following steps create a one-time run exception environment group as a child of the Development environment node group. You can create a similar group for any environment you want to test.

  1. In the console, click Node groups, and click Add group.
  2. Create the one-time run exception environment node group with these options:
    • Name: <ENVIRONMENT> one-time run exception, such as Development one-time run exception
    • Parent: Whichever environment you are testing, such as the Development environment
    • Environment: Select agent-specified
    • Environment group: Select this option.
  3. Click Add.
  4. Dynamically add nodes to a node group by creating a rule to match nodes to this group if they request a Puppet environment other than their default environment:
    • Fact: agent_specified_environment
      Tip: This fact name doesn't autocomplete. You must manually type it.
    • Operator: ~
    • Value: .+
    This rule matches any node from the parent environment node group that requests to use a non-default environment, through either the --environment flag on the command line or the environment setting in puppet.conf. For other rules you might use, refer to Sample rules for one-time run exception groups.
  5. On any node in the parent environment node group (such as the Development environment group), run the following code: 
    puppet agent -t --environment <ENVNAME>
    Important: <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 agent_specified_environment value to <ENVNAME>. The one-time run exception group's rule 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.

Testing scenario Fact Operator Value
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 ~ .+
facts.os.family = RedHat
Permit any nodes in the parent environment group to use any Puppet environment except production agent_specified_environment ~ .+
agent_specified_environment != production
Permit any nodes in the parent environment group to use any Puppet environment that begins with the prefix "feature_ agent_specified_environment ~ ^feature_.+