Grouping and Classifying Nodes

A newer version is available; see the version menu above for details.

To start classifying your nodes, go to the Puppet Enterprise (PE) console and click Nodes > Classification. This takes you to a list of node groups.

PE comes with several preconfigured node groups to help you manage your PE infrastructure. To learn more about these preconfigured node groups, see Preconfigured Node Groups.

viewing list of node groups

You should create two different types of node groups in PE:

  • Environment node groups, which assign environments to nodes.
  • Classification node groups, which assign classification data to nodes.

In other words, a given node group should assign environments or classification data, not both.


The node classifier uses role-based access control (RBAC) to manage access to tasks, including the tasks described on this page. For info about managing access, see the RBAC documentation.

Creating Environment Node Groups

The only role of an environment node group is to set the environment for your nodes. Environment node groups should not contain any classification data.

More on environments from the Puppet reference manual:

PE comes with two preconfigured environment node groups: the Production environment node group and the Agent-specified environment node group.

  • The Production environment group comes with a rule that matches all nodes, and assigns the production environment. This means your nodes will default to the production environment unless you specify otherwise.
  • The Agent-specified environment group matches no nodes by default. It doesn’t assign an environment, which lets its nodes use the environment from their config file. Add nodes to this group if you need to preserve an agent-specified environment in your installation. For more information, see The Agent-Specified Environment Node Group.

To create a new environment node group:

  1. In the Node group name box, enter a name that describes the role of this environment node group, such as “Test environment”.
  2. In the Parent name box, set the parent to be Production environment. Every environment node group you add must be a descendent of the Production environment group; otherwise it won’t be able to override which environment its nodes are assigned to.
  3. In the Environment box, specify the environment you want to assign to the nodes that match this node group. If you haven’t created any environments yet, you will only see the production and agent-specified environments in the drop-down list.
  4. Click Add group to add the environment node group.
  5. This step is very important and should not be skipped. In the list of node groups, find the new group that you just created and click it. Click Edit node group metadata. Select the This is an environment group checkbox. The environment will not be enforced unless you select this checkbox.
  6. Click the commit button to commit your change.

Note: For more information on using environments in the PE console, see Working With Environments.

Creating Classification Node Groups

The role of a classification node group is to assign classification data (classes, parameters, and variables) to nodes.

  1. To add a new classification node group, in the Node group name box in the Classification page, enter a name that describes the function of the nodes that match this node group. For example, “web servers.”

  2. In the Parent name box, select the name of the classification node group that you want to set as the parent to this node group. Classification node groups inherit classes, parameters, and variables from their parent node group. By default, the parent node group is the All Nodes node group.

    Node group inheritance is an important feature in node classification that can save you a lot of time. For example, if you have a class that needs to be assigned to all of a node group’s descendent node groups, then you can assign it once in the parent node group and avoid having to assign it in each descendent node group. For an overview of node group inheritance, see How Does Inheritance Work?.

  3. In the Environment box, you can specify an environment for filtering the classes and parameters that are available for selection in this node group. This does not assign an environment to any nodes. You did that when you set up the environment node groups.

    For example, if you want to apply some test classification data to your development web server nodes, you would add the nodes to your test environment through the environment node group, and then set the test environment here in the classification node group so that only your test classification is available for selection.

    Important: Do not select This is an environment group. This option should only be set when you are configuring environment node groups.

  4. To finish creating the node group, click Add Group.

To change a classification node group later, see:

Adding Nodes to a Node Group

There are two ways to add nodes to a node group:

  1. Create rules that match node facts (dynamic)

  2. Individually pin nodes to the node group (static)

Adding Nodes Dynamically

Rules are by far the most powerful and scalable way to include nodes in a node group. You can create rules in a node group that are used to match node facts. When nodes match the rules in a node group, they are classified with all of the classification data (classes, parameters, and variables) that has been set for the node group.

When nodes no longer match the rules of a node group, the classification data for that node group no longer applies to the node.

Note: Structured facts (arrays and hash map values) are not supported when using the console to enter facts.

