diff --git a/rakelib/generate_references.rake b/rakelib/generate_references.rake index 364160a0557..8dec11b83c8 100644 --- a/rakelib/generate_references.rake +++ b/rakelib/generate_references.rake @@ -3,6 +3,10 @@ require 'tempfile' OUTPUT_DIR = 'references' CONFIGURATION_ERB = File.join(__dir__, 'references/configuration.erb') CONFIGURATION_MD = File.join(OUTPUT_DIR, 'configuration.md') +METAPARAMETER_ERB = File.join(__dir__, 'references/metaparameter.erb') +METAPARAMETER_MD = File.join(OUTPUT_DIR, 'metaparameter.md') +REPORT_ERB = File.join(__dir__, 'references/report.erb') +REPORT_MD = File.join(OUTPUT_DIR, 'report.md') def render_erb(erb_file, variables) # Create a binding so only the variables we specify will be visible @@ -40,4 +44,16 @@ namespace :references do body = puppet_doc('configuration') generate_reference('configuration', CONFIGURATION_ERB, body, CONFIGURATION_MD) end + + desc "Generate metaparameter reference" + task :metaparameter do + body = puppet_doc('metaparameter') + generate_reference('metaparameter', METAPARAMETER_ERB, body, METAPARAMETER_MD) + end + + desc "Generate report reference" + task :report do + body = puppet_doc('report') + generate_reference('report', REPORT_ERB, body, REPORT_MD) + end end diff --git a/rakelib/references/metaparameter.erb b/rakelib/references/metaparameter.erb new file mode 100644 index 00000000000..7022c9c77d9 --- /dev/null +++ b/rakelib/references/metaparameter.erb @@ -0,0 +1,13 @@ +--- +layout: default +built_from_commit: <%= sha %> +title: Metaparameter Reference +toc: columns +canonical: "/puppet/latest/metaparameter.html" +--- + +# Metaparameter Reference + +> **NOTE:** This page was generated from the Puppet source code on <%= now %> + +<%= body %> diff --git a/rakelib/references/report.erb b/rakelib/references/report.erb new file mode 100644 index 00000000000..9424a995752 --- /dev/null +++ b/rakelib/references/report.erb @@ -0,0 +1,13 @@ +--- +layout: default +built_from_commit: <%= sha %> +title: Report Reference +toc: columns +canonical: "/puppet/latest/report.html" +--- + +# Report Reference + +> **NOTE:** This page was generated from the Puppet source code on <%= now %> + +<%= body %> diff --git a/references/metaparameter.md b/references/metaparameter.md new file mode 100644 index 00000000000..a806fc9bd27 --- /dev/null +++ b/references/metaparameter.md @@ -0,0 +1,260 @@ +--- +layout: default +built_from_commit: c0f933882f92b7998fe94e2a57bbdf69f77ac61e +title: Metaparameter Reference +toc: columns +canonical: "/puppet/latest/metaparameter.html" +--- + +# Metaparameter Reference + +> **NOTE:** This page was generated from the Puppet source code on 2024-08-29 09:52:11 -0700 + + + + + +Metaparameters are attributes that work with any resource type, including custom +types and defined types. + +In general, they affect _Puppet's_ behavior rather than the desired state of the +resource. Metaparameters do things like add metadata to a resource (`alias`, +`tag`), set limits on when the resource should be synced (`require`, `schedule`, +etc.), prevent Puppet from making changes (`noop`), and change logging verbosity +(`loglevel`). + +## Available Metaparameters + + ### alias + +Creates an alias for the resource. Puppet uses this internally when you +provide a symbolic title and an explicit namevar value: + + file { 'sshdconfig': + path => $os['name'] ? { + solaris => '/usr/local/etc/ssh/sshd_config', + default => '/etc/ssh/sshd_config', + }, + source => '...' + } + + service { 'sshd': + subscribe => File['sshdconfig'], + } + +When you use this feature, the parser sets `sshdconfig` as the title, +and the library sets that as an alias for the file so the dependency +lookup in `Service['sshd']` works. You can use this metaparameter yourself, +but note that aliases generally only work for creating relationships; anything +else that refers to an existing resource (such as amending or overriding +resource attributes in an inherited class) must use the resource's exact +title. For example, the following code will not work: + + file { '/etc/ssh/sshd_config': + owner => root, + group => root, + alias => 'sshdconfig', + } + + File['sshdconfig'] { + mode => '0644', + } + +There's no way here for the Puppet parser to know that these two stanzas +should be affecting the same file. + +### audit + +Marks a subset of this resource's unmanaged attributes for auditing. Accepts an +attribute name, an array of attribute names, or `all`. + +Auditing a resource attribute has two effects: First, whenever a catalog +is applied with puppet apply or puppet agent, Puppet will check whether +that attribute of the resource has been modified, comparing its current +value to the previous run; any change will be logged alongside any actions +performed by Puppet while applying the catalog. + +Secondly, marking a resource attribute for auditing will include that +attribute in inspection reports generated by puppet inspect; see the +puppet inspect documentation for more details. + +Managed attributes for a resource can also be audited, but note that +changes made by Puppet will be logged as additional modifications. (I.e. +if a user manually edits a file whose contents are audited and managed, +puppet agent's next two runs will both log an audit notice: the first run +will log the user's edit and then revert the file to the desired state, +and the second run will log the edit made by Puppet.) + +### before + +One or more resources that depend on this resource, expressed as +[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html). +Multiple resources can be specified as an array of references. When this +attribute is present: + +* This resource will be applied _before_ the dependent resources. + +This is one of the four relationship metaparameters, along with +`require`, `notify`, and `subscribe`. For more context, including the +alternate chaining arrow (`->` and `~>`) syntax, see +[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html). + +### loglevel + +Sets the level that information will be logged. +The log levels have the biggest impact when logs are sent to +syslog (which is currently the default). + +The order of the log levels, in decreasing priority, is: + +* `emerg` +* `alert` +* `crit` +* `err` +* `warning` +* `notice` +* `info` / `verbose` +* `debug` + +Valid values are `debug`, `info`, `notice`, `warning`, `err`, `alert`, `emerg`, `crit`, `verbose`. + +### noop + +Whether to apply this resource in noop mode. + +When applying a resource in noop mode, Puppet will check whether it is in sync, +like it does when running normally. However, if a resource attribute is not in +the desired state (as declared in the catalog), Puppet will take no +action, and will instead report the changes it _would_ have made. These +simulated changes will appear in the report sent to the primary Puppet server, or +be shown on the console if running puppet agent or puppet apply in the +foreground. The simulated changes will not send refresh events to any +subscribing or notified resources, although Puppet will log that a refresh +event _would_ have been sent. + +**Important note:** +[The `noop` setting](https://puppet.com/docs/puppet/latest/configuration.html#noop) +allows you to globally enable or disable noop mode, but it will _not_ override +the `noop` metaparameter on individual resources. That is, the value of the +global `noop` setting will _only_ affect resources that do not have an explicit +value set for their `noop` attribute. + +Valid values are `true`, `false`. + +### notify + +One or more resources that depend on this resource, expressed as +[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html). +Multiple resources can be specified as an array of references. When this +attribute is present: + +* This resource will be applied _before_ the notified resources. +* If Puppet makes changes to this resource, it will cause all of the + notified resources to _refresh._ (Refresh behavior varies by resource + type: services will restart, mounts will unmount and re-mount, etc. Not + all types can refresh.) + +This is one of the four relationship metaparameters, along with +`before`, `require`, and `subscribe`. For more context, including the +alternate chaining arrow (`->` and `~>`) syntax, see +[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html). + +### require + +One or more resources that this resource depends on, expressed as +[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html). +Multiple resources can be specified as an array of references. When this +attribute is present: + +* The required resources will be applied **before** this resource. + +This is one of the four relationship metaparameters, along with +`before`, `notify`, and `subscribe`. For more context, including the +alternate chaining arrow (`->` and `~>`) syntax, see +[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html). + +### schedule + +A schedule to govern when Puppet is allowed to manage this resource. +The value of this metaparameter must be the `name` of a `schedule` +resource. This means you must declare a schedule resource, then +refer to it by name; see +[the docs for the `schedule` type](https://puppet.com/docs/puppet/latest/type.html#schedule) +for more info. + + schedule { 'everyday': + period => daily, + range => "2-4" + } + + exec { "/usr/bin/apt-get update": + schedule => 'everyday' + } + +Note that you can declare the schedule resource anywhere in your +manifests, as long as it ends up in the final compiled catalog. + +### stage + +Which run stage this class should reside in. + +**Note: This metaparameter can only be used on classes,** and only when +declaring them with the resource-like syntax. It cannot be used on normal +resources or on classes declared with `include`. + +By default, all classes are declared in the `main` stage. To assign a class +to a different stage, you must: + +* Declare the new stage as a [`stage` resource](https://puppet.com/docs/puppet/latest/type.html#stage). +* Declare an order relationship between the new stage and the `main` stage. +* Use the resource-like syntax to declare the class, and set the `stage` + metaparameter to the name of the desired stage. + +For example: + + stage { 'pre': + before => Stage['main'], + } + + class { 'apt-updates': + stage => 'pre', + } + +### subscribe + +One or more resources that this resource depends on, expressed as +[resource references](https://puppet.com/docs/puppet/latest/lang_data_resource_reference.html). +Multiple resources can be specified as an array of references. When this +attribute is present: + +* The subscribed resources will be applied _before_ this resource. +* If Puppet makes changes to any of the subscribed resources, it will cause + this resource to _refresh._ (Refresh behavior varies by resource + type: services will restart, mounts will unmount and re-mount, etc. Not + all types can refresh.) + +This is one of the four relationship metaparameters, along with +`before`, `require`, and `notify`. For more context, including the +alternate chaining arrow (`->` and `~>`) syntax, see +[the language page on relationships](https://puppet.com/docs/puppet/latest/lang_relationships.html). + +### tag + +Add the specified tags to the associated resource. While all resources +are automatically tagged with as much information as possible +(e.g., each class and definition containing the resource), it can +be useful to add your own tags to a given resource. + +Multiple tags can be specified as an array: + + file {'/etc/hosts': + ensure => file, + source => 'puppet:///modules/site/hosts', + mode => '0644', + tag => ['bootstrap', 'minimumrun', 'mediumrun'], + } + +Tags are useful for things like applying a subset of a host's configuration +with [the `tags` setting](https://puppet.com/docs/puppet/latest/configuration.html#tags) +(e.g. `puppet agent --test --tags bootstrap`). + diff --git a/references/report.md b/references/report.md new file mode 100644 index 00000000000..dba027d1f75 --- /dev/null +++ b/references/report.md @@ -0,0 +1,50 @@ +--- +layout: default +built_from_commit: 41ffe0f49158b8f34714b7e18429afa0ce8ded09 +title: Report Reference +toc: columns +canonical: "/puppet/latest/report.html" +--- + +# Report Reference + +> **NOTE:** This page was generated from the Puppet source code on 2024-08-29 09:52:52 -0700 + + + + +Puppet can generate a report after applying a catalog. This report includes +events, log messages, resource statuses, and metrics and metadata about the run. +Puppet agent sends its report to a Puppet master server, and Puppet apply +processes its own reports. + +Puppet master and Puppet apply will handle every report with a set of report +processors, configurable with the `reports` setting in puppet.conf. This page +documents the built-in report processors. + +See [About Reporting](https://puppet.com/docs/puppet/latest/reporting_about.html) +for more details. + +http +---- +Send reports via HTTP or HTTPS. This report processor submits reports as +POST requests to the address in the `reporturl` setting. When a HTTPS URL +is used, the remote server must present a certificate issued by the Puppet +CA or the connection will fail validation. The body of each POST request +is the YAML dump of a Puppet::Transaction::Report object, and the +Content-Type is set as `application/x-yaml`. + +log +--- +Send all received logs to the local log destinations. Usually +the log destination is syslog. + +store +----- +Store the yaml report on disk. Each host sends its report as a YAML dump +and this just stores the file on disk, in the `reportdir` directory. + +These files collect quickly -- one every half hour -- so it is a good idea +to perform some maintenance on them if you use this report (it's the only +default report). +