Restore lang_tags, lang_collectors, lang_run_stages from Puppet 5.4 archive

docs/_openvox_8x/lang_collectors.markdown

@@ -3,10 +3,147 @@ layout: default
 title: "Language: Resource collectors"
 ---
 
+[virtual]: ./lang_virtual.html
+[realize]: ./lang_virtual.html#syntax
+[exported]: ./lang_exported.html
+[chaining]: ./lang_relationships.html#syntax-chaining-arrows
+[attribute]: ./lang_resources.html#attributes
+[expressions]: ./lang_expressions.html
+[string]: ./lang_data_string.html
+[boolean]: ./lang_data_boolean.html
+[number]: ./lang_data_number.html
+[reference]: ./lang_data_resource_reference.html
+[undef]: ./lang_data_undef.html
+[amend]: ./lang_resources_advanced.html#amending-attributes-with-a-collector
+[catalog]: ./lang_summary.html#compilation-and-catalogs
 
-This page is no longer maintained in Github. Contributions from the Puppet community are still very welcome.
+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][virtual], can be used in [chaining statements][chaining], and can override resource
+attributes.
 
- - 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.
+Collectors have an irregular syntax that lets them function as both a statement and a value.
 
- - Email docs@puppet.com  if you have questions about contributing to the documentation.
+## Syntax
 
+``` puppet
+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](#exported-resource-collectors).
+
+### 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][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:
+
+* The left operand (attribute) must be the name of a [resource attribute][attribute] or the word `title`.
+* The right operand (search key) must be a [string][], [boolean][], [number][], [resource
+  reference][reference], or [undef][].
+
+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:
+
+* The left operand (attribute) must be the name of a [resource attribute][attribute] or the word `title`.
+* The right operand (search key) must be a [string][], [boolean][], [number][], [resource
+  reference][reference], or [undef][].
+
+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:
+
+* Independent statements
+* The operand of a [chaining statement][chaining]
+* In a [collector attribute block][amend] for amending resource attributes
+
+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][virtual] 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][chaining], 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][amend] 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].
+
+### Exported collector syntax
+
+Exported resource collectors are identical to collectors, except that their angle brackets are doubled:
+
+``` puppet
+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][exported] 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.

docs/_openvox_8x/lang_run_stages.markdown

@@ -3,10 +3,70 @@ layout: default
 title: "Language: Run stages"
 ---
 
+[metaparameter]: ./lang_resources.html#metaparameters
+[ordering]: ./lang_relationships.html
+[class]: ./lang_classes.html
+[resourcelike]: ./lang_classes.html#using-resource-like-declarations
+[containment]: ./lang_containment.html
 
-This page is no longer maintained in Github. Contributions from the Puppet community are still very welcome.
+Run stages are an additional way to order resources. They allow groups of classes to run before or after
+nearly everything else, without having to explicitly create relationships with every other class.
 
