Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 38 ยท Roles and Profiles

The Roles and Profiles Pattern

Learn the roles and profiles design pattern: component modules, profiles as technology stacks, roles as business machines, and why each node gets exactly one role.

When a Puppet codebase is small, you can write node 'web1' { include apache; include mysql } and move on. After a few dozen nodes the same classes are copied in many places, special cases pile up, and nobody knows which machine runs what. The roles and profiles pattern is the community's answer: a way to organize classes into three layers so that code is reusable and each node's job is stated in one place.

It is a convention, not a feature of the language. Puppet does not know what a role is; you create the structure with ordinary classes and good discipline. The commands and files in this lesson are read-only examples; the runnable blocks are JavaScript stand-ins that model how classes include each other.

The three layers

Layer What it is Example
Component modules Generic, reusable modules that manage one technology apache, postgresql, ntp (often from the Forge)
Profiles Your site's way of configuring one technology stack, built from component modules profile::webserver, profile::database
Roles The business purpose of a machine, built only from profiles role::shop_frontend, role::reporting_db

Think of it like cooking. Component modules are ingredients, profiles are prepared dishes, and a role is the whole meal you serve to a customer.

flowchart TB
  N["Node: web1.example.com"] --> R["role::shop_frontend"]
  R --> P1["profile::base"]
  R --> P2["profile::webserver"]
  R --> P3["profile::app_runtime"]
  P2 --> C1["apache"]
  P3 --> C2["nodejs"]
  P1 --> C3["ntp"]
  P1 --> C4["accounts"]

One node, one role, several profiles, many component modules.

Profiles: technology stacks

A profile is an ordinary class in a module called profile. It declares (usually with include or a resource-like declaration) the component modules it needs and adds the site-specific choices:

PUPPET
# profile/manifests/webserver.pp
class profile::webserver (
  Integer $port = 80,
  Array[String] $vhosts = [],
) {
  class { 'apache':
    default_vhost => false,
  }

  $vhosts.each |$name| {
    apache::vhost { $name:
      port    => $port,
      docroot => "/var/www/${name}",
    }
  }
}

A good profile is about one technology stack: web server, database, monitoring agent. It wraps component modules, makes decisions, and reads data from Hiera through its parameters. It contains no node names and no if $hostname == ... branches.

Roles: business machines

A role says what a machine is. It contains nothing but include lines of profiles:

PUPPET
# role/manifests/shop_frontend.pp
class role::shop_frontend {
  include profile::base
  include profile::webserver
  include profile::app_runtime
}

Two rules keep roles healthy:

  1. A node gets exactly one role. A machine that is both a web server and a database is a new role (role::all_in_one), not two roles at once. This keeps the question "what is this machine?" answerable.
  2. Roles contain no parameters and no logic. If you need to vary behavior, vary the data in Hiera for the profiles, not the role.

You classify a node by assigning its role. In a simple setup that is in site.pp:

PUPPET
node /^web\d+\./ {
  include role::shop_frontend
}

node default {
  include role::minimal
}

Better still, let an ENC or a Hiera lookup choose the role. See Node Classification.

Why bother? Three benefits

  • Reuse without copy-paste. profile::base is used by every role; improving it improves every node.
  • A clear answer to "who runs what?" Open one role file and you see the machine's whole definition.
  • Safe change. Profiles are your own wrapper around public modules. When the apache module releases a breaking change, you adapt in the profile and the roles do not move.

A simple model in code

This stand-in models the pattern with plain objects: roles list profiles, profiles list component modules, and a function resolves the full set of classes a node gets. It lets you check the "one role per node" rule and see duplicates.

JS Stand-in: resolve a node's class tree

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

No output.

The node odd1 violates the rule. In a real codebase you would catch this in a test, see RSpec-puppet Unit Tests.

JS Stand-in: audit that roles only include profiles

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

No output.

Where do the files go?

In a typical control repository, role and profile are two modules in the site-modules/ directory next to modules/ (which holds Forge modules). Keeping them apart from third-party code makes it obvious which code is yours and keeps deployment simple. You will meet that layout again in R10k and the Control Repo.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What may a role class contain?

    A role only lists profiles. Anything else belongs in a profile or in Hiera data.
  2. 2. How many roles should one node have?

    One role per node keeps the machine's purpose unambiguous. Combine duties by making a new role.
  3. 3. Which layer wraps a component module like apache with your site's settings?

    Profiles configure technology stacks using component modules.
  4. 4. A new major version of a Forge module breaks your parameters. Where is the cheapest place to fix it?

    Profiles isolate component modules, so the change is made once.

Summary

  • Three layers: component modules (technology), profiles (your stack), roles (business purpose).
  • A role only includes profiles; a node has exactly one role.
  • Profiles contain logic and take their data from Hiera through parameters.
  • The pattern is a convention you enforce with review and tests.
  • Keep role and profile modules in your own site-modules/ directory.

Next: Profiles with Hiera and Parameters