Defining and declaring classes

A Puppet class can be considered to be a container for resources. It is defined once and selected by all nodes that need to make use of the prepared functionality. Each class represents a well-known subset of a system's configuration.

For example, a classic use case is a class that installs the Apache web server and applies some basic settings. This class will look like the following:

class apache {
  package { 'apache2':
    ensure => 'installed',
  }
  file { '/etc/apache2/apache2.conf':
    ensure => 'file',
    source =>
      'puppet:///modules/apache/etc/apache2/apache2.conf', 
    require => Package['apache2'], 
  } 
  service { 'apache2': 
    enable    => true, 
    subscribe => File['/etc/apache2/apache2.conf', 
  } 
} 

All web server nodes will make use of this class. To this end, their manifests need to contain a simple statement:

include apache

This is referred to as including a class, or declaring it. If your apache class is powerful enough to do all that is needed, this line might fully comprise a node block's content:

node 'webserver01' {
  include apache
}

This already concludes our tour of classes in a nutshell. There is yet some more to discuss, of course, but let's take a look at defined types before that.

Creating and using defined types

A defined type can be imagined like a blueprint for a piece of manifest. Like a class, it mainly consists of a body of the manifest code. However, a defined type takes arguments and makes their values available in its body as local variables.

Here is another typical example of a defined type, the Apache virtual host configuration:

define virtual_host(
  String $content,
  String[3,3] $priority = '050'
) {
  file { "/etc/apache2/sites-available/${name}":
    ensure  => 'file',
    owner   => 'root',
    group   => 'root',
    mode    => '0644',
    content => $content
  }
  file { "/etc/apache2/sites-enabled/${priority}-${name}": 
    ensure => 'link', 
    target => "../sites-available/${name}";
  }
}

This code might still seem pretty cryptic. It will get clearer in the context of how it is actually used from other places in your manifest; the following code shows you how:

virtual_host { 'example.net': 
  content => file('apache/vhosts/example.net') 
}
virtual_host{ 'fallback': 
  priority => '999', 
  content  => file('apache/vhosts/fallback') 
} 

This is why the construct is called a defined type—you can now place what appear to be resources in your manifest, but you really call your own manifest code construct.

virtual_host {
  'example.net':
    content  => 'foo';
  'fallback':
    priority => '999',
    content  => ...,
}

The virtual_host type takes two arguments: the content argument is mandatory and is used verbatim in the configuration file resource. Puppet will synchronize that file's content to what is specified in the manifest. The priority argument is optional and its value becomes the file name prefix. If omitted, the respective virtual host definition uses the default priority of 050.

Both parameters of this example type are of the String type. For details about Puppet's variable type system, see Chapter 7, New Features from Puppet 4. It suffices to say that you can restrict parameters to certain value types. This is optional, however. You can omit the type name, and Puppet will accept any value for the parameter in question.

Also, each defined type can implicitly refer to the name (or title) by which it was called. In other words, each instance of your define gets a name, and you can access it through the $name or $title variable.

Understanding and leveraging the differences

The respective purposes of Puppet's class and defined type are very specific and they usually don't overlap.

The class declares resources and properties that are in some way centric to the system. A class is a finalized description of one or sometimes more aspects of your system as a whole. Whatever the class represents, it can only ever exist in one form; to Puppet, each class is implicitly a singleton, a fixed set of information that either applies to your system (the class is included), or not.

The typical resources you will encapsulate in a class for convenient inclusion in a manifest are as follows:

The define is used for all things that exist in multiple instances. All aspects that appear in varying quantities in your system can possibly be modeled using this language construct. In this regard, the define is very similar to the full-fledged resource it mimics with its declaration syntax. Some of the typical contents of defined types are:

The class's singleton nature is especially valuable because it prevents clashes in the form of multiple resource declarations. Remember that each resource must be unique to a catalog. For example, consider a second declaration of the Apache package:

package { 'apache2': }

This declaration can be anywhere in the manifest of one of your web servers (say, right in the node block, next to include apache); this additional declaration will prevent the successful compilation of a catalog.

The virtue of the class is that there can be an arbitrary number of include statements for the same class strewn throughout the manifest. Puppet will commit the class's contents to the catalog exactly once.

virtual_host { 'wordpress': 
  content  => file(...), 
  priority => '011', 
}
virtual_host { 'wordpress': 
  content  => '# Dummy vhost', 
  priority => '600', 
}