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.
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.
- Contains data files specifying parameter defaults.
- 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.
- 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.
- Contains static files, which managed nodes can download.
- This file's
source => URLis
puppet:///modules/my_module/service.conf. Its contents can also be accessed with the
filefunction, such as
content => file('my_module/service.conf').
- Contains custom functions written in the Puppet language.
- 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.
- Contains custom facts, written in Ruby.
- Contains custom functions, resource types, and resource providers:
puppet/functions/: Contains functions written in Ruby for the modern
puppet/parser/functions/: Contains functions written in Ruby for the legacy
puppet/provider/: Contains custom resource providers written in the Puppet language.
puppet/type/: Contains custom resource types written in the Puppet language.
- Contains files relating to module localization into languages other than English.
- Contains all of the manifests in the module.
init.ppclass, if used, is the main class of the module. This class's name must match the module's name.
- 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
- 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
implementation/class.pp: This defined type is named
- Contains Puppet task plans, which are sets of tasks that can be combined with other logic. Plans are written in the Puppet language.
- The module's README localized into languages other than English.
- Contains spec tests for any plug-ins in the lib directory.
- Contains Puppet tasks, which can be written in any programming language that can be read by the target node.
- Contains templates, which the module's manifests can use to generate content or variable values.
- A manifest can render this template with
- A manifest can render this template with
- Contains resource type aliases.
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:
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, contained in the module's
manifests/ folder, each contain one class or defined type.
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
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.
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
|Module name||Filepath to class or defined type||Class or defined type name|
Files in modules
You can serve files from a module's
files/ directory to agent nodes.
Download files to the agent by setting the
source attribute to the
puppet:/// URL for the file. Alternately, you can access module files with the
For example, given a file located in
my_module/files/service.conf, the URL is:
To access files with the
filefunction, 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 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
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.
eppfunctions look up templates identified by module and template name, passed as a string in parentheses:
function('module_name/template_name.extension'). For example:
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.
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.