Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 38 ยท Classes, Modules and Hiera

Classes and Parameters

Group resources into Puppet classes, declare them with include or resource-like syntax, add typed parameters with defaults, and understand automatic data binding and contain.

So far you declared resources one by one. A class gives a name to a group of resources that belong together, such as everything needed for Nginx. You define a class once and then apply it to as many nodes as you like. Classes are the main unit of reuse in Puppet, and they are the place where parameters let you customise behaviour without editing code.

Defining and declaring

Defining a class only makes it available. It does nothing until it is declared.

PUPPET
class nginx {
  package { 'nginx':
    ensure => installed,
  }
  service { 'nginx':
    ensure  => running,
    enable  => true,
    require => Package['nginx'],
  }
}

The class nginx must live in a file named init.pp of a module called nginx (Modules). Then declare it where you want it to apply, for example in site.pp:

PUPPET
node 'web1.example.test' {
  include nginx
}

Class names use lowercase letters, digits and underscores, with :: as a namespace separator (nginx::config).

include versus resource-like declaration

There are two ways to declare a class.

PUPPET
include nginx                  # 1. include-like

class { 'nginx':               # 2. resource-like
  port => 8080,
}

include can be repeated anywhere, any number of times: a class is only applied once however many places include it. That makes include safe when several parts of the code need the same class. The resource-like form lets you pass parameters, but it can be declared only once and must happen before any include of that class in the compile, or you get a duplicate declaration error. That fragility is why modern code sets parameters from Hiera and uses only include everywhere.

include foo class { 'foo': ... }
Repeat safely Yes No (duplicate error)
Pass parameters inline No Yes
Use with Hiera data Yes (automatic lookup) Yes
Recommended Default choice Rarely, for one-off overrides

Related declaration functions: require nginx (declare and order before the caller) and contain nginx (declare and make part of the caller for ordering; see Relationships).

Parameters

Parameters make a class configurable. Give each one a data type and, usually, a default:

PUPPET
class nginx (
  String            $package = 'nginx',
  Integer[1, 65535] $port    = 80,
  Boolean           $manage_service = true,
  Optional[String]  $ssl_cert = undef,
) {
  package { $package: ensure => installed }

  file { '/etc/nginx/conf.d/default.conf':
    ensure  => file,
    content => "server { listen ${port}; }\n",
    require => Package[$package],
    notify  => Service['nginx'],
  }

  if $manage_service {
    service { 'nginx':
      ensure => running,
      enable => true,
    }
  }
}

A parameter without a default is required: a catalog that does not provide a value fails with an error that names the class and the missing parameter. Types catch mistakes early: a port of 70000 or 'eighty' stops the compile.

Inside the class the parameter is an ordinary variable, readable as $port. From outside, other code can read it as $nginx::port (after the class is evaluated).

Automatic parameter lookup (data binding)

When you include nginx, Puppet looks for a value for each parameter in Hiera under the key nginx::<parameter>, such as nginx::port. If found, that value is used; otherwise the default in the class applies. In a Hiera data file:

YAML
# data/common.yaml
nginx::port: 8080
nginx::ssl_cert: /etc/ssl/certs/site.pem

The lookup order is: an explicit value in a resource-like declaration, then Hiera, then the default. This is called automatic parameter lookup, and it is how the same class behaves differently per environment or node without code changes. The next lessons and Hiera explore it.

Inheritance and class design

Puppet classes support inherits:

PUPPET
class nginx::custom inherits nginx {
  File['/etc/nginx/conf.d/default.conf'] {
    content => "server { listen 9000; }\n",
  }
}

This overrides one attribute of a resource in the parent class. In practice, avoid inheritance; the style guidance is to use it only for the params pattern of older modules. Prefer parameters, Hiera data, and composition (a class including other classes).

Good class design rules:

  • One class, one job. nginx installs, nginx::config writes configuration, nginx::service runs it.
  • Expose a few parameters; put big structured data in a hash parameter.
  • Do not look up other classes' variables. Pass values in.
  • Name parameters for what they mean (port), not how they are used.

Stand-in: parameters and data binding

Python Stand-in: automatic parameter lookup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: parameter type checking

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Defining a class does what?

    A class must be declared (include, class {}) to take effect.
  2. 2. Why is include preferred over class { ... }?

    Resource-like declarations may appear only once; include is idempotent.
  3. 3. Where does automatic parameter lookup look in Hiera for nginx's port?

    Keys are <class>::<parameter>.
  4. 4. What happens when a parameter has no default and no data is found?

    Required parameters must be supplied.

Summary

  • A class groups resources; define it in a module, declare it with include (preferred) or resource-like syntax.
  • Parameters carry types and defaults; no default means required.
  • Automatic lookup binds class::param from Hiera, falling back to defaults.
  • Prefer composition and data over inheritance; use contain for ordering nested classes.

Next: Defined Types