Grouping and classifying nodes

Types of node groups

You can create two types of node groups:

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

A node group assigns either environment or classification data, not both. The role of an environment node group is to set the environment, such as test, development, or production, for your nodes. The role of a classification node group is to assign classification data, such as classes, parameters, and variables, to nodes.

Tip: For more information on using an environment-based workflow in the PE console, see Working With Environments.

Important: 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.

Preconfigured environment node groups

To help you manage your infrastructure, PE comes with several preconfigured node groups, including two environment node groups:

  • 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. This group doesn’t assign an environment, so nodes that you add to the group use the environment from their config file. Add nodes to this group if you need them to preserve their agent-specified environment.

For more information about these and other preconfigured node groups, see Preconfigured Node Groups.

Creating environment node groups

Create environment node groups so that your nodes aren’t all in the production environment.

  1. In the PE console, click Nodes > Classification, then click Add group.
  2. Specify options for the new node group:
    • Parent name – Select Production environment. Every environment node group you add must be a descendent of this group. This lets the new group inherit the ability to override a member node’s agent-specified environment setting.
    • Group name – Enter a name that describes the role of this environment node group, for example, Test environment.
    • Environment – Select the environment that you want to assign to nodes that match this node group. If you haven’t created environments yet, you see only the production and agent-specified environments.
    • Environment group – Select this option.
  3. Click Add.

You can now add nodes to your environment node group to control which environment each node belongs to.

Creating classification node groups

  1. In the PE console, click Nodes > Classification, then click Add group.
  2. Specify options for the new node group:
    • Parent name – 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.

      Tip: Node group inheritance allows you to assign a class once in a parent node group and avoid assigning it in each descendent node group. For more information about node group inheritance, see How Does Inheritance Work?

    • Group name – Enter a name that describes the role of this classification node group, for example, Web Servers.

    • Environment – Specify an environment to limit the classes and parameters available for selection in this node group.

      Note: Specifying an environment in a classification node group doesn’t assign an environment to any nodes, as it does in an environment node group.

    • Environment groupDo not select this option.

  3. Click Add.

You can now add nodes to your classification node group dynamically or statically. After that, you can specify the Puppet classes you want to apply to the nodes in the classification node 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) 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 via the usual support channels. Approved modules have passed Puppet’s quality and reliability standards and are recommended by Puppet 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