Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท Roles and Profiles

Roles and Profiles Anti-patterns

Spot and fix common mistakes in roles and profiles code: fat roles, node-name logic, hard-coded data, profile chains, class dependency tangles and over-parameterized wrappers.

The roles and profiles pattern is simple on paper, and codebases still drift away from it. A role grows an if statement; a profile hard-codes an IP address; ten profiles depend on each other in a chain that nobody dares to touch. This lesson lists the anti-patterns that show up again and again, explains why each one hurts, and gives the refactoring.

Use it as a review checklist. The stand-ins at the end are a small linter written in JavaScript that finds three of these mistakes in text. It is a teaching model, not a replacement for puppet-lint and code review.

1. The fat role

A role that contains resources, parameters or conditionals has stopped being a role:

PUPPET
class role::shop_frontend {
  include profile::base
  package { 'git': ensure => installed }          # resource in a role
  if $facts['networking']['hostname'] == 'web1' {  # node name logic
    include profile::debug_tools
  }
}

Why it hurts. Roles are meant to be the readable list of what a machine is. Once logic leaks in, the list lies. Fix: move the resource into a profile (profile::base or a new one) and move the per-node difference into Hiera data, for example a boolean profile::debug_tools::enabled set only for web1.

2. Node names inside profiles

if $trusted['certname'] == 'db1.example.com' { ... } ties generic code to one machine. It cannot be tested without that name, and it breaks when the machine is renamed. Fix: use a parameter with a safe default and let the hierarchy set it for the specific node.

3. Hard-coded data

IP addresses, URLs, ports, passwords and package versions inside a manifest mean a code change for every data change, and the same profile cannot serve two environments.

PUPPET
class profile::app {
  $db = '10.0.4.17'                  # wrong: data in code
  # ...
}

Fix: a class parameter, filled from Hiera: String $db_host. Defaults should be safe, not environment-specific.

4. Profile chains and hidden dependencies

profile::a includes profile::b, which includes profile::c which needs profile::a's file to exist. The order of evaluation becomes a puzzle, and removing one profile breaks others for no visible reason.

flowchart LR
  A["profile::app"] --> B["profile::proxy"]
  B --> C["profile::certs"]
  C --> A

A dependency cycle: Puppet reports it, but the real fix is design.

Fix: profiles should be independent peers that roles combine. If two profiles share something, extract it into a third profile (profile::base) or a component module they both use. Express order with require, before or -> on resources, and only where it is real.

5. Role inheritance and composition tricks

Making role::b inherit from role::a, or adding a role as a profile of another role, brings back everything the pattern was invented to avoid. Fix: a new role that includes the shared profiles. Duplicated include lines are cheap; clever inheritance is expensive.

6. Parameter explosion

A wrapper profile that copies every parameter of a component module (forty of them) adds no value and forces you to edit it for each new upstream option. Fix: expose only the few settings your site varies. Pass the rest through Hiera data to the component module directly, for example apache::default_vhost: false, because component classes are also looked up through automatic parameter binding.

7. Resource-like declarations in many places

class { 'apache': ... } can appear once per catalog. If two profiles declare it that way, compilation fails with a duplicate declaration error. Fix: only one profile owns each component module and declares it with parameters, or every profile uses include and the values come from Hiera.

8. Using facts for access control

Giving a node secrets because its self-reported fact says role=database. Fix: classification on certname or trusted data, covered in Node Classification.

9. Untested, undocumented profiles

A profile with no tests and no README is a risk every time somebody touches it. Fix: at least a compile test per role (see RSpec-puppet) and a documented list of parameters using Puppet Strings comments.

Checklist for a review

Question Expected answer
Does the role contain only include profile::... lines? Yes
Does any class mention a literal node name? No
Are all addresses, versions and credentials parameters? Yes
Can each profile be included alone and compile? Yes
Does a role compile for every supported OS in tests? Yes

Stand-in linter

The first stand-in scans text for a role with non-include lines, a profile mentioning a node name and hard-coded IP addresses. The second builds a dependency graph from include lines and detects a cycle. Both are JavaScript stand-ins for ideas you apply by reading code.

JS Stand-in: a tiny anti-pattern linter

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

No output.

JS Stand-in: detect a profile dependency cycle

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A role contains a package resource. What is the best fix?

    Roles only list profiles. Resources belong in profiles (or component modules).
  2. 2. Why is if $trusted['certname'] == 'db1.example.com' inside a profile a problem?

    Node-specific differences belong in the data hierarchy, not in code.
  3. 3. Two profiles both write class { 'apache': ... }. What happens?

    A resource-like class declaration may appear only once; use include plus Hiera data for shared classes.
  4. 4. How should two profiles that need the same helper share it?

    Independent profiles combined by roles avoid chains and cycles.

Summary

  • Keep roles as plain lists of profiles, one role per node.
  • Never put node names or literal data into profiles; use parameters and Hiera.
  • Avoid profile chains, role inheritance and wrappers that copy every upstream parameter.
  • Declare a component class in exactly one place.
  • Review with a checklist and cover each role with a compile test.

Next: Puppet Lint and Parser Validate