Skip to content

Commit bc13bea

Browse files
joshcooperjoshcooper
authored
Merge pull request #9462 from joshcooper/references_meta_report
2 parents 4a74a9e + 1e01036 commit bc13bea

File tree

5 files changed

+352
-0
lines changed

5 files changed

+352
-0
lines changed

‎rakelib/generate_references.rake

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ require 'tempfile'
33
OUTPUT_DIR = 'references'
44
CONFIGURATION_ERB = File.join(__dir__, 'references/configuration.erb')
55
CONFIGURATION_MD = File.join(OUTPUT_DIR, 'configuration.md')
6+
METAPARAMETER_ERB = File.join(__dir__, 'references/metaparameter.erb')
7+
METAPARAMETER_MD = File.join(OUTPUT_DIR, 'metaparameter.md')
8+
REPORT_ERB = File.join(__dir__, 'references/report.erb')
9+
REPORT_MD = File.join(OUTPUT_DIR, 'report.md')
610

711
def render_erb(erb_file, variables)
812
# Create a binding so only the variables we specify will be visible
@@ -40,4 +44,16 @@ namespace :references do
4044
body = puppet_doc('configuration')
4145
generate_reference('configuration', CONFIGURATION_ERB, body, CONFIGURATION_MD)
4246
end
47+
48+
desc "Generate metaparameter reference"
49+
task :metaparameter do
50+
body = puppet_doc('metaparameter')
51+
generate_reference('metaparameter', METAPARAMETER_ERB, body, METAPARAMETER_MD)
52+
end
53+
54+
desc "Generate report reference"
55+
task :report do
56+
body = puppet_doc('report')
57+
generate_reference('report', REPORT_ERB, body, REPORT_MD)
58+
end
4359
end

‎rakelib/references/metaparameter.erb

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
layout: default
3+
built_from_commit: <%= sha %>
4+
title: Metaparameter Reference
5+
toc: columns
6+
canonical: "/puppet/latest/metaparameter.html"
7+
---
8+
9+
# Metaparameter Reference
10+
11+
> **NOTE:** This page was generated from the Puppet source code on <%= now %>
12+
13+
<%= body %>

‎rakelib/references/report.erb

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
layout: default
3+
built_from_commit: <%= sha %>
4+
title: Report Reference
5+
toc: columns
6+
canonical: "/puppet/latest/report.html"
7+
---
8+
9+
# Report Reference
10+
11+
> **NOTE:** This page was generated from the Puppet source code on <%= now %>
12+
13+
<%= body %>

‎references/metaparameter.md

