You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page is no longer maintained in Github. Contributions from the Puppet community are still very welcome.
20
+
Resource collectors (also known as the spaceship operator) select a group of resources by searching the
21
+
attributes of every resource in the [catalog][]. This search is independent of evaluation order — it
22
+
includes resources that haven't yet been declared at the time the collector is written. Collectors realize
23
+
[virtual resources][virtual], can be used in [chaining statements][chaining], and can override resource
24
+
attributes.
8
25
9
-
- Open a Jira ticket in the DOCUMENT project here: https://tickets.puppetlabs.com/projects/DOCUMENT/ Let us know the URL of the page, and describe the changes you think it needs.
26
+
Collectors have an irregular syntax that lets them function as both a statement and a value.
10
27
11
-
- Email docs@puppet.com if you have questions about contributing to the documentation.
28
+
## Syntax
12
29
30
+
```puppet
31
+
User <| title == 'luke' |> # collect a single user resource whose title is 'luke'
32
+
User <| groups == 'admin' |> # collect any user whose supplemental groups includes 'admin'
33
+
Yumrepo['custom_packages'] -> Package <| tag == 'custom' |> # order relationship with several packages
34
+
```
35
+
36
+
The general form of a resource collector is:
37
+
38
+
* The resource type, capitalized. (This cannot be `Class`.)
39
+
*`<|` — An opening angle bracket and pipe character.
40
+
* Optionally, a search expression (see below).
41
+
*`|>` — A pipe character and closing angle bracket.
42
+
43
+
Exported resource collectors have a slightly different syntax; [see below](#exported-resource-collectors).
44
+
45
+
### Search expressions
46
+
47
+
Collectors can search the values of resource titles and attributes using a special expression syntax. This
48
+
resembles the normal syntax for [Puppet expressions][expressions], but is not the same.
49
+
50
+
> **Note:** Collectors can only search on attributes which are present in the manifests and cannot read
51
+
> the state of the target system. For example, `Package <| provider == yum |>` would only collect
52
+
> packages whose `provider` attribute had been _explicitly set_ to `yum` in the manifests.
53
+
54
+
A collector with an empty search expression will match **every** resource of the specified resource type.
55
+
56
+
Parentheses can be used to improve readability and to modify the priority/grouping of `and`/`or`. You can
57
+
create arbitrarily complex expressions using the following four operators:
58
+
59
+
#### `==` (equality search)
60
+
61
+
This operator is non-symmetric:
62
+
63
+
* The left operand (attribute) must be the name of a [resource attribute][attribute] or the word `title`.
64
+
* The right operand (search key) must be a [string][], [boolean][], [number][], [resource
65
+
reference][reference], or [undef][].
66
+
67
+
For a given resource, this operator will **match** if the value of the attribute (or one of the value's
68
+
members, if the value is an array) is identical to the search key.
69
+
70
+
#### `!=` (non-equality search)
71
+
72
+
This operator is non-symmetric:
73
+
74
+
* The left operand (attribute) must be the name of a [resource attribute][attribute] or the word `title`.
75
+
* The right operand (search key) must be a [string][], [boolean][], [number][], [resource
76
+
reference][reference], or [undef][].
77
+
78
+
For a given resource, this operator will **match** if the value of the attribute is **not** identical to
79
+
the search key.
80
+
81
+
> **Note:** This operator will always match if the attribute's value is an array.
82
+
83
+
#### `and`
84
+
85
+
Both operands must be valid search expressions. This operator will **match** if **both** operands match.
86
+
Has higher priority than `or`.
87
+
88
+
#### `or`
89
+
90
+
Both operands must be valid search expressions. This operator will **match** if **either** operand matches.
91
+
Has lower priority than `and`.
92
+
93
+
## Location
94
+
95
+
Resource collectors can be used as:
96
+
97
+
* Independent statements
98
+
* The operand of a [chaining statement][chaining]
99
+
* In a [collector attribute block][amend] for amending resource attributes
100
+
101
+
Collectors **cannot** be used as the value of a resource attribute, as the argument of a function, within
102
+
an array or hash, or as the operand of an expression other than a chaining statement.
103
+
104
+
## Behavior
105
+
106
+
A resource collector will **always**[realize][] any [virtual resources][virtual] that match its search
107
+
expression. An empty search expression matches every resource of the specified type.
108
+
109
+
Note that a collector also collects and realizes any exported resources from the current node. If you use
110
+
exported resources that you don't want realized, take care to exclude them from the collector's search
111
+
expression.
112
+
113
+
In addition to realizing, collectors can function as a value in two places:
114
+
115
+
* When used in a [chaining statement][chaining], a collector acts as a proxy for every resource (virtual
116
+
or non) that matches its search expression.
117
+
* When given a block of attributes and values, a collector will [set and override][amend] those attributes
118
+
for every resource (virtual or not) that matches its search expression.
119
+
120
+
## Exported resource collectors
121
+
122
+
An **exported resource collector** uses a modified syntax that realizes [exported resources][exported].
123
+
124
+
### Exported collector syntax
125
+
126
+
Exported resource collectors are identical to collectors, except that their angle brackets are doubled:
127
+
128
+
```puppet
129
+
Nagios_service <<| |>> # realize all exported nagios_service resources
130
+
```
131
+
132
+
The general form of an exported resource collector is:
133
+
134
+
* The resource type, capitalized.
135
+
*`<<|` — Two opening angle brackets and a pipe character.
136
+
* Optionally, a search expression (see above).
137
+
*`|>>` — A pipe character and two closing angle brackets.
138
+
139
+
### Exported collector behavior
140
+
141
+
Exported resource collectors import resources that were published by other nodes. To use them, you need
142
+
catalog storage and searching (storeconfigs) enabled via PuppetDB. See [Exported Resources][exported] for
143
+
more details.
144
+
145
+
Like normal collectors, exported resource collectors can be used with attribute blocks and chaining
146
+
statements.
147
+
148
+
Note that the search for exported resources also searches the catalog being compiled, to avoid having to
149
+
perform an additional run before finding them in the store of exported resources.
This page is no longer maintained in Github. Contributions from the Puppet community are still very welcome.
12
+
Run stages are an additional way to order resources. They allow groups of classes to run before or after
13
+
nearly everything else, without having to explicitly create relationships with every other class.
8
14
9
-
- Open a Jira ticket in the DOCUMENT project here: https://tickets.puppetlabs.com/projects/DOCUMENT/ Let us know the URL of the page, and describe the changes you think it needs.
15
+
Run stages have [several major limitations](#limitations-and-known-issues); you should understand these
16
+
before attempting to use them.
10
17
11
-
- Email docs@puppet.com if you have questions about contributing to the documentation.
18
+
The run stage feature has two parts:
12
19
20
+
* A `stage` resource type.
21
+
* A `stage`[metaparameter][], which assigns a class to a named run stage.
22
+
23
+
## The default `main` stage
24
+
25
+
By default there is only one stage (named `main`). All resources are automatically associated with this
26
+
stage unless explicitly assigned to a different one. If you do not use run stages, every resource is in
27
+
the main stage.
28
+
29
+
## Custom stages
30
+
31
+
Additional stages are declared as normal resources. Each additional stage must have an
32
+
[order relationship][ordering] with another stage, such as `Stage['main']`. As with normal resources,
33
+
these relationships can be specified with metaparameters or with chaining arrows.
34
+
35
+
```puppet
36
+
stage { 'first':
37
+
before => Stage['main'],
38
+
}
39
+
stage { 'last': }
40
+
Stage['main'] -> Stage['last']
41
+
```
42
+
43
+
In the above example, all classes assigned to the `first` stage will be applied before classes in the
44
+
`main` stage, and both will be applied before the `last` stage.
45
+
46
+
## Assigning classes to stages
47
+
48
+
Once stages have been declared, a [class][] can be assigned to a custom stage with the `stage`
49
+
metaparameter.
50
+
51
+
```puppet
52
+
class { 'apt-keys':
53
+
stage => first,
54
+
}
55
+
```
56
+
57
+
The above example ensures the `apt-keys` class happens before all other classes, which is useful if most
58
+
of your package resources rely on those keys.
59
+
60
+
## Limitations and known issues
61
+
62
+
* To assign a class to a stage, you **must** use the [resource-like][resourcelike] class declaration
63
+
syntax and supply the stage explicitly. You **cannot** assign classes to stages with the `include`
64
+
function or by relying on automatic parameter lookup from Hiera with resource-like declarations.
65
+
* You cannot subscribe to or notify resources across a stage boundary.
66
+
* Classes that [contain][containment] other classes (with either the `contain` function or the anchor
67
+
pattern) can sometimes behave badly if declared with a run stage. If the contained class is only
68
+
declared by its container it will work fine, but if it is also declared anywhere outside its container
69
+
it will often create a dependency cycle that prevents the involved classes from being applied.
70
+
71
+
Due to these limitations, **stages should only be used with the simplest of classes,** and only when
72
+
absolutely necessary. Mass dependencies like package repositories are effectively the only valid use case.
[Resources][], [classes][], and [defined type instances][defined] can have any number of **tags** associated
25
+
with them, plus they receive some tags automatically. Tags are useful for:
7
26
8
-
This page is no longer maintained in Github. Contributions from the Puppet community are still very welcome.
27
+
*[Collecting][collectors] resources
28
+
* Analyzing [reports][]
29
+
* Restricting catalog runs
9
30
10
-
- Open a Jira ticket in the DOCUMENT project here: https://tickets.puppetlabs.com/projects/DOCUMENT/ Let us know the URL of the page, and describe the changes you think it needs.
31
+
## Tag names
11
32
12
-
- Email docs@puppet.com if you have questions about contributing to the documentation.
33
+
[See the reserved words page for the characters allowed in tag names.][tagnames]
13
34
35
+
## Assigning tags to resources
36
+
37
+
A resource can have any number of tags. There are several ways to assign a tag to a resource.
38
+
39
+
### Automatic tagging
40
+
41
+
Every resource automatically receives the following tags:
42
+
43
+
* Its resource type
44
+
* The full name of the [class][classes] and/or [defined type][defined] in which the resource was declared
45
+
* Every [namespace segment][namespace] of the resource's class and/or defined type
46
+
47
+
For example, a file resource in class `apache::ssl` would get the tags `file`, `apache::ssl`, `apache`,
48
+
and `ssl`.
49
+
50
+
### Containment
51
+
52
+
Like [relationships][] and most metaparameters, tags are passed along by [containment][]. This means a
53
+
resource will receive all of the tags from the class and/or defined type that contains it. In the case of
54
+
nested containment (e.g. a class that declares a defined resource, or a defined type that declares other
55
+
defined resources), a resource will receive tags from all of its containers.
56
+
57
+
### The `tag` metaparameter
58
+
59
+
You can use [the `tag` metaparameter][tagmeta] in a resource declaration to add any number of tags:
60
+
61
+
```puppet
62
+
apache::vhost {'docs.example.com':
63
+
port => 80,
64
+
tag => ['us_mirror1', 'us_mirror2'],
65
+
}
66
+
```
67
+
68
+
The `tag` metaparameter can accept a single tag or an array. These will be added to the tags the resource
69
+
already has. Since [containment][] applies to tags, the example above would assign the `us_mirror1` and
70
+
`us_mirror2` tags to every resource contained by `Apache::Vhost['docs.example.com']`.
71
+
72
+
### The `tag` function
73
+
74
+
You can use [the `tag` function][tagfunction] inside a class definition or defined type to assign tags to
75
+
the surrounding container and all of the resources it contains:
76
+
77
+
```puppet
78
+
class role::public_web {
79
+
tag 'us_mirror1', 'us_mirror2'
80
+
81
+
apache::vhost {'docs.example.com':
82
+
port => 80,
83
+
}
84
+
ssh::allowgroup {'www-data': }
85
+
@@nagios::website {'docs.example.com': }
86
+
}
87
+
```
88
+
89
+
The example above assigns `us_mirror1` and `us_mirror2` to all resources declared in `role::public_web`,
90
+
as well as to all the resources each of them contains.
91
+
92
+
## Using tags
93
+
94
+
### Collecting resources
95
+
96
+
Tags can be used as an attribute in the [search expression][collector_search] of a [resource
97
+
collector][collectors]. This is mostly useful for realizing [virtual][] and [exported][] resources.
98
+
99
+
### Restricting catalog runs
100
+
101
+
OpenVox agent and `puppet apply` can use [the `tags` setting][tags_setting] to only apply a subset of the
102
+
node's [catalog][]. This is useful when refactoring modules and allows you to only apply a single class on
103
+
a test node.
104
+
105
+
The `tags` setting can be set in `puppet.conf` (to permanently restrict the catalog) or on the command
106
+
line (to temporarily restrict it):
107
+
108
+
```bash
109
+
sudo puppet agent --test --tags apache,us_mirror1
110
+
```
111
+
112
+
The value of the `tags` setting should be a comma-separated list of tags with no spaces between tags.
113
+
114
+
### Reading tags in custom report handlers
115
+
116
+
Resource tags are available to custom report handlers and out-of-band report processors: each
117
+
`Puppet::Resource::Status` object and `Puppet::Util::Log` object has a `tags` key whose value is an array
118
+
containing every tag for the resource in question. See the following pages for more info:
0 commit comments