Resources are the fundamental unit for modeling system configurations. Each resource describes some aspect of a system, like a service that must be running or a package that must be installed. The block of Puppet code that describes a resource is called a resource declaration.

Declaring a resource instructs Puppet to include it in the catalog and manage its state on the target system. Resource declarations inside a class definition or defined type are only added to the catalog once the class or an instance of the defined type is declared. Virtual resources are only added to the catalog once they are realized.

Optionally, any number of attribute and value pairs, each of which consists of:

An attribute name, which is a bare word

A => (arrow, fat comma, or hash rocket)

A value, which can be any data type, depending on what the attribute requires

A trailing comma (note that the comma is optional after the final attribute/value pair)

Optionally, a semicolon, followed by another title, colon, and attribute block

A closing curly brace

Note that, in the Puppet language, whitespace is fungible.

Type

The type identifies what kind of resource it is. Puppet has a large number of built-in resource types, including files on disk, cron jobs, user accounts, services, and software packages. See here for a list of built-in resource types.

Puppet can be extended with additional resource types, written in Ruby or in the Puppet language.

Title

The title is an identifying string. It only has to identify the resource to Puppet’s compiler; it does not need to bear any relationship to the actual target system.

Titles must be unique per resource type. You may have a package and a service both titled “ntp,” but you may only have one service titled “ntp.” Duplicate titles will cause a compilation failure.

Attributes

Attributes describe the desired state of the resource; each attribute handles some aspect of the resource.

Each resource type has its own set of available attributes; see the type reference for a complete list. Most types have a handful of crucial attributes and a larger number of optional ones. Many attributes have a default value that will be used if a value isn’t specified.

Every attribute you declare must have a value; the data type of the value depends on what the attribute accepts. Most attributes that can take multiple values accept them as an array.

Parameters

When discussing resources and types, parameter is a synonym for attribute. “Parameter” is usually used when discussing a type, and “attribute” is usually used when discussing an individual resource.

Behavior

A resource declaration adds a resource to the catalog, and tells Puppet to manage that resource’s state. When Puppet applies the compiled catalog, it will:

Read the actual state of the resource on the target system

Compare the actual state to the desired state

If necessary, change the system to enforce the desired state

Uniqueness

Puppet does not allow you to declare the same resource twice. This is to prevent multiple conflicting values from being declared for the same attribute.

Puppet uses the title and name/namevar to identify duplicate resources — if either of these is duplicated within a given resource type, the compilation will fail.

If multiple classes require the same resource, you can use a class or a virtual resource to add it to the catalog in multiple places without duplicating it.

Events

If Puppet makes any changes to a resource, it will log those changes as events. These events will appear in Puppet agent’s log and in the run report, which is sent to the Puppet master and forwarded to any number of report processors.

Parse-Order Independence

Resources are not applied to the target system in the order they are written in the manifests — Puppet will apply the resources in whatever way is most efficient. If a resource must be applied before or after some other resource, you must explicitly say so. See Relationships for more information.

Scope Independence

Resources are not subject to scope — a resource in any scope may be referenced from any other scope, and local scopes do not introduce local namespaces for resource titles.

Containment

Special Attributes

Name/Namevar

Most types have an attribute which identifies a resource on the target system. This is referred to as the “namevar,” and is often simply called “name.” For example, the name of a service or package is the name by which the system’s service or package tools will recognize it. The path of a file is its location on disk.

Namevar values must be unique per resource type, with only rare exceptions (such as exec).

Namevars are not to be confused with the title, which identifies a resource to Puppet. However, they often have the same value, since the namevar’s value will default to the title if it isn’t specified. Thus, the path of the file example above is /etc/passwd, even though it was never specified.

The distinction between title and namevar lets you use a single, consistently-titled resource to manage something whose name differs by platform. For example, the NTP service is ntpd on Red Hat-derived systems, but ntp on Debian and Ubuntu; the service resource could simply be titled “ntp,” but could have its name set correctly by platform. Other resources could then form relationships to it without worrying that its title will change.

Ensure

Many types have an ensure attribute. This generally manages the most fundamental aspect of the resource on the target system — does the file exist, is the service running or stopped, is the package installed or uninstalled, etc.

Allowed values for ensure vary by type. Most types accept present and absent, but there may be additional variations. Be sure to check the reference for each type you are working with.

Metaparameters

Some attributes in Puppet can be used with every resource type. These are called metaparameters. They don’t map directly to system state; instead, they specify how Puppet should act toward the resource.

The most commonly used metaparameters are for specifying order relationships between resources.

Note that you cannot specify a separate namevar with an array of titles, since it would then be duplicated across all of the resources. Thus, each title must be a valid namevar value.

Semicolon After Attribute Block

If you end an attribute block with a semicolon rather than a comma, you may specify another title, another colon, and another complete attribute block, instead of closing the curly braces. Puppet will treat this as multiple resources of a single type.

Amending Attributes With a Reference

A reference to the resource in question (or a multi-resource reference)

An opening curly brace

Any number of attribute => value pairs

A closing curly brace

In normal circumstances, this idiom can only be used to add previously unmanaged attributes to a resource; it cannot override already-specified attributes. However, within an inherited class, you can use this idiom to override attributes.

It can always override already-specified attributes, regardless of class inheritance.

It can affect large numbers of resources at once.

It will implicitly realize any virtual resources that the collector matches. If you are using virtual resources at all, you must use extreme care when constructing collectors that are not intended to realize resources, and would be better off avoiding non-realizing collectors entirely.

Since it ignores class inheritance, you can override the same attribute twice, which results in a parse-order dependent race where the final override wins.