Concept and reference samples: Puppet language

20 Dec, 2025

Context

• Organization: Puppet (open source)
• Audience: Infrastructure engineers, SREs, sysadmins
• Scope: Language concepts, manifests, and annotated examples

These samples are from my work modernizing and reorganizing Puppet’s core language reference. The existing material had grown organically over time and assumed significant prior knowledge. In addition to rewriting and polishing, I separated mixed concept, reference, and task topics, improved navigability, and added explanatory text around real-world code examples. The result was documentation that helped both experienced practitioners and new users understand not just what to write, but why.

This version of Puppet open source documentation can be accessed in its entirety in the Puppet documentation archive.

Contents

• Manifests
• Manifest example
• Catalogs
• Resources and classes

Manifests

Resources are declared in manifests (.pp files). Manifests are stored in modules and may be custom-written or downloaded.

Manifests:

• Are UTF-8 encoded text files
• Use .pp extensions
• Can contain conditional logic
• Can declare resources for multiple agents

The primary server evaluates manifests and compiles catalogs for each node.

The main manifest (site.pp) is evaluated first and defines global configuration.

Manifest example

This short manifest manages NTP. It includes:

• A case statement that sets the name of the NTP service, depending on which operating system is installed on the agent.
• A package resource that installs the NTP package on the agent.
• A service resource that enables and runs the NTP service. This resource also applies the NTP configuration settings from ntp.conf to the service.
• A file resource that creates the ntp.conf file on the agent in /etc/ntp.conf. This resource also requires that the ntp package is installed on the agent. The contents of the ntp.conf file will be taken from the specified source file, which is contained in the ntp module.

case $operatingsystem {
  centos, redhat: { $service_name = 'ntpd' }
  debian, ubuntu: { $service_name = 'ntp' }
}

package { 'ntp':
  ensure => installed,
}

service { 'ntp':
  name      => $service_name,
  ensure    => running,
  enable    => true,
  subscribe => File['ntp.conf'],
}

file { 'ntp.conf':
  path    => '/etc/ntp.conf',
  ensure  => file,
  require => Package['ntp'],
  source  => "puppet:///modules/ntp/ntp.conf",
  # This source file would be located on the primary Puppet server at
  # /etc/puppetlabs/code/modules/ntp/files/ntp.conf
}

Catalogs

To configure nodes, the primary Puppet server compiles configuration information into a catalog, which describes the desired state of a specific agent node. Each agent requests and receives its own individual catalog.

The catalog describes the desired state for every resource managed on a single given node. Whereas a manifest can contain conditional logic to describe specific resource configuration for multiple nodes, a catalog is a static document that describes all of the resources and dependencies for only one node.

To create a catalog for a given agent, the primary server compiles:

• Data from the agent, such as facts or certificates.
• External data, such as values from functions or classification information from the PE console.
• Manifests, which can contain conditional logic to describe the desired state of resources for many nodes.

The primary server resolves all of these elements and compiles a specific catalog for each individual agent. After the agent receives its catalog, it applies any changes needed to bring the agent to the state described in the catalog.

Tip: When you run the puppet apply command on a node, it compiles the catalog locally and applies it immediately on the node where you ran the command.

Agents cache their most recent catalog. If they request a catalog and the primary server fails to compile one, they fall back to their cached catalog.

Resources and classes

A resource describes some aspect of a system, such as a specific service or package. You can group resources together in classes, which generally configure larger chunks of functionality, such as all of the packages, configuration files, and services needed to run an application.

The Puppet language is structured around resource declaration. When you declare a resource, you tell Puppet the desired state for that resource, so that Puppet can add it to the catalog and manage it. Every other part of the Puppet language exists to add flexibility and convenience to the way you declare resources.

Just as you declare a single resource, you can declare a class to manage many resources at once. Whereas a resource declaration might manage the state of a single file or package, a class declaration can manage everything needed to configure an entire service or application, including packages, configuration files, service daemons, and maintenance tasks. In turn, small classes that manage a few resources can be combined into larger classes that describe entire custom system roles, such as “database server” or “web application worker.”

To add a class’s resources to the catalog, either declare the class in a manifest or classify your nodes. Node classification allows you to assign a different set of classes to each node, based on the node’s role in your infrastructure. You can classify nodes with node definitions or by using node-specific data from outside your manifests, such as that from an external node classifier or Hiera.

Open source documentation licensed under Creative Commons. Reproduced here as a professional writing sample.