Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Managing nodes Grey arrow pointing right Environment-based testing Grey arrow pointing right

Environment-based testing

Sections

An environment-based testing workflow is an effective approach for testing new code before pushing it to production.


Graphic showing how to set up environment and classification node groups to enable environment-based testing.
  1. Root All Nodes node group.
  2. 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.
  3. 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
  4. 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.
  5. 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.
  6. 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.

  1. Create a classification node group with the test environment that is a child of a classification group that uses the production environment.
  2. In the child group, set a test parameter. The test parameter overrides the value set by the parent group using the production environment.
  3. If you're satisfied with your test results, manually change the parameter in the parent group.
  4. Delete the child test group.

Test and promote a class

Test and promote a class when using an environment-based testing workflow.

  1. 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.
  2. Add the class you would like to test.
  3. If you're satisfied with your test results, promote your code to production and manually add the class in the parent node group.
  4. 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.

Before you begin
You must have configured an environment group other than All Environments in which to test code.

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.

  1. 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
  2. Create a rule to match nodes to this group if they request a Puppet environment other than their default.
    • Fact — agent_specified_environment
      Tip: This fact name doesn't autocomplete.
    • Operator — ~
    • Value — .+
    This rule matches any node from the parent group that requests the use of a non-default environment using either the --environment flag on the command line or the environment setting in puppet.conf.
  3. 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 agent_specified_environment value to <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.

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_.+