Tags | Puppet.com

Sections

Tags are useful for collecting resources, analyzing reports, and restricting catalog runs. Resources, classes, and defined type instances can have multiple tags associated with them, and they receive some tags automatically.

Tag names

For information about the characters allowed in tag names, see reserved words and acceptable names.

Assigning tags to resources

Every resource automatically receives the following tags:

Its resource type.
The full name of the class or defined type in which the resource was declared.
Every namespace segment of the resource’s class or defined type.

For example, a file resource in class apache::ssl is automatically assigned the tags file, apache::ssl, apache, and ssl. Do not manually assign tags with names that are the same as these automatically assigned tags.

Tip: Class tags are useful when setting up the tagmail module or testing refactored manifests.

Similar to relationships and most metaparameters, tags are passed along by containment. This means a resource receives all of the tags from the class and/or defined type that contains it. In the case of nested containment (a class that declares a defined resource, or a defined type that declares other defined resources), a resource receives tags from all of its containers.

The tag metaparameter accepts a single tag or an array, and these are added to the tags the resource already has. A tag can also be used with normal resources, defined resources, and classes (when using the resource-like declaration syntax).

Because containment applies to tags, the example below assigns the us_mirror1 and us_mirror2 tags to every resource contained by Apache::Vhost['docs.puppetlabs.com'].

To add multiple tags, use the tag metaparameter in a resource declaration:

apache::vhost {'docs.puppetlabs.com':
  port => 80,
  tag  => ['us_mirror1', 'us_mirror2'],
}

To assign tags to the surrounding container and all of the resources it contains, use the tag function inside a class definition or defined type. The example below assigns 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.

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': }
}

Using tags

Tip: Tags are useful when used as an attribute in the search expression of a resource collector for realizing virtual and exported resources.

Puppet agent and Puppet apply use the tags setting to apply a subset of the node’s catalog. This is useful when refactoring modules, and enables you to apply a single class on a test node.

The tags setting can be set in puppet.conf to restrict the catalog, or on the command line to temporarily restrict it. The value of the tags setting should be a comma-separated list of tags, with no spaces between tags:

$ sudo puppet agent --test --tags apache,us_mirror1

The tagmail module sends emails to arbitrary email addresses whenever resources with certain tags are changed.

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.

For more information, see:

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project