Lines changed: 260 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,260 @@
1+
---
2+
layout: default
3+
built_from_commit: c0f933882f92b7998fe94e2a57bbdf69f77ac61e
4+
title: Metaparameter Reference
5+
toc: columns
6+
canonical: "/puppet/latest/metaparameter.html"
7+
---
8+
9+
# Metaparameter Reference
10+
11+
> **NOTE:** This page was generated from the Puppet source code on 2024-08-29 09:52:11 -0700
12+
13+
14+
15+
16+
17+
Metaparameters are attributes that work with any resource type, including custom
18+
types and defined types.
19+
20+
In general, they affect _Puppet's_ behavior rather than the desired state of the
21+
resource. Metaparameters do things like add metadata to a resource (`alias`,
22+
`tag`), set limits on when the resource should be synced (`require`, `schedule`,
23+
etc.), prevent Puppet from making changes (`noop`), and change logging verbosity
24+
(`loglevel`).
25+
26+
## Available Metaparameters
27+
28+
### alias
29+
30+
Creates an alias for the resource. Puppet uses this internally when you
31+
provide a symbolic title and an explicit namevar value:
32+
33+
file { 'sshdconfig':
34+
path => $os['name'] ? {
35+
solaris => '/usr/local/etc/ssh/sshd_config',
36+
default => '/etc/ssh/sshd_config',
37+
},
38+
source => '...'
39+
}
40+
41+
service { 'sshd':
42+
subscribe => File['sshdconfig'],
43+
}
44+
45+
When you use this feature, the parser sets `sshdconfig` as the title,
46+
and the library sets that as an alias for the file so the dependency
47+
lookup in `Service['sshd']` works. You can use this metaparameter yourself,
48+
but note that aliases generally only work for creating relationships; anything
49+
else that refers to an existing resource (such as amending or overriding
50+
resource attributes in an inherited class) must use the resource's exact
51+
title. For example, the following code will not work:
52+
53+
file { '/etc/ssh/sshd_config':
54+
owner => root,
55+
group => root,
56+
alias => 'sshdconfig',
57+
}
58+
59+
File['sshdconfig'] {
60+
mode => '0644',
61+
}
62+
63+
There's no way here for the Puppet parser to know that these two stanzas
64+
should be affecting the same file.
65+
66+
### audit
67+
68+
Marks a subset of this resource's unmanaged attributes for auditing. Accepts an
69+
attribute name, an array of attribute names, or `all`.
70+
71+
Auditing a resource attribute has two effects: First, whenever a catalog
72+
is applied with puppet apply or puppet agent, Puppet will check whether
73+
that attribute of the resource has been modified, comparing its current
74+
value to the previous run; any change will be logged alongside any actions
75+
performed by Puppet while applying the catalog.
76+
77+
Secondly, marking a resource attribute for auditing will include that
78+
attribute in inspection reports generated by puppet inspect; see the
79+
puppet inspect documentation for more details.
80+
81+
Managed attributes for a resource can also be audited, but note that
82+
changes made by Puppet will be logged as additional modifications. (I.e.
83+
if a user manually edits a file whose contents are audited and managed,
84+
puppet agent's next two runs will both log an audit notice: the first run
85+
will log the user's edit and then revert the file to the desired state,
86+
and the second run will log the edit made by Puppet.)
87+
88+
### before
89+
90+
One or more resources that depend on this resource, expressed as
91+
[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html).
92+
Multiple resources can be specified as an array of references. When this
93+
attribute is present:
94+
95+
* This resource will be applied _before_ the dependent resources.
96+
97+
This is one of the four relationship metaparameters, along with
98+
`require`, `notify`, and `subscribe`. For more context, including the
99+
alternate chaining arrow (`->` and `~>`) syntax, see
100+
[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html).
101+
102+
### loglevel
103+
104+
Sets the level that information will be logged.
105+
The log levels have the biggest impact when logs are sent to
106+
syslog (which is currently the default).
107+
108+
The order of the log levels, in decreasing priority, is:
109+
110+
* `emerg`
111+
* `alert`
112+
* `crit`
113+
* `err`
114+
* `warning`
115+
* `notice`
116+
* `info` / `verbose`
117+
* `debug`
118+
119+
Valid values are `debug`, `info`, `notice`, `warning`, `err`, `alert`, `emerg`, `crit`, `verbose`.
120+
121+
### noop
122+
123+
Whether to apply this resource in noop mode.
124+
125+
When applying a resource in noop mode, Puppet will check whether it is in sync,
126+
like it does when running normally. However, if a resource attribute is not in
127+
the desired state (as declared in the catalog), Puppet will take no
128+
action, and will instead report the changes it _would_ have made. These
129+
simulated changes will appear in the report sent to the primary Puppet server, or
130+
be shown on the console if running puppet agent or puppet apply in the
131+
foreground. The simulated changes will not send refresh events to any
132+
subscribing or notified resources, although Puppet will log that a refresh
133+
event _would_ have been sent.
134+
135+
**Important note:**
136+
[The `noop` setting](https://puppet.com/docs/puppet/latest/configuration.html#noop)
137+
allows you to globally enable or disable noop mode, but it will _not_ override
138+
the `noop` metaparameter on individual resources. That is, the value of the
139+
global `noop` setting will _only_ affect resources that do not have an explicit
140+
value set for their `noop` attribute.
141+
142+
Valid values are `true`, `false`.
143+
144+
### notify
145+
146+
One or more resources that depend on this resource, expressed as
147+
[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html).
148+
Multiple resources can be specified as an array of references. When this
149+
attribute is present:
150+
151+
* This resource will be applied _before_ the notified resources.
152+
* If Puppet makes changes to this resource, it will cause all of the
153+
notified resources to _refresh._ (Refresh behavior varies by resource
154+
type: services will restart, mounts will unmount and re-mount, etc. Not
155+
all types can refresh.)
156+
157+
This is one of the four relationship metaparameters, along with
158+
`before`, `require`, and `subscribe`. For more context, including the
159+
alternate chaining arrow (`->` and `~>`) syntax, see
160+
[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html).
161+
162+
### require
163+
164+
One or more resources that this resource depends on, expressed as
165+
[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html).
166+
Multiple resources can be specified as an array of references. When this
167+
attribute is present:
168+
169+
* The required resources will be applied **before** this resource.
170+
171+
This is one of the four relationship metaparameters, along with
172+
`before`, `notify`, and `subscribe`. For more context, including the
173+
alternate chaining arrow (`->` and `~>`) syntax, see
174+
[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html).
175+
176+
### schedule
177+
178+
A schedule to govern when Puppet is allowed to manage this resource.
179+
The value of this metaparameter must be the `name` of a `schedule`
180+
resource. This means you must declare a schedule resource, then
181+
refer to it by name; see
182+
[the docs for the `schedule` type](https://puppet.com/docs/puppet/latest/type.html#schedule)
183+
for more info.
184+
185+
schedule { 'everyday':
186+
period => daily,
187+
range => "2-4"
188+
}
189+
190+
exec { "/usr/bin/apt-get update":
191+
schedule => 'everyday'
192+
}
193+
194+
Note that you can declare the schedule resource anywhere in your
195+
manifests, as long as it ends up in the final compiled catalog.
196+
197+
### stage
198+
199+
Which run stage this class should reside in.
200+
201+
**Note: This metaparameter can only be used on classes,** and only when
202+
declaring them with the resource-like syntax. It cannot be used on normal
203+
resources or on classes declared with `include`.
204+
205+
By default, all classes are declared in the `main` stage. To assign a class
206+
to a different stage, you must:
207+
208+
* Declare the new stage as a [`stage` resource](https://puppet.com/docs/puppet/latest/type.html#stage).
209+
* Declare an order relationship between the new stage and the `main` stage.
210+
* Use the resource-like syntax to declare the class, and set the `stage`
211+
metaparameter to the name of the desired stage.
212+
213+
For example:
214+
215+
stage { 'pre':
216+
before => Stage['main'],
217+
}
218+
219+
class { 'apt-updates':
220+
stage => 'pre',
221+
}
222+
223+
### subscribe
224+
225+
One or more resources that this resource depends on, expressed as
226+
[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html).
227+
Multiple resources can be specified as an array of references. When this
228+
attribute is present:
229+
230+
* The subscribed resources will be applied _before_ this resource.
231+
* If Puppet makes changes to any of the subscribed resources, it will cause
232+
this resource to _refresh._ (Refresh behavior varies by resource
233+
type: services will restart, mounts will unmount and re-mount, etc. Not
234+
all types can refresh.)
235+
236+
This is one of the four relationship metaparameters, along with
237+
`before`, `require`, and `notify`. For more context, including the
238+
alternate chaining arrow (`->` and `~>`) syntax, see
239+
[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html).
240+
241+
### tag
242+
243+
Add the specified tags to the associated resource. While all resources
244+
are automatically tagged with as much information as possible
245+
(e.g., each class and definition containing the resource), it can
246+
be useful to add your own tags to a given resource.
247+
248+
Multiple tags can be specified as an array:
249+
250+
file {'/etc/hosts':
251+
ensure => file,
252+
source => 'puppet:///modules/site/hosts',
253+
mode => '0644',
254+
tag => ['bootstrap', 'minimumrun', 'mediumrun'],
255+
}
256+
257+
Tags are useful for things like applying a subset of a host's configuration
258+
with [the `tags` setting](https://puppet.com/docs/puppet/latest/configuration.html#tags)
259+
(e.g. `puppet agent --test --tags bootstrap`).
260+

‎references/report.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
layout: default
3+
built_from_commit: 41ffe0f49158b8f34714b7e18429afa0ce8ded09
4+
title: Report Reference
5+
toc: columns
6+
canonical: "/puppet/latest/report.html"
7+
---
8+
9+
# Report Reference
10+
11+
> **NOTE:** This page was generated from the Puppet source code on 2024-08-29 09:52:52 -0700
12+
13+
14+
15+
16+
Puppet can generate a report after applying a catalog. This report includes
17+
events, log messages, resource statuses, and metrics and metadata about the run.
18+
Puppet agent sends its report to a Puppet master server, and Puppet apply
19+
processes its own reports.
20+
21+
Puppet master and Puppet apply will handle every report with a set of report
22+
processors, configurable with the `reports` setting in puppet.conf. This page
23+
documents the built-in report processors.
24+
25+
See [About Reporting](https://puppet.com/docs/puppet/latest/reporting_about.html)
26+
for more details.
27+
28+
http
29+
----
30+
Send reports via HTTP or HTTPS. This report processor submits reports as
31+
POST requests to the address in the `reporturl` setting. When a HTTPS URL
32+
is used, the remote server must present a certificate issued by the Puppet
33+
CA or the connection will fail validation. The body of each POST request
34+
is the YAML dump of a Puppet::Transaction::Report object, and the
35+
Content-Type is set as `application/x-yaml`.
36+
37+
log
38+
---
39+
Send all received logs to the local log destinations. Usually
40+
the log destination is syslog.
41+
42+
store
43+
-----
44+
Store the yaml report on disk. Each host sends its report as a YAML dump
45+
and this just stores the file on disk, in the `reportdir` directory.
46+
47+
These files collect quickly -- one every half hour -- so it is a good idea
48+
to perform some maintenance on them if you use this report (it's the only
49+
default report).
50+

0 commit comments

Comments
 (0)