A node definition or node statement is a block of Puppet code that will only be included in matching nodes’ catalogs. This feature allows you to assign specific configurations to specific nodes.
Node statements are an optional feature of Puppet. They can be replaced by or combined with an external node classifier, or you can eschew both and use conditional statements with facts to classify nodes.
Unlike more general conditional structures, node statements only match nodes by name. By default, the name of a node is its certname (which defaults to the node’s fully qualified domain name).
Node definitions should go in the main manifest. The main manifest can be a single file, or a directory containing many files.
# <ENVIRONMENTS DIRECTORY>/<ENVIRONMENT>/manifests/site.pp
node 'www1.example.com' {
include common
include apache
include squid
}
node 'db1.example.com' {
include common
include mysql
}
In the example above, only www1.example.com
would receive the apache and squid classes, and only db1.example.com
would receive the mysql class.
Node definitions look like class definitions. The general form of a node definition is:
node
keywordAside: Best practices
Although node statements can contain almost any Puppet code, we recommend that you only use them to set variables and declare classes. Avoid using resource declarations, collectors, conditional statements, chaining relationships, and functions in them; all of these belong in classes or defined types.
This will make it easier to switch between node definitions and an ENC.
Node statements match nodes by name. A node’s name is its unique identifier; by default, this is its certname setting, which in turn defaults to the node’s fully qualified domain name.
Note on Non-Certname Node Names
Although it’s possible to set something other than the certname as the node name (using either the
node_name_fact
ornode_name_value
setting), we don’t generally recommend it. It allows you to re-use one node certificate for many nodes, but it reduces security, makes it harder to reliably identify nodes, and can interfere with other features.Setting a non-certname node name is not officially supported in Puppet Enterprise.
A node statement’s name must be one of the following:
_
), hyphens (-
), and periods (.
).default
.You cannot create two node statements with the same name.
You can use a comma-separated list of names to create a group of nodes with a single node statement:
node 'www1.example.com', 'www2.example.com', 'www3.example.com' {
include common
include apache, squid
}
This example creates three identical nodes: www1.example.com
, www2.example.com
, and www3.example.com
.
The name default
(without quotes) is a special value for node names. If no node statement matching a given node can be found, the default
node will be used. See Behavior below.
Regular expressions (regexes) can be used as node names. This is another method for writing a single node statement that matches multiple nodes.
Note: Make sure all of your node regexes match non-overlapping sets of node names. If a node’s name matches more than one regex, Puppet makes no guarantee about which matching definition it will get.
node /^www\d+$/ {
include common
}
The above example would match www1
, www13
, and any other node whose name consisted of www
and one or more
digits.
node /^(foo|bar)\.example\.com$/ {
include common
}
The above example would match foo.example.com
and bar.example.com
, but no other nodes.
If the main manifest contains at least one node definition, it must have one for every node; compilation for a node will fail if one cannot be found. (Hence the usefulness of the default
node.) If the main manifest contains no node definitions, this requirement is dropped.
A given node will only get the contents of one node definition, even if two node statements could match a node’s name. Puppet will do the following checks in order when deciding which definition to use:
www01.example.com
isn’t found, Puppet will look for a definition matching www01.example
.)default
node.Thus, for the node www01.example.com
, Puppet would try the following, in order:
www01.example.com
www01.example.com
www01.example
www01.example
www01
www01
default
You can turn off this fuzzy name matching by changing the Puppet master’s strict_hostname_checking
setting to true
. This will cause Puppet to skip step 3 and only use the node’s full name before resorting to default
.
Regex node definitions will set numbered regex capture variables ($1, $2, etc.) within the body of the node definition. This is similar to the behavior of conditional statements that use regexes.
Puppet code that is outside any node statement will be compiled for every node. That is, a given node will get both the code in its node definition and the code outside any node definition.
Node definitions create a new anonymous scope that can override variables and defaults from top scope. See the section on node scope for details.
Node definitions and external node classifiers can co-exist. Puppet merges their data as follows:
Although ENCs and node definitions can work together, we recommend that most users pick one or the other.
In earlier versions of the Puppet language, nodes could inherit from other nodes using the inherits
keyword. We removed that feature, and this version of the language will raise an error if you try to use it.