To add a rule:

  1. Click Nodes > Classification, and click the group that you want to add the rule to.

  2. Go to the Rules tab.

  3. Select a Fact.

    When you click in the Fact field, a list of known facts appears. These are the facts that are stored in PuppetDB. They include things like the operating system (operatingsystem), the amount of memory (memorytotal), and the primary IP address (ipaddress).

    Tip: The list of facts uses autosuggest with fuzzy matching. As you type a search string in Fact, the list filters to show facts that contain the search string anywhere within the fact name. In other words, if you are looking for uptime_days, you can simply type “time.”

  4. Specify an Operator and Value for the fact.

    You can get really specific about the nodes that you want to match by setting Operator to matches regex or does not match regex and specifying a regular expression for Value.

    Note: The greater than, greater than or equal to, less than, and less than or equal to operators can only be used with facts that have a numeric value.

    After you have entered the Fact, Operator, and Value, the number of nodes that match your new rule will appear under Node matches. This is a great way to confirm that you have specified a valid rule.

    As an example of how you could specify a rule, say that you have set up a Web Servers node group and now you want to add all of your web servers to this node group. You can do this by creating a rule similar to:

       “hostname”   matches regex   “web”

    If at any point you change the role of one of the web server nodes and remove “web” from the name, that node no longer matches the rule for being included in the Web Servers node group and will no longer be configured with the classes that have been applied by the node group.

  5. Whenever you make a change in the node classifier, you need to commit the change. At the lower right of the page, click the commit button.

Note: In the Rules tab, there is an option that let’s you select whether your nodes need to match All rules before they are added to the node group, or if they should be added when they match Any of the rules.

Adding Nodes Statically

If you have a node that needs to be in a node group regardless of the rules that have been specified for that node group, you can pin the node to the node group. A pinned node is not affected by rules and will remain in the node group until you manually remove it. Adding a pinned node essentially creates the rule <the certname of your node> is <the certname>, and includes this rule along with the other fact-based rules.

To pin a node to a node group:

  1. In the Rules tab, scroll down to the pinned nodes section below the rules.

  2. In the Certname field, enter the certname of the node.

  3. Click Pin node, and then click the commit button.

Removing Nodes From a Node Group

Adding Classes to a Node Group

Classes are the blocks of Puppet code used to configure your nodes and assign resources to them. To add a class to a node classification group, first create the class in a module. You’ll then need to install the module.

Creating Puppet classes

Before you can add a class to a node group, you need to make the class available to the Puppet master. This means that the class must be located in an installed module. There are two ways to get modules:

  1. Download modules from the Puppet Forge. In addition to the many public modules that are available, the Puppet Forge also provides supported modules and approved modules. Supported modules are rigorously tested with PE and are supported by Puppet Labs via the usual support channels. Approved modules have passed PuppetLabs quality and reliability standards and are recommended by Puppet Labs for use with PE.

  2. Write your own classes, and put them in a module.

Tip: If you are new to Puppet and have not written Puppet code before, follow the Learning Puppet tutorial, which walks you through the basics of Puppet code, classes, and modules.

To add a class to a node group:

  1. On the Classification page, click the node group that you want to add the class to, and then click Classes.

  2. Under Add new class, click the Class name field.

    A list of classes appears. These are the classes that the Puppet master knows about and are available in the environment that you have set for the node group. The list filters as you type. Filtering is not limited to the start of a class name, you can also type substrings from anywhere within the class name. Select the class when it appears in the list.

  3. Click Add class and then click the commit button.

Note: If you created a new class within the last three minutes, it may not appear in the list of available classes yet. There are two things that need to happen before the class appears in the list:

  1. The node classifier needs to retrieve classes from the master. (By default, the node classifier retrieves classes from the master every 3 minutes. To change the default setting, see Configuring and Tuning the Console).

  2. The environment cache needs to refresh. (By default, the environment cache refreshes every 3 minutes.)

To override the default refresh period and force the node classifier to retrieve the classes from the master immediately, click the Refresh button.

Removing Classes From a Node Group

Defining the Data Used by Classes

You can use either parameters or variables to define the data used by classes. Parameters are scoped to the class, while variables are scoped to the node group.

Setting Class Parameters

Classes will automatically use default parameters and values, or parameters and values inherited from parent node groups. However, if the nodes in a node group need to be an exception to the general case, you can override default and parent values by specifying new parameter values.

To add a parameter:

  1. In Classes, click the Parameter name drop-down list under the appropriate class and select the parameter to add. The drop-down list shows all of the parameters that are available in the node group’s environment.

  2. When you select a parameter, the Value field is automatically populated with the default value. To change the value, type the new value in the Value field.

Tips on specifying parameter and variable values

Parameters and variables can be structured as JSON. If they cannot be parsed as JSON, they will be treated as strings.

Parameters and variables can be specified using the following data types and syntax:

  • Strings (e.g. "centos")
    • Variable-style syntax, which interpolates the result of referencing a fact (e.g. "I live at $ipaddress.")
    • Expression-style syntax, which interpolates the result of evaluating the embedded expression (e.g. ${$os["release"]["full"]})
  • Booleans (e.g. true or false)
  • Numbers (e.g. 123)
  • Hashes (e.g. {"a": 1})
  • Arrays (e.g. ["1","2.3"])

