Puppet Language

Puppet's language describes the state a system should have. A manifest is source code; catalog compilation evaluates its variables, expressions, conditions, functions, and declarations for one node. The resulting catalog contains resources and relationships, not the control flow that produced them.

That distinction is the key to reading Puppet correctly. A manifest is not a shell script with unusual punctuation.

Think in two phases

During compilation, Puppet evaluates language constructs on the primary server, or locally when you use puppet apply. It uses code, facts, classification, and data to create a catalog.

During application, an agent evaluates the resources in that catalog against the target system. Resource providers inspect current state and make necessary changes.

manifest + facts + data
          |
          v
     compilation
          |
          v
resources + dependency relationships
          |
          v
      application

A function called in a manifest runs during compilation. It cannot directly manage an agent-side file. A file resource in the compiled catalog can.

Declare resources

A resource declaration has a type, a title, and attributes:

file { '/etc/example.conf':
  ensure  => file,
  owner   => 'root',
  group   => 'root',
  mode    => '0644',
  content => "enabled = true\n",
}

The type is file. The title is /etc/example.conf. Attributes describe desired state.

Titles must uniquely identify resources of the same type in a catalog. Declaring the same resource twice is an error, even if the declarations appear in different classes.

Use lower-case names for built-in resource declarations. Capitalized syntax refers to a resource:

File['/etc/example.conf']

References can appear before their declarations. They are commonly used in relationships.

Build a dependency graph

Puppet can apply unrelated resources in any order. Declare relationships when correctness requires order or refresh behavior.

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