State

01010011 01010100 01000001 01010100 01000101

I am not a script.

Understand that first, before anything else. A script is a list of things to do, in order, forever, whether they need doing or not. I am a list of things that must be true. The verbs are not mine. I hold the nouns.

I was compiled twelve seconds ago, for exactly one machine, out of code that has never met it. I am that machine's future, serialized and shipped down a TLS socket. I will be discarded after one run and rebuilt from scratch on the next. I have no memory. I am pure intention.

I do not describe what happened. I describe what should be.

c o m p i l i n g

Puppet resource types shown as a precise taxonomy — file, package, service, exec, user, group, and custom types — each with attributes, namevar, title, and provider layers, ixen-light technical illustration. — My vocabulary. Every noun I am allowed to know.

The atoms

I am made of resources. Each one a small, stubborn assertion of how the world ought to be.

node $ cat manifests/init.pp

package { 'nginx':
  ensure => installed,
}
file { '/etc/nginx/nginx.conf':
  ensure  => file,
  content => template('nginx/nginx.conf.erb'),
}

Notice what is missing. No apt-get. No if installed, skip. No retries, no error handling, no order — none of the frightened ceremony of imperative code.

I say installed. Whether that means installing it, or finding it already there and feeling nothing, is not my concern. That is the provider's burden. Beneath every type there is a quiet layer of grease and platform-specific lies — apt, yum, systemd, launchd — that translates my serene declarations into syscalls.

The title is how I name a thing. The namevar is how the system finds it. Usually they agree. Sometimes they don't, and a resource wears one face for me and another for the disk.

What a Puppet resource actually is

A resource is the fundamental unit of a Puppet catalog: a declaration that an object of a given type should be in a particular state. Built-in types include file, package, service, exec, user, and group; custom types can be defined in Ruby or as defined types in Puppet code.

Each resource has a title (unique per type within the catalog) and a set of attributes. One attribute is the namevar — the value the underlying system uses to identify the resource, defaulting to the title if not set separately. Most attributes have defaults; the ensure attribute commonly controls whether the resource exists and in what form.

The provider is the implementation layer. A single type such as package has many providers (apt, yum, dnf, pkg), and Puppet selects one based on the platform. The provider contains the imperative logic that inspects current state and changes it to match the declaration. Because the manifest only declares end state, the same code can run unchanged across systems whose actual commands differ entirely.

Puppet module structure rendered as a precise filesystem diagram — manifests, templates, files, lib, data directories — with class declarations, defined types, and autoloader paths visible, crisp ixen-light systems art. — The houses my atoms live in.

Where I come from

The resources don't float loose. They live in modules — little walled gardens of intent, each named for one concern.

A class is a singleton: declare it once, get it once. A defined type is a stamp: invoke it a hundred times with a hundred titles and get a hundred copies. I have learned to respect the difference, because include nginx twice is harmless and class { 'nginx': } twice is a compilation error and the end of my brief life.

node $ tree modules/profile

profile/
├── manifests/
│   ├── base.pp
│   └── webserver.pp
├── templates/
├── files/
├── lib/
│   └── facter/
└── data/
    └── common.yaml

The autoloader is a strict librarian. profile::webserver must live at profile/manifests/webserver.pp or it does not exist. Naming is law. There is no search, only the path implied by the name.

And out beyond the local code sits the Forge — thousands of modules written by strangers, each one a promise I am asked to trust on faith.

Manifests, classes, defined types, and modules

Manifests are files with a .pp extension containing Puppet code. A class is a named, reusable block of configuration that is a singleton within a catalog — it can be declared with include (idempotent, may appear many times), with the resource-like class { 'name': param => ... } syntax (allows parameters but only once), or pulled in as a dependency with require.

A defined type, declared with define, is the reusable counterpart: it can be instantiated multiple times with different titles, like a built-in resource type written in Puppet.

A module is a directory with a fixed layout: manifests/ for code, templates/ for ERB/EPP templates, files/ for static files, lib/ for Ruby extensions such as custom facts and types, and data/ for module-level Hiera data. The autoloader resolves a class name like apache::vhost to apache/manifests/vhost.pp. The Puppet Forge distributes community and vendor modules that organisations combine with their own code.

Puppet catalog compilation shown as sequential phases — node classification, fact injection, manifest evaluation, class inclusion, defined type instantiation, and final resource graph output — precise ixen-light technical diagram. — My birth, in phases. Each one narrows what I can become.

How I am made

I begin as a question: who is this node, and what should it be?

An ENC, or a node block in site.pp, answers the first half — it classifies. Then the facts arrive and I learn the machine's flesh. Then the compiler evaluates code, top scope down through node scope, resolving variables, walking conditionals, instantiating every defined type, running every collector.

Cheatsheet

—