Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 38 ยท Architecture and Setup

Puppet Architecture: Server, Agent, and Catalog

Learn how Puppet Server, agents, Facter, catalogs, reports and PuppetDB fit together, and what happens on the network during one agent run.

In the simplest setup one machine runs puppet apply. In production you have a Puppet Server and hundreds or thousands of agents. This lesson explains the pieces, who talks to whom, and why the design scales.

The main components

  • Puppet Server (a JVM application, port 8140): holds your code, compiles catalogs, acts as a certificate authority (CA), and serves files.
  • Puppet agent: runs on every node, asks the server for a catalog and enforces it.
  • Facter: runs on the agent to collect facts; the facts are sent to the server.
  • Hiera: the data lookup used by the compiler, on the server.
  • PuppetDB (optional): a database of facts, catalogs and reports; enables queries and exported resources.
  • Code repository: usually Git, deployed to the server's code directory (covered later in the course).
sequenceDiagram
    participant A as Agent (node)
    participant S as Puppet Server
    participant D as PuppetDB
    A->>A: Facter collects facts
    A->>S: Request catalog (sends facts, over HTTPS 8140)
    S->>S: Compile catalog (code + Hiera + facts)
    S-->>A: Catalog
    A->>A: Apply: compare and fix each resource
    A->>S: Send report
    S->>D: Store facts, catalog, report

One agent run. Only the server needs your code; agents receive finished catalogs.

Why compile on the server?

The agent never sees your manifests, only the catalog, a static list of resources with all variables resolved. That has several advantages:

  • Security. Secrets and logic stay on the server. Each node only gets its own data.
  • Consistency. The compile happens in one place, with one set of modules.
  • Light agents. The node needs no copy of your code base.
  • Auditability. The catalog is a complete record of what was requested.

The compiler decides per node using the node's facts (OS, IP, memory) and node classification (which classes this node gets, via site.pp node blocks, Hiera or an external node classifier).

Agent and server communication

Agent and server talk over HTTPS on port 8140, with mutual TLS: the agent presents a certificate signed by the server's CA, and the server proves its own identity. The certificates lesson shows how a new agent gets approved. The agent contacts the server; the server never connects into nodes. That means nodes behind NAT or firewalls only need outbound access to port 8140.

Agents run as a service (puppet) and check in every 30 minutes (runinterval), after a random start offset so a thousand agents do not hit the server at the same second. Besides the catalog, an agent also downloads plugins (custom facts and types from modules) at the start of a run: this is pluginsync.

Masterless: puppet apply

You can skip the server entirely. In a masterless setup, every node has a copy of the code (for example cloned from Git by cron) and runs puppet apply. Trade-offs:

Server and agent Masterless (puppet apply)
Setup CA, server, certificates Just the agent package and code
Secrets Held on the server Must be on every node
Reporting Central (PuppetDB, console) You must collect it yourself
Scale Server must be sized Scales with node count, no server load
Good for Most fleets Small sites, images, containers, bootstrapping

Sizing and high availability

A catalog compile uses CPU on the server; compile time grows with the amount of code and data. When one server is not enough, you add compilers (extra servers that only compile) behind a load balancer, with one primary server holding the CA. Later chapters discuss scaling further. As a rough idea: one modest server can serve a few hundred nodes at a 30-minute interval; compilers extend this to many thousands.

A stand-in: compile and apply

This stand-in (Python, not Puppet) models the split between server-side compilation and agent-side enforcement. Notice that the agent function never touches the "code".

Python Stand-in: server compiles, agent applies

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.

Python Stand-in: when do 1000 agents hit the server?

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 random offset spreads the load: the busiest minute stays close to the average rather than all 1000 agents arriving together.

Common architecture mistakes

  • Putting secrets into code in Git in plain text (use Hiera with encryption, see Hiera).
  • Making the server a single point of failure without backups of the CA directory.
  • Forgetting that the agent needs outbound access to port 8140 and DNS that resolves the server name.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which component compiles the catalog?

    The server compiles the catalog from code, Hiera data and the node's facts.
  2. 2. Which port do agents use to reach the Puppet Server?

    Agents connect over HTTPS on port 8140.
  3. 3. Why does the agent receive a catalog and not your manifests?

    Compiling on the server keeps logic and data private and gives a complete record.
  4. 4. What is PuppetDB used for?

    PuppetDB stores run data and supports queries and exported resources.

Summary

  • Server compiles; agent collects facts, applies the catalog and reports.
  • Communication is HTTPS on port 8140, initiated by the agent.
  • Agents check in every 30 minutes with a random offset.
  • Masterless puppet apply trades central control for simplicity.
  • PuppetDB is optional but powers queries and reporting.

Next: Installing Puppet Server and the Agent