Classifying nodes

You can classify nodes using an external node classifier (ENC), which is a script or application that tells Puppet which classes a node must have. It can replace or work in concert with the node definitions in the main site manifest (site.pp).

The external_nodes script receives the name of the node to classify as its first argument, which is usually the node's fully qualified domain name. For more information, see the Configuration reference.

Depending on the external data sources you use in your infrastructure, building an external node classifier can be a valuable way to extend Puppet.

You can use an ENC instead of or in combination with node definitions.

External node classifiers

An external node classifier is an executable that Puppet Server or puppet apply can call; it doesn’t have to be written in Ruby. Its only argument is the name of the node to be classified, and it returns a YAML document describing the node.

Inside the ENC, you can reference any data source you want, including PuppetDB. From Puppet’s perspective, the ENC submits a node name and gets back a hash of information.

External node classifiers can co-exist with standard node definitions in site.pp; the classes declared in each source are merged together.

Merging classes from multiple sources

Every node always gets a node object from the configured node terminus. The node object might be empty, or it might contain classes, parameters, and an environment. The node terminus setting, node_terminus, takes effect where the catalog is compiled, on Puppet Server when using an agent-server configuration, and on the node itself when using puppet apply. The default node terminus is plain, which returns an empty node object, leaving node configuration to the main manifest. The exec terminus calls an ENC script to determine what goes in the node object. Every node might also get a node definition from the main manifest.

When compiling a node's catalog, Puppet includes all of the following:

  • Classes specified in the node object it received from the node terminus.

  • Classes or resources that are in the site manifest but outside any node definitions.

  • Classes or resources in the most specific node definition in site.pp that matches the current node (if site.pp contains any node definitions). The following notes apply:

    • If site.pp contains at least one node definition, it must have a node definition that matches the current node; compilation fails if a match can’t be found.

    • If the node name resembles a dot-separated fully qualified domain name, Puppet makes multiple attempts to match a node definition, removing the right-most part of the name each time. Thus, Puppet would first try agent1.example.com, then agent1.example, then agent1. This behavior isn’t mimicked when calling an ENC, which is invoked only once with the agent’s full node name.

    • If no matching node definition can be found with the node’s name, Puppet tries one last time with a node name of default; most users include a node default {} statement in their site.pp file. This behavior isn’t mimicked when calling an ENC.