Module fundamentals

You'll keep nearly all of your Puppet code in modules. Each module manages a specific task in your infrastructure, such as installing and configuring a piece of software. Modules serve as the basic building blocks of Puppet and are reusable and shareable.

Modules contain Puppet classes, defined types, tasks, task plans, functions, resource types and providers, and plug-ins such as custom types or facts. Modules must be installed in the Puppet modulepath. Puppet loads all content from every module in the modulepath, making this code available for use.

You can download and install modules from the Puppet Forge. The Forge contains thousands of modules written by Puppet developers and the open source community for a wide variety of use cases. You should also expect to write at least a few of your own modules to meet specific needs in your infrastructure.

If you're using Code Manager or r10k, you'll manage modules with a Puppetfile. For smaller, manually managed infrastructures or proof of concept projects, you can install and manage modules with the puppet module command. See the related topic about installing modules for details.

Module structure

Modules have a specific directory structure that allows Puppet to find and load classes, defined types, facts, custom types and providers, functions, and tasks.

Each module subdirectory has a specific function. Not all directories are required, but if used, they should be in the following structure.

data/
Contains data files specifying parameter defaults.
examples/
Contains examples showing how to declare the module's classes and defined types.
init.pp: The main class of the module.
example.pp: Provide examples for major use cases.
facts.d/
Contains external facts, which are an alternative to Ruby-based custom facts. These are synced to all agent nodes, so they can submit values for those facts to the Puppet master.
files/
Contains static files, which managed nodes can download.
service.conf
This file's source => URL is puppet:///modules/my_module/service.conf. Its contents can also be accessed with the file function, such as content => file('my_module/service.conf').
functions/
Contains custom functions written in the Puppet language.
lib/
Contains plug-ins, such as custom facts and custom resource types. These are used by both the Puppet master and the Puppet agent, and they are synced to all agent nodes in the environment on each Puppet run.
facter/
Contains custom facts, written in Ruby.
puppet/
Contains custom functions, resource types, and resource providers:
puppet/functions/: Contains functions written in Ruby for the modern Puppet::Functions API.
puppet/parser/functions/: Contains functions written in Ruby for the legacy Puppet::Parser::Functions API.
puppet/provider/: Contains custom resource providers written in the Puppet language.
puppet/type/: Contains custom resource types written in the Puppet language.
locales/
Contains files relating to module localization into languages other than English.
manifests/
Contains all of the manifests in the module.
init.pp
The init.pp class, if used, is the main class of the module. This class's name must match the module's name.
other_class.pp
Classes and defined types are named with the namespace of the module and the name of the class or defined type. For example, this class is named my_module::other_class.
implementation/
You can group related classes and defined types in subdirectories of the manifests/ directory. The name of this subdirectory is reflected in the names of the classes and types it contains. Classes and defined types are named with the namespace of the module, any subdirectories, and the name of the class or defined type.
implementation/my_defined_type.pp: This defined type is named my_module::implementation::my_defined_type.
implementation/class.pp: This defined type is named my_module::implementation::class.
readmes/
The module's README localized into languages other than English.
spec/
Contains spec tests for any plug-ins in the lib directory.
tasks/
Contains Puppet tasks, which can be written in any programming language that can be read by the target node.
templates/
Contains templates, which the module's manifests can use to generate content or variable values.
component.erb
A manifest can render this template with template('my_module/component.erb').
component.epp
A manifest can render this template with epp('my_module/component.epp').
types/
Contains resource type aliases.

Module names

Module names should contain only lowercase letters, numbers, and underscores, and should begin with a lowercase letter. That is, module names should match the expression: [a-z][a-z0-9_]*

These restrictions are similar to those that apply to class names, with the added restriction that module names cannot contain the namespace separator (::), because modules cannot be nested. Certain module names are disallowed; see the list of reserved words and names.

Manifests

Manifests, contained in the module's manifests/ folder, each contain one class or defined type.

The init.pp manifest is the main class of a module and, unlike other classes or defined types, it is referred to only by the name of the module itself. For example, the class in init.pp in the puppetlabs-motd module is the motd class. You cannot name a class init.

All other classes or defined types names are composed of name segments, separated from each other by a namespace separator, ::

  • The module short name, followed by the namespace separator.

  • Any manifests/ subdirectories that the class or defined type is contained in, followed by a namespace separato.

  • The manifest file name, without the extension.

For example, each module class or defined type would have the following names based on their module name and location within the manifests/ directory:

Module name Filepath to class or defined type Class or defined type name
username-my_module my_module/manifests/init.pp my_module
username-my_module my_module/manifests/other_class.pp my_module::other_class
puppetlabs-apache apache/manifests/security/rule_link.pp apache::security::rule_link
puppetlabs-apache apache/manifests/fastcgi/server.pp apache::fastcgi::server 

Files in modules

You can serve files from a module's files/ directory to agent nodes.

Download files to the agent by setting the file resource's source attribute to the puppet:/// URL for the file. Alternately, you can access module files with the file function.

To download the file with a URL, use the following format for the puppet:/// URL:
puppet:///<MODULE_DIRECTORY>/<MODULE_NAME>/<FILE_NAME>
For example, given a file located in my_module/files/service.conf, the URL is: 
puppet:///modules/my_module/service.conf
To access files with the file function, pass the reference <MODULE NAME>/<FILE NAME> to the function, which will return the content of the requested file from the module's files/ directory. Puppet URLs work for both puppet agent and puppet apply; in either case they retrieve the file from a module.

To learn more about the file function, see the function reference.

Templates in modules

You can use ERB or EPP templates in your module to manage the content of configuration files. Templates combine code, data, and literal text to produce a string output, which can be used as the content attribute of a file resource or as a variable value. Templates are contained in the module's templates/ directory.

For ERB templates, which use Ruby, use the template function. For EPP templates, which use the Puppet language, use the epp function. See the page about templates for detailed information.

The template and epp functions look up templates identified by module and template name, passed as a string in parentheses: function('module_name/template_name.extension'). For example:
template('my_module/component.erb')
epp('my_module/component.epp')

Writing modules

Every Puppet user should expect to write at least some of their own modules. You must give your modules a specific directory structure and include correctly formatted metadata. Puppet Development Kit (PDK) provides tools for writing, validating, and testing modules.

PDK creates a complete module structure, class, defined type, and task templates, and configures a module testing framework. To test your modules, use PDK commands to run unit tests and to validate your module's metadata, syntax, and style. You can download and install PDK on any development machine; no Puppet installation is required. See the PDK documentation to get started.

The puppet module generate command is deprecated and will be removed in a future version of Puppet. For help getting started writing modules, see our beginner's guide to writing modules. For details on best practices and code style, see the Puppet Language style guide.