You can create two types of node groups:
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.
To help you manage your infrastructure, PE comes with several preconfigured node groups, including two environment node groups:
For more information about these and other preconfigured node groups, see Preconfigured Node Groups.
Create environment node groups so that your nodes aren’t all in the production environment.
You can now add nodes to your environment node group to control which environment each node belongs to.
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 group – Do not select this option.
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:
There are two ways to add nodes to a node group:
Create rules that match node facts (dynamic)
Individually pin nodes to the node group (static)
Rules are 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’re classified with all of the classification data (classes, parameters, and variables) 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.
To add a rule:
In the console, click Nodes > Classification, and then find the node group that you want to add the rule to and select it.
On the Rules tab, specify rules for the fact, then click Add rule.
Option | Definition |
---|---|
Fact | Specifies the fact used to match nodes. Select from the list of known facts, or enter part of a string to view fuzzy matches. To use structured or trusted facts, select the initial value from the dropdown list, then type the rest of the fact.
Tip: Structured and trusted facts don't provide type-ahead suggestions beyond the top-level name key, and the facts aren't verified when entered. After adding a rule for a structured or trusted fact, review the number of matching nodes to verify that the fact was entered correctly. |
Operator | Describes the relationship between the fact and value. Operators include:
The numeric operators >, >=, <, and <= can be used only with facts that have a numeric value. To match highly specific node facts, use ~ or !~ with a regular expression for Value. |
Value | Specifies the value associated with the fact. |
(Optional) Repeat step 2 as needed to add more rules.
Tip: If the node group includes multiple rules, be sure to specify whether nodes are added when they match All or Any of the rules.
Commit changes.
Structured facts group a set of related facts in the form of a hash or array. For example, the structured fact os
includes multiple independent facts about the operating system, including architecture, family, and release. In the console, when you view facts about a node, you can differentiate structured facts because they’re surrounded by curly braces.
Trusted facts are a specific type of structured fact where the facts are immutable and extracted from a node’s certificate. Because they can’t be changed or overridden, trusted facts enhance security by verifying a node’s identity before sending sensitive data in its catalog. For details, see More about certificate extensions.
You can use structured and trusted facts in the console to dynamically add nodes to groups.
Note: If you’re using trusted facts to specify certificate extensions, in order for nodes to match to rules correctly, you must use short names for Puppet-specific registered IDs and numeric IDs for private extensions. Numeric IDs are required for private extensions whether or not you specify a short name in the custom_trusted_oid_mapping.yaml
file.
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>
= <the certname>
, and includes this rule along with the other fact-based rules.
To pin a node to a node group:
In the console, click Nodes > Classification, and then find the node group that you want to pin a node to and select it.
On the Rules tab, in the pinned nodes section, enter the Certname of the node.
Click Pin node, and then commit changes.
Removing Nodes From 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:
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.
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:
In the console, click Nodes > Classification, and then find the node group that you want to add the class to and select it.
On the Classes tab, in the Add new class field, select the class to add.
The Add new class field suggests classes that the Puppet master knows about and that are available in the environment set for the node group. The list filters as you type. You can enter substrings from anywhere within the class name.
Click Add class and then commit changes.
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:
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).
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
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.
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:
In the console, click Nodes > Classification, and then find the node group that you want to add a parameter to and select it.
On the Classes tab, 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.
(Optional) Change the default Value. When you select a parameter, the Value field is automatically populated with the default value.
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
orfalse
)- 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 theipaddress
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 theprocessors
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:
${$os["release"]["full"]}
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 theos
hash)${$os[release][2]}
(accesses the value of the third key-value pair in therelease
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.
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:
In the console, click Nodes > Classification, and then find the node group that you want to set a variable for and select it.
On the Variables tab, enter options for the variable:
Key – Enter the name of the variable.
Value – Enter the value that you want to assign to the variable.
Click Add variable, and then commit changes.
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.
To view all nodes that currently match the rules specified for a node group:
In the console, click Nodes > Classification, and then find the node group that you want to view and select it.
Click Matching nodes.
You 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.
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.