Language: Resource collectors

Resource collectors (also known as the spaceship operator) select a group of resources by searching the attributes of every resource in the catalog. This search is independent of evaluation order — it includes resources that haven’t yet been declared at the time the collector is written. Collectors realize virtual resources, can be used in chaining statements, and can override resource attributes.

Collectors have an irregular syntax that lets them function as both a statement and a value.

Syntax

User <| title == 'luke' |>           # collect a single user resource whose title is 'luke'
User <| groups == 'admin' |>         # collect any user whose supplemental groups includes 'admin'
Yumrepo['custom_packages'] -> Package <| tag == 'custom' |>  # order relationship with several packages

The general form of a resource collector is:

  • The resource type, capitalized. (This cannot be Class.)
  • <| — An opening angle bracket and pipe character.
  • Optionally, a search expression (see below).
  • |> — A pipe character and closing angle bracket.

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

Search expressions

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

Note: Collectors can only search on attributes which are present in the manifests and cannot read the state of the target system. For example, Package <| provider == yum |> would only collect packages whose provider attribute had been explicitly set to yum in the manifests.

A collector with an empty search expression will match every resource of the specified resource type.

Parentheses can be used to improve readability and to modify the priority/grouping of and/or. You can create arbitrarily complex expressions using the following four operators:

== (equality search)

This operator is non-symmetric:

For a given resource, this operator will match 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:

For a given resource, this operator will match if the value of the attribute is not identical to the search key.

Note: This operator will always match if the attribute’s value is an array.

and

Both operands must be valid search expressions. This operator will match if both operands match. Has higher priority than or.

or

Both operands must be valid search expressions. This operator will match if either operand matches. Has lower priority than and.

Location

Resource collectors can be used as:

Collectors cannot be used as the value of a resource attribute, as the argument of a function, within an array or hash, or as the operand of an expression other than a chaining statement.

Behavior

A resource collector will always realize any virtual resources that match its search expression. An empty search expression matches every resource of the specified type.

Note that a collector also collects and realizes any exported resources from the current node. If you use exported resources that you don’t want realized, take care to exclude them from the collector’s search expression.

In addition to realizing, collectors can function as a value in two places:

  • When used in a chaining statement, a collector acts as a proxy for every resource (virtual or non) that matches its search expression.
  • When given a block of attributes and values, a collector will set and override those attributes for every resource (virtual or not) that matches its search expression.

Exported resource collectors

An exported resource collector uses a modified syntax that realizes exported resources.

Exported collector syntax

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, capitalized.
  • <<| — Two opening angle brackets and a pipe character.
  • Optionally, a search expression (see above).
  • |>> — A pipe character and two closing angle brackets.

Exported collector behavior

Exported resource collectors import resources that were published by other nodes. To use them, you need catalog storage and searching (storeconfigs) enabled via PuppetDB. See Exported Resources for more details.

Like normal collectors, exported resource collectors can be used with attribute blocks and chaining statements.

Note that 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.