English for Puppet Configuration Management

Puppet predates most modern infrastructure-as-code tools, and many teams still run it to manage long-lived servers, which means new hires often need to learn its specific vocabulary from scratch. Being precise about manifests, resources, and catalog runs in English helps you describe exactly what changed on a server instead of vaguely saying “Puppet did something.”

Key Vocabulary

Manifest — a Puppet file, written in its declarative language, that describes the desired state of resources on a node, such as which packages should be installed or which services should be running. “I added the new package to the manifest, but it won’t take effect on the servers until the next scheduled Puppet run.”

Resource — the basic unit Puppet manages, representing a single piece of system state like a file, package, service, or user, each declared with a type and a desired state. “This manifest declares the nginx service as a resource that should always be running and enabled at boot, so Puppet will restart it if it ever stops.”

Catalog — the compiled, node-specific set of resources and their desired states that Puppet generates from manifests and applies during a run. “The catalog compilation failed because of a syntax error in a shared module, so this node never even attempted to apply its configuration.”

Idempotent — describing an operation that produces the same end state no matter how many times it’s applied, which is the core guarantee Puppet resources are designed around. “Puppet resources are idempotent by design — running the same manifest ten times in a row should leave the server in exactly the same state as running it once.”

Puppet run (catalog run) — the periodic process where an agent node fetches its compiled catalog from the Puppet server and applies any resources that are out of sync with the desired state. “That config drift will get corrected automatically on the next Puppet run, usually within thirty minutes, unless someone forces it manually.”

Common Phrases

• “Has this manifest change actually reached the server yet, or is it waiting for the next run?”
• “Which resource is failing to converge — is it the package, the service, or a file?”
• “Did the catalog even compile for that node, or did it fail before applying anything?”
• “Is this operation idempotent, or could a repeated run cause a problem?”
• “Let’s force a Puppet run instead of waiting for the scheduled interval.”

Example Sentences

Debugging config drift: “That server was manually edited outside of Puppet, so the next catalog run will revert the change back to what the manifest declares — that’s expected, not a bug.”

Explaining a rollout delay: “The manifest change is merged, but it won’t apply until the next Puppet run on each node, so expect it to roll out gradually over the next thirty minutes.”

Reviewing a new manifest: “Make sure this resource declaration is idempotent — if it just appends to a file every run instead of ensuring a specific state, we’ll get duplicate entries over time.”

Professional Tips

• Use manifest specifically for the source file and catalog for the compiled, per-node result — conflating the two makes it hard to tell whether a problem is in the code or in how it applied to a specific server.
• Confirm whether a change has actually been through a Puppet run before assuming a fix failed — most “it’s still broken” reports are really “it hasn’t converged yet.”
• Point out when a proposed resource declaration isn’t idempotent during review — non-idempotent resources are the most common source of Puppet-managed servers slowly drifting out of a predictable state.
• Say “force a run” rather than “restart Puppet” when you want an immediate catalog application — it’s the precise action and avoids confusion with restarting the Puppet service itself.

Practice Exercise

1. Explain, in one sentence, the difference between a manifest and a catalog.
2. Describe why idempotency matters for a resource that appends a line to a configuration file.
3. Write two sentences explaining to a teammate why a manual change they made on a server was reverted automatically.