Metaparameter reference

Metaparameters are attributes that work with any resource type, including custom types and defined types. They change the way Puppet handles resources.

With metaparameters, you can change how Puppet handles specific resources. For example, you can:
  • Add metadata to a resource with the alias or tag metaparameters.
  • Set limits on when the resource should be applied, by using relationship metaparameters like notify or require.
  • Prevent Puppet from making changes, by setting the noop metaparameter.
  • Change logging verbosity with the loglevel metaparameter.

alias

Creates an alias for the resource. You can explicitly specify the alias metaparameter, but it's usually safer to give the resource the alias value as the title and provide the full namevar value explicitly.

For example, this sample gives the title as sshdconfig, which acts as the alias. The namevar value is the path, which is set to '/etc/ssh/sshd_config'.
file { 'sshdconfig': 
  path => '/etc/ssh/sshd_config',
  source => '...'
}

service { 'sshd': 
  subscribe => File['sshdconfig'],
}
Aliases generally work only 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, because there's no way for Puppet to know that the two stanzas should affect the same file.
file { '/etc/ssh/sshd_config': 
  owner => root,
  group => root,
  alias => 'sshdconfig',
 }

File['sshdconfig'] {
  mode => '0644',
}

audit

Marks a subset of this resource's unmanaged attributes for auditing. Accepts an attribute name, an array of attribute names, or the value all.

When audit is set for an attribute, when Puppet applies the catalog, it checks whether that attribute of the resource has been modified, comparing its current value to the previous run. Any change is then logged alongside any actions Puppet performed while applying the catalog.

before

Specifies one or more resources that depend on this resource, expressed as resource references. Specify multiple resources as an array of references. When specified, before causes the resource to be applied before the dependent resources. This is one of the four relationship metaparameters, along with require, notify, and subscribe. For more information about creating relationships between resources, see Relationships and ordering. For details about resource references, see Resource and class references.

consume

Consumes a capability resource. The value of this parameter must be a reference to a capability resource, or an array of such references.

Each capability resource referenced here must have been exported by another resource in the same environment. Puppet looks up the referenced capability resources, adds them to the current node catalog, and processes them following the underlying consumes clause. Puppet returns an error if this metaparameter references a resource that is not a capability type, or if there is no consume clause for the type of the current resource and the capability resource mentioned in this parameter.

For example:
define web(..) { .. }
Web consumes Sql { .. }
web { server:
  consume => Sql[my_db]
}

export

Exports a capability resource. The value of this parameter must be a reference to a capability resource, or an array of such references.

Each capability resource referenced here is instantiated in the node catalog and exported to consumers of this resource. The title of the capability resource is the title given in the reference, and all other attributes of the resource are filled according to the corresponding produces statement. Puppet returns an error if this metaparameter references a resource that is not a capability type, or of there is no produces clause for the type of the current resource and the capability resource mentioned in this parameter.

For example:
define web(..) { .. }
Web produces Http { .. }
web { server:
  export => Http[main_server]
}

loglevel

Sets the level at which information is logged. The log levels have the biggest impact when logs are sent to syslog, which is the default log. Any of the log levels are valid values for this metaparameter. The order of the log levels, in decreasing priority, is:
  • emerg
  • alert
  • crit
  • err
  • warning
  • notice
  • info
  • verbose
  • debug

noop

Whether to apply this resource in non-operational, or "no-op" mode. When applying a resource in noop mode, Puppet checks whether the resource is in the desired state as declared in the catalog. If the resource is not in the desired state, Puppet takes no action, but reports the changes it would have made. These simulated changes appear in the report sent to the primary server or are displayed be shown on the console if running puppet agent or puppet apply in the foreground. The simulated changes do not send refresh events to any subscribing or notified resources, although Puppet logs that a refresh event would have been sent. Valid values are true or false.

Note: The noop setting allows you to globally enable or disable noop mode, but it does not override the noop metaparameter on individual resources. That is, the value of a global noop setting affects only resources that do not have an explicit value set for their noop attribute.

notify

Specifies one or more resources that depend on this resource, expressed as resource references. Specify multiple resources as an array of references.

When this attribute is set, this resource is applied before the notified resources. If Puppet makes changes to this resource, it causes all of the notified resources to refresh. Refresh behavior varies by resource type: for example, services restart and mounts unmount and re-mount. Not all types can refresh.

This is one of the four relationship metaparameters, along with before, require, and subscribe. For more information about creating relationships between resources, see Relationships and ordering. For details about resource references, see Resource and class references.

require

Specifies one or more resources that depend on this resource, expressed as resource references. Specify multiple resources as an array of references.

When this attribute is set, the required resources are applied before this resource.

This is one of the four relationship metaparameters, along with before, notify, and subscribe. For more information about creating relationships between resources, see Relationships and ordering. For details about resource references, see Resource and class references.

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 first declare a schedule resource, then refer to it by name.

For example:
schedule { 'everyday': 
  period => daily,
  range  => "2-4"
  }

exec { "/usr/bin/apt-get update": 
  schedule => 'everyday'
}
You can declare the schedule resource anywhere in your manifests, as long as it ends up in the final compiled catalog.

See the schedule type for more information.

stage

Which run stage this class should reside in. To assign a class to a different stage, you must:
  • Declare the new stage as a stage resource See the stage type for details.
  • 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.
Important: 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.
For example:
stage { 'pre': 
  before => Stage['main'],
}

class { 'apt-updates': 
  stage => 'pre',
}

subscribe

Specifies one or more resources that depend on this resource, expressed as resource references. Specify multiple resources as an array of references.

When this attribute is present, the subscribed resources are applied before this resource. If Puppet makes changes to any of the subscribed resources, it causes this resource to refresh. Refresh behavior varies by resource type: for example, services restart and mounts unmount and re-mount. Not all types can refresh.

This is one of the four relationship metaparameters, along with before, require, and notify. For more information about creating relationships between resources, see Relationships and ordering. For details about resource references, see Resource and class references.

tag

Add the specified tags to the associated resource. Although all resources are automatically tagged with as much information as possible, such as with 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 configuration setting, such as with puppet agent --test --tags bootstrap. See the configuration reference for more information about the tags setting