- - 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.
+Run stages have [several major limitations](#limitations-and-known-issues); you should understand these
+before attempting to use them.
 
- - Email docs@puppet.com  if you have questions about contributing to the documentation.
+The run stage feature has two parts:
 
+* A `stage` resource type.
+* A `stage` [metaparameter][], which assigns a class to a named run stage.
+
+## The default `main` stage
+
+By default there is only one stage (named `main`). All resources are automatically associated with this
+stage unless explicitly assigned to a different one. If you do not use run stages, every resource is in
+the main stage.
+
+## Custom stages
+
+Additional stages are declared as normal resources. Each additional stage must have an
+[order relationship][ordering] with another stage, such as `Stage['main']`. As with normal resources,
+these relationships can be specified with metaparameters or with chaining arrows.
+
+``` puppet
+stage { 'first':
+  before => Stage['main'],
+}
+stage { 'last': }
+Stage['main'] -> Stage['last']
+```
+
+In the above example, all classes assigned to the `first` stage will be applied before classes in the
+`main` stage, and both will be applied before the `last` stage.
+
+## Assigning classes to stages
+
+Once stages have been declared, a [class][] can be assigned to a custom stage with the `stage`
+metaparameter.
+
+``` puppet
+class { 'apt-keys':
+  stage => first,
+}
+```
+
+The above example ensures the `apt-keys` class happens before all other classes, which is useful if most
+of your package resources rely on those keys.
+
+## Limitations and known issues
+
+* To assign a class to a stage, you **must** use the [resource-like][resourcelike] class declaration
+  syntax and supply the stage explicitly. You **cannot** assign classes to stages with the `include`
+  function or by relying on automatic parameter lookup from Hiera with resource-like declarations.
+* You cannot subscribe to or notify resources across a stage boundary.
+* Classes that [contain][containment] other classes (with either the `contain` function or the anchor
+  pattern) can sometimes behave badly if declared with a run stage. If the contained class is only
+  declared by its container it will work fine, but if it is also declared anywhere outside its container
+  it will often create a dependency cycle that prevents the involved classes from being applied.
+
+Due to these limitations, **stages should only be used with the simplest of classes,** and only when
+absolutely necessary. Mass dependencies like package repositories are effectively the only valid use case.

docs/_openvox_8x/lang_tags.markdown

@@ -3,11 +3,119 @@ layout: default
 title: "Language: Tags"
 ---
 
+[virtual]: ./lang_virtual.html
+[exported]: ./lang_exported.html
+[namespace]: ./lang_namespaces.html
+[resources]: ./lang_resources.html
+[classes]: ./lang_classes.html
+[defined]: ./lang_defined_types.html
+[collectors]: ./lang_collectors.html
+[reports]: ./reporting_about.html
+[report_format]: ./format_report.html
+[tagmeta]: ./metaparameter.html#tag
+[tagfunction]: ./function.html#tag
+[tags_setting]: ./configuration.html#tags
+[tagnames]: ./lang_reserved.html#tags
+[relationships]: ./lang_relationships.html
+[containment]: ./lang_containment.html
+[collector_search]: ./lang_collectors.html#search-expressions
+[catalog]: ./lang_summary.html#compilation-and-catalogs
 
+[Resources][], [classes][], and [defined type instances][defined] can have any number of **tags** associated
+with them, plus they receive some tags automatically. Tags are useful for:
 
-This page is no longer maintained in Github. Contributions from the Puppet community are still very welcome.
+* [Collecting][collectors] resources
+* Analyzing [reports][]
+* Restricting catalog runs
 
- - 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.
+## Tag names
 
- - Email docs@puppet.com  if you have questions about contributing to the documentation.
+[See the reserved words page for the characters allowed in tag names.][tagnames]
 
+## Assigning tags to resources
+
+A resource can have any number of tags. There are several ways to assign a tag to a resource.
+
+### Automatic tagging
+
+Every resource automatically receives the following tags:
+
+* Its resource type
+* The full name of the [class][classes] and/or [defined type][defined] in which the resource was declared
+* Every [namespace segment][namespace] of the resource's class and/or defined type
+
+For example, a file resource in class `apache::ssl` would get the tags `file`, `apache::ssl`, `apache`,
+and `ssl`.
+
+### Containment
+
+Like [relationships][] and most metaparameters, tags are passed along by [containment][]. This means a
+resource will receive all of the tags from the class and/or defined type that contains it. In the case of
+nested containment (e.g. a class that declares a defined resource, or a defined type that declares other
+defined resources), a resource will receive tags from all of its containers.
+
+### The `tag` metaparameter
+
+You can use [the `tag` metaparameter][tagmeta] in a resource declaration to add any number of tags:
+
+``` puppet
+apache::vhost {'docs.example.com':
+  port => 80,
+  tag  => ['us_mirror1', 'us_mirror2'],
+}
+```
+
+The `tag` metaparameter can accept a single tag or an array. These will be added to the tags the resource
+already has. Since [containment][] applies to tags, the example above would assign the `us_mirror1` and
+`us_mirror2` tags to every resource contained by `Apache::Vhost['docs.example.com']`.
+
+### The `tag` function
+
+You can use [the `tag` function][tagfunction] inside a class definition or defined type to assign tags to
+the surrounding container and all of the resources it contains:
+
+``` puppet
+class role::public_web {
+  tag 'us_mirror1', 'us_mirror2'
+
+  apache::vhost {'docs.example.com':
+    port => 80,
+  }
+  ssh::allowgroup {'www-data': }
+  @@nagios::website {'docs.example.com': }
+}
+```
+
+The example above assigns `us_mirror1` and `us_mirror2` to all resources declared in `role::public_web`,
+as well as to all the resources each of them contains.
+
+## Using tags
+
+### Collecting resources
+
+Tags can be used as an attribute in the [search expression][collector_search] of a [resource
+collector][collectors]. This is mostly useful for realizing [virtual][] and [exported][] resources.
+
+### Restricting catalog runs
+
+OpenVox agent and `puppet apply` can use [the `tags` setting][tags_setting] to only apply a subset of the
+node's [catalog][]. This is useful when refactoring modules and allows you to only apply a single class on
+a test node.
+
+The `tags` setting can be set in `puppet.conf` (to permanently restrict the catalog) or on the command
+line (to temporarily restrict it):
+
+``` bash
+sudo puppet agent --test --tags apache,us_mirror1
+```
+
+The value of the `tags` setting should be a comma-separated list of tags with no spaces between tags.
+
+### Reading tags in custom report handlers
+
+Resource tags are available to custom report handlers and out-of-band report processors: each
+`Puppet::Resource::Status` object and `Puppet::Util::Log` object has a `tags` key whose value is an array
+containing every tag for the resource in question. See the following pages for more info:
+
+* [Processing Reports][reports]
+* [Report Format][report_format]