Learn Puppet - Core Concepts & Main Architecture

#Introduction

In the previous episode 1, you understood the history of configuration management and why Puppet exists — from the era of manual scripting to the complete ecosystem it brought. Now it's time to dissect Puppet's main architecture: how a simple manifest can keep thousands of nodes converged. This is the most fundamental episode in the series, because almost every advanced topic — Hiera, PuppetDB, Roles/Profiles, and even Puppet Enterprise — is rooted in this architecture.

#How It Works Under the Hood

#The Agent Run Flow

Every node managed by Puppet runs an agent run periodically (default 30 minutes). One agent run cycle consists of six stages:

1. Facter gathers node facts — operating system, IP address, architecture, and other metadata are collected into facts.
2. SSL certificate authentication — the agent proves its identity to the server using an SSL certificate.
3. Catalog compilation on the server — the server reads manifests, node classification, and Hiera, then compiles a catalog specific to that node.
4. The catalog is sent to the agent — the catalog contains the list of resources to be applied.
5. The agent applies the catalog — the agent compares the actual state with the desired state and makes the required changes.
6. Reporting to the server/PuppetDB — the agent run results are sent back for reporting.

Node                 Server               PuppetDB
 |  1. node facts       |                     |
 |--------------------->|                     |
 |  2. SSL handshake    |                     |
 |--------------------->|                     |
 |  3. catalog compile  |                     |
 |   (manifest + data)  |                     |
 |                      |                     |
 |  4. catalog sent     |                     |
 |<---------------------|                     |
 |  5. agent applies    |                     |
 |  6. result report    |                     |
 |--------------------->|-------------------->|

#SSL Certificates: The Bridge of Trust

Before an agent first receives a catalog, it must introduce itself through a certificate. The authentication flow:

1. The agent creates a certificate signing request (CSR) with an identity based on its certname.
2. The server stores the pending CSR — for initial installation, the admin must sign it.
3. Once approved, the agent and server communicate over a verified TLS connection.

sudo puppetserver ca sign --certname agent.example.com

#Main Components

Puppet is a set of components that work together. Understand each role:

#Puppet Server

Puppet Server is the control center. It stores manifests, reads node classification, pulls data from Hiera, and compiles catalogs — one for each node, based on its facts and classification. It also acts as the Certificate Authority (CA) that manages all agents' certificates.

#Puppet Agent

The agent is the process running on every managed node. On a schedule (default 30 minutes), the agent fetches a catalog from the server, compares it with the actual state, then applies the changes. The agent also runs Facter to gather facts.

#PuppetDB

PuppetDB is the centralized data store. All facts and agent run reports are stored here, so you can answer questions like: which nodes still run an old OS, or how many nodes failed last night. PuppetDB also supports exporting data to other tools.

#Manifest

A manifest is a file containing Puppet configuration code. This is where you write resource types, classes, and node settings. Manifests use the .pp extension (Puppet Program).

#Resource Type

A resource type is an abstraction of a system element: package, service, file, user, group, cron, and more. Each resource has a title for identification and parameters that define its properties.

package { 'nginx':
  ensure => '1.18.0',
}

#Class

A class is a named collection of resources that can be reused. Classes let you write a configuration once and apply it to many nodes — this is the core idea behind modules.

#Module

A module is a structured package containing manifests, templates, files, and Hiera data. Modules can be downloaded from Puppet Forge or written by yourself. We'll dissect the internal module structure in episode 5.

#Node Classification

Node classification determines which classes are applied to which nodes. There are several mechanisms: the site.pp file on the server, Puppet Enterprise's built-in classifier, or Hiera data. The goal is one — mapping nodes to configurations.

#Hiera

Hiera is a hierarchical database that separates data from logic. Instead of writing configuration values inside manifests, you store them in Hiera and access them via lookup. This allows one class to serve thousands of nodes with different values per environment.

#Facter

Facter is the fact-gathering tool that runs on the agent. Facts like os.name, networking.ip, and memory serve as input for catalog compilation. With facts, a single manifest can produce different catalogs for different nodes.

#Conclusion

In this episode 2, you understood Puppet's architecture from top to bottom: the six-stage agent run flow that starts with Facter gathering facts, SSL certificate authentication, catalog compilation on the server, through to reporting to PuppetDB — plus the ten main components that work together as one unit.

Key takeaways:

• The Puppet agent run flow: facts → certificate → catalog → apply → report.
• A catalog is a compilation result unique to each node, based on facts and classification.
• SSL certificates are the bridge of trust between agent and server.
• Key components: Server, Agent, PuppetDB, manifests, resource types, classes, modules, node classification, Hiera, and Facter.

In the next episode, episode 3, we'll get hands-on — setting up and installing Puppet Server and agents from the official repos, configuring DNS and certificates with puppet ssl bootstrap, running your first puppet agent -t, and comparing Puppet OSS with Puppet Enterprise. Prepare your nodes, because now it's time to take action!