Defining classes

Create a class by writing a class definition in a manifest (.pp) file. Store class manifests in the manifests/ directory of a module. Define only one class in a manifest, and give the manifest file the same name as the class. Puppet automatically loads any classes that are present in a valid module. See module fundamentals to learn more about module structure and usage.

A class contains all of its resources. This means any relationships formed with the class as a whole is extended to every resource in the class. Every resource in a class gets automatically tagged with the class’s name and each of its namespace segments.

Classes can contain other classes, but you must use the contain function to explicitly specify when a class is contained. For more information, see the documentation about containing classes. A contained class is automatically tagged with the name of its container.

The general form of a class definition is:

• The class keyword.
• The name of the class.
• An optional parameter list, which consists of:
  • An opening parenthesis.
  • A comma-separated list of parameters, such asString $myparam = "value". Each parameter consists of:
    • An optional data type, which restricts the allowed values for the parameter. If not specified, the data type defaults to Any.
    • A variable name to represent the parameter, including the dollar sign ($) prefix
    • An optional equals sign (=) and default value, which must match the data type, if one was specified.
  • An optional trailing comma after the last parameter.
  • A closing parenthesis.
• Optionally, the inherits keyword followed by a single class name.
• An opening curly brace.
• A block of arbitrary Puppet code, which generally contains at least one resource declaration.
• A closing curly brace.

For example, this class definition specifies no parameters:

class base::linux {
  file { '/etc/passwd':
    owner => 'root',
    group => 'root',
    mode  => '0644',
  }
  file { '/etc/shadow':
    owner => 'root',
    group => 'root',
    mode  => '0440',
  }
}

This class definition creates a version parameter ($version) that accepts a String data type with a default value of 'latest'. It also includes file content from an embedded Ruby (ERB) template from the apache module.

class apache (String $version = 'latest') {
  package {'httpd':
    ensure => $version, # Using the version parameter from above
    before => File['/etc/httpd.conf'],
  }
  file {'/etc/httpd.conf':
    ensure  => file,
    owner   => 'httpd',
    content => template('apache/httpd.conf.erb'), # Template from a module
  }
  service {'httpd':
    ensure    => running,
    enable    => true,
    subscribe => File['/etc/httpd.conf'],
  }
}

Class parameters and variables

Parameters allow a class to request external data. If a class needs to use data other than facts for configuration, use a parameter for that data.

You can use class parameters as normal variables inside the class definition. The values of these variables are set based on user input when the class is declared, rather than with normal assignment statements.

Supply default values for parameters whenever possible. If a class parameter lacks a default value, the parameter is considered required and the user must set a value, either in external data or as an override.

If you set a data type for each parameter, Puppet checks the parameter's value at runtime to make sure that it is the correct data type, and raises an error if the value is illegal. If you do not provide a data type for a parameter, the parameter accepts values of any data type.

The variables $title and $name are both set to the class name automatically, so you can't use them as parameters.

Setting class parameter defaults with Hiera data

To set class parameter defaults with Hiera data in your modules, set up a hierarchy in your module's hiera.yaml file and include the referenced data files in the data directory.

For example, this hiera.yaml file, located in the root directory of the ntp module, uses the operating system fact to determine which class defaults to apply to the target system. Puppet first looks for a data file that matches the operating system of the target system: path: "os/%{facts.os.family}.yaml". If no matching path is found, Puppet uses defaults from the "common" data file instead.

# ntp/hiera.yaml
---
version: 5
defaults:
  datadir: data
  data_hash: yaml_data
hierarchy:
  - name: "OS family"
    path: "os/%{facts.os.family}.yaml"

  - name: "common"
    path: "common.yaml"

The files in the example below specify the default values are located in the data directory:

• Debian.yaml specifies the defaults for systems that return an operating system fact of Debian.
• common.yaml specifies the defaults for all other systems.

# ntp/data/common.yaml
---
ntp::autoupdate: false
ntp::service_name: ntpd

# ntp/data/os/Debian.yaml
ntp::service_name: ntp