Resource collectors

Resource collectors select a group of resources by searching the attributes of each resource in the catalog, even resources which haven’t yet been declared at the time the collector is written. Collectors realize virtual resources, are used in chaining statements, and override resource attributes. Collectors have an irregular syntax that enables them to function as a statement and a value.

Syntax

User <| title == 'luke' |> # Collect a single user resource whose title is 'luke'
User <| groups == 'admin' |> # Collect any user resource whose list of supplemental groups includes 'admin'
Yumrepo['custom_packages'] -> Package <| tag == 'custom' |> # Creates an order relationship with several package resources
The general form of a resource collector is:

  • A capitalized resource type name. This cannot be Class, and there is no way to collect classes.

  • <|- An opening angle bracket (less-than sign) and pipe character.

  • Optionally, a search expression.

  • |> - A pipe character and closing angle bracket (greater-than sign)

Note: Exported resource collectors have a slightly different syntax; see below.

Using a special expression syntax, collectors search the values of resource titles and attributes. This resembles the normal syntax for Puppet expressions, but is not the same.

Note: Collectors can search only on attributes that are present in the manifests, and cannot read the state of the target system. For example, the collector Package <| provider == yum |> collects only packages whose provider attribute is explicitly set to yum in the manifests. It does not match packages that would default to the yum provider based on the state of the target system.
A collector with an empty search expression matches every resource of the specified resource type.
Use parentheses to improve readability, and to modify the priority and grouping of and and or operators. You can create complex expressions using four operators.
== (equality search)
This operator is non-symmetric:

  • The left operand (attribute) is a string, and must be the name of a resource attribute or the word title (which searches on the resource’s title). If the resource attribute name is a reserved word (for example, site, unit, or application), it must be in quotes.

  • The right operand (search key) must be a string, boolean, number, resource reference, or undef. The behavior of arrays and hashes in the right operand is undefined in this version of Puppet.

For a given resource, this operator matches if the value of the attribute (or one of the value’s members, if the value is an array) is identical to the search key.
!= (non-equality search)
This operator is non-symmetric:

  • The left operand (attribute) is a string, and must be the name of a resource attribute or the word title (which searches on the resource’s title). If the resource attribute name is a reserved word (for example, site, unit, or application), it must be in quotes.

  • The right operand (search key) must be a string, boolean, number, resource reference, or undef. The behavior of arrays and hashes in the right operand is undefined in this version of Puppet.

For a given resource, this operator matches if the value of the attribute is not identical to the search key.
Note: This operator always matches if the attribute’s value is an array.
and
Both operands must be valid search expressions. For a given resource, this operator matches if both of the operands match for that resource. This operator has higher priority than or.
or
Both operands must be valid search expressions. For a given resource, this operator matches if either of the operands match for that resource. This operator has lower priority than and.

Location

Use resource collectors in a collector attribute block for amending resource attributes, or as the operand of a chaining statement, or as independent statements.

Collectors cannot be used in the following contexts:

  • As the value of a resource attribute

  • As the argument of a function

  • Within an array or hash

  • As the operand of an expression other than a chaining statement

Tip: Resource collector expressions does not produce a directly assignable value. However, the query_resources function of the puppetdb_query module returns an array of resources. For more information, see PuppetDB query tools.

Behavior

A resource collector realizes any virtual resources matching its search expression. Empty search expressions match every resource of the specified resource type.

Note: A collector also collects and realizes any exported resources from the current node. When you use exported resources that you don’t want realized, exclude them from the collector’s search expression.
Collectors function as a value in two places:

  • In a chaining statement, a collector acts as a proxy for every resource (virtual or not) that matches its search expression.

  • When given a block of attributes and values, a collector sets and overrides those attributes for every resource (virtual or not) matching its search expression.

Note: Collectors used as values also realize any matching virtual resources. When you use virtualized resources, be careful when chaining collectors or using them for overrides.

Exported resource collectors

An exported resource collector uses a modified syntax that realizes exported resources and imports resources published by other nodes.

To use exported resource collectors, enable catalog storage and searching (storeconfigs). See Exported resources for more details. To enable exported resources, follow the installation instructions and Puppet configuration instructions in the PuppetDB docs.

Like normal collectors, use exported resource collectors with attribute blocks and chaining statements.

Note: The search for exported resources also searches the catalog being compiled, to avoid having to perform an additional run before finding them in the store of exported resources.
Exported resource collectors are identical to collectors, except that their angle brackets are doubled.
Nagios_service <<| |>> # realize all exported nagios_service resources
The general form of an exported resource collector is:

  • The resource type name, capitalized.

  • <<| — Two opening angle brackets (less-than signs) and a pipe character.

  • Optionally, a search expression.

  • |>> — A pipe character and two closing angle brackets (greater-than signs).