Declaring classes

You can declare classes in node definitions, at top scope in the site manifest, and in other classes or defined types. Classes are singletons — although a given class can behave very differently depending on how its parameters are set, the resources in it are evaluated only once per compilation. You can also assign classes to nodes with an external node classifier (ENC) .

Puppet has two main ways to declare classes: include-like and resource-like. Include-like declarations are the most common; they are flexible and idempotent, so you can safely repeat them without causing errors. Resource-like declarations are mostly useful if you want to pass parameters to the class but can't or don't use Hiera. Most ENCs assign classes with include-like behavior, but others assign them with resource-like behavior. See the ENC interface documentation or the documentation of your specific ENC for details.

Include-like declarations

Include-like resource declarations allow you to declare a class multiple times — but no matter how many times you add the class, it is added to the catalog only once. This allows classes or defined types to manage their own dependencies and allows you create overlapping role classes, in which a given node can have more than one role.

Include-like behavior relies on external data and defaults for class parameter values, which allows the external data source to act like cascading configuration files for all of your classes.

You can declare a class with this behavior with one of three functions: include, require, and contain.

When a class is declared with an include-like declaration, Puppet takes the following actions, in order, for each of the class parameters:

1. Requests a value from the external data source, using the key <class name>::<parameter name>. For example, to get the apache class's version parameter, Puppet searches for apache::version.
2. Uses the default value, if one exists.
3. Fails compilation with an error, if no value is found.

The include function

The include function is the most common way to declare classes. Declaring a class with this function includes the class in the catalog.

This function uses include-like behavior, so you can make multiple declarations and Puppet relies on external data for parameters.

The include function accepts one of the following:

• A single class name, such as apache.
• A single class reference, such as Class['apache'].
• A comma-separated list of class names or class references.
• An array of class names or class references.

This single class name declaration declares the class only once and has no additional effect:

include base::linux

This example declares a single class with a class reference:

include Class['base::linux']

This example declares two classes in a list:

include base::linux, apache

This example declares two classes in an array:

$my_classes = ['base::linux', 'apache']
include $my_classes

The require function

The require function declares one or more classes, then causes them to become a dependency of the surrounding container. This function uses include-like behavior, so you can make multiple declarations, and Puppet relies on external data for parameters.

The require function accepts one of the following:

• A single class name, such as apache.
• A single class reference, such as Class['apache'].
• A comma-separated list of class names or class references.
• An array of class names or class references.

In this example, Puppet ensures that every resource in the apache class is applied before any resource in any apache::vhost instance:

define apache::vhost (Integer $port, String $docroot, String $servername, String $vhost_name) {
  require apache
  ...
}

The contain function

The contain function is used inside another class definition to declare one or more classes and contain those classes in the surrounding class. This enforces ordering of classes. When you contain a class in another class, the relationships of the containing class extend to the contained class as well. For details about containment, see the documentation on containing classes.

This function uses include-like behavior, so you can make multiple declarations, and Puppet relies on external data for parameters.

The contain function accepts one of the following:

• A single class name, such as apache.
• A single class reference, such as Class['apache'].
• A comma-separated list of class names or class references.
• An array of class names or class references.

In this example class declaration, the ntp class contains the ntp::service class. Any resource that forms a relationship with the ntp class also has the same relationship to the ntp::service class.

class ntp {
  file { '/etc/ntp.conf':
    ...
    require => Package['ntp'],
    notify  => Class['ntp::service'],
  }
  contain ntp::service
  package { 'ntp':
    ...
  }
}

For example, if a resource has a before relationship with the ntp class, that resource will also be applied before the ntp::service class. Similarly, any resource that forms a require relationship with ntp will be applied after ntp::service.

The hiera_include function

The legacy Hiera function hiera_include has been deprecated. In Hiera 5 and later, instead of using hiera_include use lookup with the include function. For example: use lookup('classes', {merge => unique}).include instead of hiera_include('classes').

Resource-like declarations

Resource-like class declarations require that you declare a given class only once. They allow you to override class parameters at compile time — for any parameters you don't override, Puppet falls back to external data.

Resource-like declarations must be unique to avoid conflicting parameter values. Repeated overrides cause catalog compilation to be unreliable and dependent on order evaluation. This is because overridden values from the class declaration:

• Always take precedence.
• Are computed at compile time.
• Do not have a built-in hierarchy for resolving conflicts.

When a class is declared with a resource-like declaration, Puppet takes the following actions, in order, for each of the class parameters:

1. Uses the override value from the declaration, if present.
2. Requests a value from the external data source, using the key <class name>::<parameter name>. For example, to get the apache class's version parameter, Puppet searches for apache::version.
3. Uses the default value.
4. Fails compilation with an error, if no value is found.

Resource-like declarations look like normal resource declarations, using the class pseudo-resource type. You can provide a value for any class parameter by specifying it as a resource attribute.

You can also specify a value for any metaparameter. In such cases, every resource contained in the class will also have that metaparameter. However:

• Any resource can specifically override metaparameter values received from its container.
• Metaparameters that can take more than one value, such as the relationships metaparameters, merge the values from the container and any resource-specific values.

• You cannot apply the noop metaparameter to resource-like class declarations.

For example, this resource-like declaration declares a class with no parameters:

class {'base::linux':}

This declaration declares a class and specifies the version parameter:

class {'apache':
  version => '2.2.21',
}

Related information

• Node definitions

• Main manifest directory

• Defined resource types

• Relationships and ordering

• Containment

• Resources

• Classifying nodes