Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 38 ยท Architecture and Setup

The Agent Run Lifecycle

Follow one Puppet agent run from pluginsync and facts to catalog compile, apply and report. Learn runinterval, splay, noop mode, cached catalogs and common run failures.

A Puppet run is the unit of work: one pass from "agent wakes up" to "report is stored". Almost every operational question ("why did this not change?", "why is it slow?", "how do I test safely?") is answered by understanding the stages. This lesson walks through them and shows the knobs you can turn.

The stages

flowchart TB
    S1["1. Pluginsync<br/>download custom facts, types, functions"] --> S2["2. Facter<br/>collect facts"]
    S2 --> S3["3. Request catalog<br/>facts sent to server"]
    S3 --> S4["4. Server compiles<br/>(code + Hiera + facts)"]
    S4 --> S5["5. Agent applies catalog<br/>resource by resource"]
    S5 --> S6["6. Report sent to server"]
  1. Pluginsync. The agent downloads the lib parts of every module (custom facts, resource types, providers, functions) from the server so it can understand the catalog.
  2. Facts. Facter runs, including custom facts from modules.
  3. Catalog request. The agent sends its facts and receives a compiled catalog (or uses a cached catalog if the server is unreachable and usecacheonfailure is true, which is the default).
  4. Compile on the server, discussed in Architecture.
  5. Apply. The agent evaluates resources in dependency order. For each: read current state, compare, change if needed, and trigger refreshes (for example, restart a service after its config file changed).
  6. Report. A record of every event (changed, unchanged, failed, skipped) is sent to the server, which stores it and can forward it to PuppetDB or a monitoring system.

Timing: runinterval, splay and one-off runs

In puppet.conf (section [agent]):

INI
[agent]
runinterval = 30m
splay = true
splaylimit = 30m
  • runinterval is how often the agent runs as a service (default 30 minutes).
  • splay adds a random delay so agents do not all call at once; splaylimit caps it.
  • To run now, use sudo puppet agent -t (or --test), which is a one-off, verbose run with detailed exit codes. If the agent service is already mid-run you may get a lock message; wait for it to finish, because overlapping runs are not allowed.

Typical day-to-day commands:

Terminal
sudo puppet agent -t                    # run now
sudo puppet agent -t --noop             # dry run: show what would change
sudo puppet agent -t --environment=staging   # try another environment (once)
sudo puppet agent --disable "deploying hotfix"   # pause scheduled runs
sudo puppet agent --enable

--disable is a polite lock: scheduled runs refuse to start and report the message you gave. Use it while you debug a node by hand, and remember to enable again, or the node silently stops converging.

noop mode

noop ("no operation") tells the agent to compare but not change. Everything is evaluated and logged, with lines saying what would have been done. You can set it for one run (--noop), permanently in puppet.conf (noop = true), or on a single resource (noop => true metaparameter) to trial a risky change on a few resources while everything else runs for real. Noop is the standard way to preview a change on a node before it goes live. Treat a clean noop run as a good sign, not a guarantee: resources that depend on other changes may behave differently when the earlier change actually happens.

Failure behaviour

  • If a resource fails, Puppet skips every resource that depends on it ("Skipping because of failed dependencies") but still applies unrelated ones. The run exits with a failure code.
  • If the server is unreachable, the agent can fall back on its cached catalog, so the node keeps its last known configuration.
  • If the catalog fails to compile (a syntax error, a missing Hiera value), the agent gets an error and applies nothing new. Bad code can therefore not half-apply, which is one reason compiling on the server is attractive.
Python Stand-in: dependency-aware apply

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The unrelated File[/etc/motd] still applies, while everything below the failed package is skipped.

Python Stand-in: cached catalog fallback

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Reading a run's output

Typical lines from puppet agent -t look like this (details vary):

TEXT
Info: Using environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Loading facts
Info: Caching catalog for web1.example.test
Info: Applying configuration version '1718000000'
Notice: /Stage[main]/Nginx/File[/etc/nginx/nginx.conf]/content: content changed '{sha256}...' to '{sha256}...'
Info: /Stage[main]/Nginx/File[/etc/nginx/nginx.conf]: Scheduling refresh of Service[nginx]
Notice: /Stage[main]/Nginx/Service[nginx]: Triggered 'refresh' from 1 event
Notice: Applied catalog in 1.42 seconds

Read the path as Stage[main] / Class / Resource / attribute: it tells you exactly which class and resource acted. A Scheduling refresh line followed by Triggered 'refresh' is a restart caused by a changed config file (Relationships and Ordering).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the default interval between scheduled agent runs?

    runinterval defaults to 30 minutes.
  2. 2. What does splay do?

    Splay randomises start times so agents do not all connect together.
  3. 3. A resource fails. What happens to resources that depend on it?

    Dependents are skipped; unrelated resources still apply.
  4. 4. Which command pauses scheduled runs with a reason?

    --disable locks the agent; --enable unlocks it.

Summary

  • A run: pluginsync, facts, catalog request, compile, apply, report.
  • runinterval (30 min) and splay control timing; puppet agent -t runs now.
  • --noop previews changes; --disable/--enable pause and resume.
  • Failed resources skip their dependents; unreachable server means the cached catalog is used.
  • Read log paths as Stage/Class/Resource/attribute.

Next: Environments and puppet.conf