Resources, classes, and defined type instances may have any number of tags associated with them, plus they receive some tags automatically. Tags are useful for:
See here for the characters allowed in tag names.
A resource may have any number of tags. There are several ways to assign a tag to a resource.
Every resource automatically receives the following tags:
For example, a file resource in class apache::ssl
would get the tags file
, apache::ssl
, apache
, and ssl
.
Class tags are generally the most useful, especially when setting up tagmail or testing refactored manifests.
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.
tag
MetaparameterYou can use the tag
metaparameter in a resource declaration to add any number of tags:
apache::vhost {'docs.puppetlabs.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. Also, tag
can be used with normal resources, defined resources, and classes (when using the resource-like declaration syntax). 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.puppetlabs.com']
.
tag
FunctionYou can use the tag
function inside a class definition or defined type to assign tags to the surrounding container and all of the resources it contains:
class role::public_web {
tag 'us_mirror1', 'us_mirror2'
apache::vhost {'docs.puppetlabs.com':
port => 80,
}
ssh::allowgroup {'www-data': }
@@nagios::website {'docs.puppetlabs.com': }
}
The example above would assign the us_mirror1
and us_mirror2
tags to all of the defined resources being declared in the class role::public_web
, as well as to all of the resources each of them contains.
Tags can be used as an attribute in the search expression of a resource collector. This is mostly useful for realizing virtual and exported resources.
Puppet agent and Puppet apply can use the 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):
$ 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).
The built-in tagmail report handler can send emails to arbitrary email addresses whenever resources with certain tags are changed. See the following for more info:
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: