Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 38 ยท Classes, Modules and Hiera

Module Structure and the Puppet Forge

Organise Puppet code into modules: directory layout, autoloading names, files, templates, metadata.json, installing from the Puppet Forge, and writing a first small module.

A module is the unit for sharing Puppet code. It is a directory with a fixed layout that holds classes, defined types, files, templates, facts and functions for one purpose, such as "manage Nginx". Puppet finds the things inside a module by name, with no import statements: the layout is the interface.

The layout

TEXT
nginx/                       # module name must match: nginx
  manifests/
    init.pp                  # class nginx
    config.pp                # class nginx::config
    vhost.pp                 # define nginx::vhost
  files/
    mime.types               # source => 'puppet:///modules/nginx/mime.types'
  templates/
    nginx.conf.epp           # epp('nginx/nginx.conf.epp', {...})
    vhost.conf.erb           # template('nginx/vhost.conf.erb')
  lib/
    facter/                  # custom facts (Ruby)
    puppet/                  # custom types, providers, functions
  functions/                 # functions written in the Puppet language
  types/                     # type aliases, e.g. nginx::port.pp
  data/                      # module-level Hiera data
  hiera.yaml                 # module-level Hiera config
  examples/                  # sample manifests
  spec/                      # tests
  metadata.json              # name, version, dependencies
  README.md

The naming rule (autoloading)

Puppet maps a name to a file:

Name File
class nginx nginx/manifests/init.pp
class nginx::config nginx/manifests/config.pp
class nginx::config::ssl nginx/manifests/config/ssl.pp
define nginx::vhost nginx/manifests/vhost.pp

If the name does not match the file path, Puppet cannot find it and you get "Could not find class". The module directory name must be the module name only (not puppet-nginx or nginx-main).

Files and templates

  • files/ holds static files. Reference them with source => 'puppet:///modules/<module>/<path>' (the files folder is implicit).
  • templates/ holds templates (EPP or ERB) rendered with variables. They are rendered on the server and the result becomes the file's content. The Facts and Templates chapter shows this in depth.
PUPPET
file { '/etc/nginx/mime.types':
  source => 'puppet:///modules/nginx/mime.types',
}

metadata.json

JSON
{
  "name": "myorg-nginx",
  "version": "1.2.0",
  "author": "My Org",
  "summary": "Installs and configures Nginx",
  "license": "Apache-2.0",
  "source": "https://git.example.test/puppet/nginx",
  "dependencies": [
    { "name": "puppetlabs/stdlib", "version_requirement": ">= 9.0.0 < 10.0.0" }
  ],
  "operatingsystem_support": [
    { "operatingsystem": "Ubuntu", "operatingsystemrelease": ["22.04", "24.04"] }
  ],
  "requirements": [
    { "name": "puppet", "version_requirement": ">= 7.0.0 < 9.0.0" }
  ]
}

On the Forge a module's full name is author-name (puppetlabs-stdlib); on disk the directory is just stdlib. The version follows semantic versioning: major (breaking), minor (features), patch (fixes). Declare dependencies with version ranges.

The Puppet Forge

The Puppet Forge (forge.puppet.com) is the public catalogue of modules. Modules marked Supported or Approved by the vendor are reviewed and a good starting point (examples: puppetlabs-stdlib, puppetlabs-apt, puppetlabs-concat, puppetlabs-firewall, puppetlabs-postgresql). Always check the module's date of last release, open issues and which operating systems it supports.

Installing by hand for a quick try:

Terminal
puppet module install puppetlabs-stdlib --version 9.6.0
puppet module list
puppet module uninstall puppetlabs-stdlib

For real projects do not use puppet module install. Declare modules in a Puppetfile and let r10k or Code Manager install the exact versions, so each environment is reproducible (covered in the Testing and Code Management chapter):

Ruby
# Puppetfile
forge 'https://forge.puppet.com'

mod 'puppetlabs-stdlib', '9.6.0'
mod 'puppetlabs-apt',    '9.4.0'
mod 'myorg-nginx',
  git: 'https://git.example.test/puppet/nginx.git',
  tag: 'v1.2.0'

A first small module

Terminal
puppet module generate --skip-interview myorg-motd

(or pdk new module motd with the Puppet Development Kit). Then add manifests/init.pp:

PUPPET
# @summary Manage the message of the day.
# @param message Text shown at login.
class motd (
  String $message = 'Managed by Puppet',
) {
  file { '/etc/motd':
    ensure  => file,
    content => "${message}\n",
  }
}

The # @summary and # @param comments are Puppet Strings documentation, which can be turned into HTML or Markdown reference pages with puppet strings generate. Use it on every public class.

Stand-in: name-to-file resolution

Python Stand-in: where does Puppet look?

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: check a module's layout

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. In which file is class nginx::config defined?

    The class name maps to manifests/<last part>.pp.
  2. 2. Where does puppet:///modules/nginx/mime.types point?

    The files directory is implicit in puppet:/// URLs.
  3. 3. Which file lists a module's name, version and dependencies?

    metadata.json holds module metadata.
  4. 4. What is the recommended way to manage module versions per environment?

    A Puppetfile pins exact versions so environments are reproducible.

Summary

  • A module is a folder with manifests/, files/, templates/, lib/, data/, metadata.json.
  • Names map to files: nginx is init.pp, nginx::config is config.pp.
  • puppet:///modules/<name>/<path> reads from the module's files/.
  • Use the Forge for shared modules and a Puppetfile to pin versions.
  • Document with Puppet Strings comments.

Next: Hiera: Data Separated from Code