Learn Puppet - Classes, Modules & Roles/Profiles

#Introduction

In the previous episode 4, you wrote manifests and got to know resource types — package, service, file, exec, user, group, and cron — and tested them with puppet apply. The problem is that a single manifest won't survive as your configuration grows: you'll repeat the same resources across many files and struggle to apply them to many nodes. Episode 5 answers this problem with three concepts: classes to group resources, modules to package them, and the Roles/Profiles pattern to keep the architecture clean.

#Classes: Naming Collections of Resources

A class is a named collection of resources that can be reused. Define it once with class, then apply it anywhere with include.

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

To apply the class to a node, call it with include:

include profile::nginx

include is idempotent — calling it multiple times doesn't cause resources to be declared twice, as long as all the classes called handle different resources.

#Parametrized Classes

Classes can accept parameters so one definition serves many variations. Parameters are given default values so they remain safe to call without arguments.

class profile::nginx (
  String $listen_port = 80,
  Boolean $enable_ssl = false,
) {
  package { 'nginx':
    ensure => installed,
  }
 
  service { 'nginx':
    ensure => running,
    enable => true,
    require => Package['nginx'],
  }
 
  file { '/etc/nginx/conf.d/server.conf':
    ensure  => file,
    content => "listen ${listen_port};\nssl ${enable_ssl};\n",
    require => Package['nginx'],
    notify  => Service['nginx'],
  }
}

When using it, call it with the desired values:

class { 'profile::nginx':
  listen_port => 8443,
  enable_ssl  => true,
}

#Modules: Packaging Configuration

Scattered manifests get hard to manage. Puppet solves this with modules — structured packages that contain manifests, templates, files, and data. Modules are Puppet's distribution and versioning unit; you can download them from Puppet Forge or write your own.

#Module Structure

nginx/
├── manifests/
│   ├── init.pp          # nginx class
│   └── service.pp       # nginx::service class
├── templates/
│   └── server.conf.epp  # config template
├── files/
│   └── index.html       # static file
├── hieradata/
│   └── common.yaml      # Hiera data
├── examples/
│   ├── init.pp
├── spec/
│   └── ...              # unit tests
├── metadata.json        # description & dependency
└── README.md

An important naming rule: the init.pp file inside the nginx module defines the nginx class, and the service.pp file defines nginx::service.

#Building Modules with PDK

PDK, which we installed in episode 0, provides automatic scaffolding:

pdk new module profile --template-url=https://github.com/puppetlabs/pdk-templates
cd profile
pdk new class nginx

As a result, the manifests/init.pp and manifests/nginx.pp files are ready to fill in. PDK also provides pdk validate and pdk test to make sure the code is valid and passes unit tests.

#The Roles/Profiles Pattern

As infrastructure grows, the class hierarchy easily becomes messy — classes merge with business data, and changing one part risks breaking another. The Roles/Profiles pattern splits that layer into two:

• Profile — the technical layer: classes that describe how a technology is installed and configured, for example profile::nginx or profile::postgresql. This is where all resources and technical details live.
• Role — the business layer: classes that compose profiles to define a node's role, for example role::web or role::database. Roles contain no resources — they only include several profiles.

class profile::nginx (
  Integer $worker_processes = 4,
) {
  package { 'nginx':
    ensure => installed,
  }
 
  service { 'nginx':
    ensure => running,
    enable => true,
    require => Package['nginx'],
  }
}

class role::web {
  include profile::base
  include profile::nginx
  include profile::firewall
}

Notice: role::web doesn't know how nginx is installed — it only knows that a web node needs the nginx, base, and firewall profiles. You can swap profile::nginx for another implementation without changing the role.

This pattern is fully supported by node classification: a node is assigned one role, and that role brings in all the profiles it needs. We'll connect everything with Hiera and node classification in the following episodes.

#Conclusion

In this episode 5 you leveled up from single manifests to module architecture: defining reusable classes, writing parametrized classes for flexibility, understanding the complete module structure (manifests, templates, files, hieradata), building modules via PDK, and applying the Roles/Profiles pattern that separates the technical layer from the business layer.

Key takeaways:

• A class names a collection of resources; include uses them idempotently.
• A parametrized class separates configuration from implementation — one class, many variations.
• A module packages manifests, templates, files, and data; init.pp determines the main class name.
• PDK provides scaffolding, pdk validate, and pdk test.
• Roles/Profiles: profiles are technical, roles only include profiles — keep the layers clean.

In the next episode, episode 6, we'll cover Hiera: data-driven configuration — separating data from logic with a hierarchical database, understanding the hiera.yaml structure, automatic class parameter lookup, and practical application for dev, staging, and production environments. See you in the next episode!