The catalog: compile & apply

How a run actually works.

Intermediate12 min · lesson 4 of 12

The catalog is the heart of a Puppet run: a node-specific document listing every resource and its desired state, plus the dependency graph. On each run the agent sends its facts to the master; the master compiles the manifests (with those facts and Hiera data) into a catalog just for that node and sends it back; the agent then applies the catalog, converging each resource, and reports the results. Compile on the master, apply on the agent.

From manifests to enforced state

1facts

agent profiles the node

2compile

master builds the catalog

3apply

agent enforces each resource

4report

changes + failures back

The catalog is compiled per node from shared code + that node’s facts + Hiera data — one codebase, node-specific results.

terminal

$ puppet agent -t          # trigger a run now (test mode)
Info: Applying configuration version '1699...'
Notice: /Stage[main]/Nginx/File[/etc/nginx/nginx.conf]/content: content changed
Notice: /Stage[main]/Nginx/Service[nginx]: Triggered 'refresh'
Notice: Applied catalog in 4.21 seconds

noop: the dry run

Puppet’s equivalent of a plan is noop mode (--noop): it compiles and evaluates the catalog and reports exactly what it would change, without changing anything. Running puppet agent -t --noop is the safe preview before letting a change loose, and is invaluable when testing a manifest edit against a real node. As with other tools, run noop first, read the diff, then apply for real.

A compiled catalog reflects the master’s code and data

Because the catalog is compiled on the master from shared manifests, Hiera, and the node’s facts, a change to shared code changes every node that compiles against it on their next run — automatically, via the pull model. That is powerful and dangerous: test with --noop and in a non-prod environment before merging, since a bad manifest converges fleet-wide without a manual push.

Manifests & the DSLClasses & defined types