Variable-style syntax

Variable-style syntax uses a dollar sign ($) followed by a Puppet fact name.

Example: "I live at $ipaddress"

Variable-style syntax is interpolated as the value of the fact. For example, $ipaddress resolves to the value of the ipaddress fact.

Indexing cannot be used in variable-style syntax because the indices are treated as part of the string literal. For example, given the following fact:

processors => {"count" => 4, "physicalcount" => 1},

if you use variable-style syntax to specify $processors[count], the value of the processors fact is interpolated but it is followed by a literal “[count]”. After interpolation, this example becomes {"count" => 4,"physicalcount" => 1}[count].

Note: Do not use the :: top-level scope indication because the console is not aware of Puppet’s variable scope.

Expression-style syntax

Use expression-style syntax when you need to index into a fact (${$os[release]}), refer to trusted facts ("My name is ${trusted[certname]}"), or delimit fact names from strings ("My ${os} release").

The following is an example of using expression-style syntax to access the full release number of an operating system:


Expression-style syntax uses:

  • an initial dollar sign and curly brace (${), followed by
  • a legal Puppet fact name preceded by an optional dollar sign, followed by
  • any number of index expressions (the quotations around indices are optional but are required if the index string contains spaces or square brackets), followed by
  • a closing curly brace (}).

Indices in expression-style syntax can be used to access individual fields of structured facts, or to refer to trusted facts. Use strings in an index if you want to access the keys of a hashmap. If you want to access a particular item or character in an array or string based on the order in which it is listed, you can use an integer (zero-indexed).

Examples of legal expression-style interpolation:

  • ${os}
  • ${$os}
  • ${$os[release]}
  • ${$os['release']}
  • ${$os["release"]}
  • ${$os[2]} (accesses the value of the third (zero-indexed) key-value pair in the os hash)
  • ${$os[release][2]} (accesses the value of the third key-value pair in the release hash)

In the PE console, an index can only be simple string literals or decimal integer literals. An index cannot include variables or operations (such as string concatenation or integer arithmetic).

Examples of illegal expression-style interpolation:

  • ${$::os}
  • {$os[$release]}
  • ${$os[0xff]}
  • ${$os[6/3]}
  • ${$os[$family + $release]}
  • ${$os + $release}

Trusted facts

Trusted facts are considered to be keys of a hashmap called trusted. This means that all trusted facts must be interpolated using expression-style syntax. For example, the certname trusted fact would be expressed like this: "My name is ${trusted[certname]}". Any trusted facts that are themselves structured facts can have further index expressions to access individual fields of that trusted fact. For an overview of trusted facts, see the Puppet Reference Manual.

Note: Regular expressions, resource references, and other keywords (such as ‘undef’) are not supported.

Editing Parameters

Deleting Parameters

Setting Variables

Variables set in the console become top-scope variables available to all Puppet manifests. When you define a variable, any class in the node group that references the variable will be given the value that you set here.

To set a variable:

  1. To access a node group’s variables, on the Classification page, select the node group.

  2. Click Variables.

  3. For Key, enter the name of the variable.

  4. For Value, enter the value that you want to assign to the variable.

  5. Click Add variable, and then click the commit button.

Note: For information on the permitted syntax for specifying variable values, see “Tips on specifying parameter and variable values” in Setting Class Parameters.

Note: Nodes can match multiple node groups, and node groups are not necessarily arranged in a strict hierarchy. It is therefore possible for two equal node groups to contribute conflicting values for variables and class parameters. Conflicting values will cause a Puppet run on an agent to fail.

Editing variables

Deleting variables

Viewing the Nodes That Are in a Node Group

To view all nodes that currently match the rules specified for a node group:

  1. Go to the Classification page and click the node group.

  2. Click Matching nodes.

    You will see the number of nodes that match the node group’s rules, along with a list of the names of matching nodes. This is based on the facts collected during the node’s last Puppet run. The matching nodes list is updated as rules are added, deleted, and edited. Don’t forget that nodes must match rules in ancestor node groups as well as the rules of the current node group before they are actually considered to be a matching node.

Note: If you have not set any rules for this node group yet, there will not be any matching nodes.

Viewing the Nodes Managed By Puppet

To view the total number of nodes currently being managed by Puppet, go to Nodes > Inventory. At the top of the page, you will see the number of nodes that have checked in with a Puppet master since the last deletion of data from PuppetDB.

This page also shows a list of the managed nodes.

↑ Back to top