Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 38 ยท Roles and Profiles

Node Classification: site.pp and ENCs

Decide which classes each node gets: node definitions in site.pp, regex matching, the default node, external node classifiers, Hiera-driven classes and trusted facts.

Roles and profiles say what a machine can be; node classification decides what each machine actually is. When an agent asks for a catalog, the server must work out which classes to include for that node. There are several mechanisms, and each suits a different stage of growth: a node block in site.pp, a Hiera-driven class list, an external node classifier (ENC), or the classifier built into Puppet Enterprise.

This lesson compares them and shows the safest pattern: derive the role from something trustworthy and keep the classification in one place. The product cannot run here, so examples are read-only and the runnable blocks are JavaScript stand-ins for the matching logic.

Node blocks in site.pp

The main manifest of an environment, manifests/site.pp, is evaluated for every node. Inside it a node block matches a certname:

PUPPET
node 'web1.example.com' {
  include role::shop_frontend
}

node /^db\d+\.example\.com$/ {
  include role::reporting_db
}

node default {
  include role::minimal
}

Rules to know:

  • Node names match the certname, which is normally the fully qualified domain name.
  • A regular expression is anchored only if you anchor it. Write ^ and $.
  • The default node applies only when no other block matched.
  • Node inheritance (node a inherits b) was removed. Share code with roles, not inheritance.
  • Only the first matching block is used. Order matters when patterns overlap.

This is perfect for a small fleet. It becomes a burden when there are hundreds of nodes and every change is a code commit.

Classification through Hiera

A scalable alternative keeps site.pp tiny and reads the role from data:

PUPPET
# manifests/site.pp
$role = lookup('role', String, 'first', 'role::minimal')
include $role
YAML
# data/nodes/web1.example.com.yaml
role: role::shop_frontend

The class name stays a string, include accepts a variable, and Hiera's hierarchy provides the lookup. New machines are added by creating a data file, with no change to Puppet code. Caveat: a typo in a role name produces a compile error naming the missing class, which is a good failure.

A cousin of this is a custom or trusted fact: $trusted['extensions']['pp_role'] is a role value embedded in the node's certificate when it is created. Because the certificate is signed by the Puppet CA, a node cannot lie about it. That is better than a custom fact in facts.d, which the node itself can edit.

Never classify on an ordinary fact if the choice controls access to secrets. A node that sets role=database in a fact file could receive database credentials. Use certname, trusted extensions, or an ENC.

External node classifiers

An ENC is an executable that the Puppet server runs with the node's certname as its argument. It prints YAML that names the classes, parameters and environment for that node. You configure it in puppet.conf:

INI
[server]
node_terminus = exec
external_nodes = /usr/local/bin/my-enc

The output looks like this:

YAML
classes:
  role::shop_frontend:
parameters:
  datacenter: fra
environment: production

An ENC can read from a CMDB, a spreadsheet export, a Git repository or a web service. It lets other teams (who never touch Puppet code) decide where machines go, and it can set the environment, which site.pp cannot do. Keep it fast and reliable, because it runs on every compile. A failing ENC causes compile errors for the affected nodes.

Puppet Enterprise and Foreman provide their own web-based classifiers with the same idea.

flowchart LR
  A["Agent requests catalog"] --> S["Server"]
  S --> E["ENC / site.pp / Hiera"]
  E --> C["Classes + parameters + environment"]
  C --> S
  S --> K["Compiled catalog"]

Classification happens at compile time, on the server.

Choosing a mechanism

Approach Best for Weak point
node blocks in site.pp Small fleets, labs Every change is a code change
Hiera role key Medium fleets with Git workflow Needs good hierarchy naming
Trusted certificate extension Cloud autoscaling, secure role claims Set at certificate creation
ENC / PE classifier Large fleets, many teams Extra service to run

Stand-ins: matching nodes to roles

The first stand-in reproduces the node block semantics: first match wins, regexes need anchors, default last. The second shows classification from a data table.

JS Stand-in: first matching node block wins

Press Run (or Ctrl + Enter) to see the console output here.

No output.

mydb.example.com is caught by the unanchored /db/ block, a typical mistake. Anchor your patterns.

JS Stand-in: ENC-style output and validation

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a node block in site.pp match against?

    Node definitions match the certname, usually the FQDN.
  2. 2. Which source is safest for deciding who receives database credentials?

    Trusted data is signed by the CA, so the node cannot forge it, unlike ordinary facts.
  3. 3. What does an ENC print for a node?

    The ENC returns YAML that the server uses to classify the node.
  4. 4. Two node blocks both match a certname. Which is used?

    Puppet uses the first matching node definition.

Summary

  • Classification picks the classes (and environment) for each node at compile time.
  • site.pp node blocks are simple but code-bound; Hiera role keys scale to larger fleets.
  • Use certname or trusted extensions for security decisions, never ordinary facts.
  • An ENC prints YAML and lets external systems drive classification.
  • Anchor regexes and keep the default node minimal.

Next: Roles and Profiles Anti-patterns