Modules are self-contained bundles of code and data with a specific directory structure. These reusable, shareable units of Puppet code are a basic building block for Puppet.
Modules must have a valid name and be located in modulepath. Puppet automatically loads all content from every module in the modulepath, making classes, defined types, and plug-ins (such as custom types or facts) available. To learn more about how to classes, defined types, and plug-ins, see the related topics.
You can download and install modules written by Puppet or the Puppet community from the Puppet Forge. Every Puppet user should also expect to write at least some of their own modules.
- Installing modules
- The Forge
- Defined types
- Module plug-ins
- [Declaring classes and defined types][declare]
- External node classifiers (ENC)
- Using plug-ins
Modules have a specific directory structure that allows Puppet to find and automatically load classes, defined types, facts, custom types and providers, functions, and tasks.
Modules must have a valid name and be installed in Puppet’s modulepath. You’ll install modules with either the
puppet module command or, if you’re using code management, with a Puppetfile. See the related topic about installing modules for details.
Each module subdirectory has a specific function. Not all directories are required, but if used, they should be in the following structure.
This example module,
my_module, shows the standard module layout in more detail.
my_module: The main module directory’s name matches the name of the module.
manifests/: Contains all of the manifests in the module.
init.pp: Contains a class definition. The
init.ppclass, if used, is the main class of the module. This class’s name must match the module’s name.
other_class.pp: Contains a class named
my_defined_type.pp: Contains a defined type named
implementation/: This directory’s name affects the class names beneath it.
foo.pp: Contains a class named
bar.pp: Contains a class named
files/: Contains static files, which managed nodes can download.
service.conf: This file’s
source =>URL would be
puppet:///modules/my_module/service.conf. Its contents can also be accessed with the
content => file('my_module/service.conf').
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.
functions: Contains functions written in Ruby for the modern
parser/functions: Contains functions written in Ruby for the legacy
type: Contains custom resource types written in the Puppet language.
provider: Contains custom resource providers written in the Puppet language.
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.
templates/: Contains templates, which the module’s manifests can use.
component.erb: A manifest can render this template with
component.epp: A manifest can render this template with
examples/: Contains examples showing how to declare the module’s classes and defined types.
other_example.pp: Major use cases should have an example.
spec/: Contains spec tests for any plug-ins in the
functions: Contains custom functions written in the Puppet language.
types: Contains resource type aliases.
tasks: Contains Puppet tasks, written in any language.
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_]*. Note that these are the same restrictions that apply to class names, but 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.
Each manifest in a module’s
manifests folder should contain only one class or defined type. The file names of manifests map predictably to the names of the classes and defined types they contain.
init.pp manifest is special and always contains a class with the same name as the module. You cannot name a class
Every other manifest contains a class or defined type named as follows:
|Name of module||::||Other directories:: (if any)||Name of file (no extension)|
my_module::other_classis in the file
my_module::implementation::foois in the file
The double colon that divides the sections of a class’s name is called the namespace separator.
Files in modules
You can serve files in a module’s
files directory to agent nodes.
Download files by using
puppet:/// URLs in the
source attribute of a
file resource. You can also access module files with the
file function. This function takes a
<MODULE NAME>/<FILE NAME> reference and returns the content of the requested file from the module’s
Puppet URLs work the same for both
puppet agent and
puppet apply; in either case they retrieve the correct file from a module.
Puppet URLs are formatted as follows:
|Protocol||3 slashes||“Modules”/||Name of module/||Name of file|
puppet:///modules/my_module/service.conf would map to
Templates in modules
Any ERB or EPP template can be rendered in a manifest. Templates combine code, data, and literal text to produce a final rendered output. The template output is a string, which can be used as the content attribute of a
file resource or as the value of a variable.
For ERB templates, which use Ruby, use the
template function. For EPP templates, which use the Puppet language, use the
epp function. See templates for detailed information.
epp functions can look up templates identified by shorthand:
|Template function||(‘||Name of module/||Name of template||’)|
template('my_module/component.erb') renders the template
See the templates topic for more details.
Every Puppet user should expect to write at least some of their own modules. Modules must have a specific directory structure and include correctly formatted metadata. The Puppet Development Kit provides tools for writing, validating, and testing modules.
The Puppet Development Kit creates a complete module skeleton and includes command line tools for creating classes, defined types, and tasks in your module. It can also validate and run unit tests on modules. PDK can be downloaded and installed on any development machine; a Puppet installation is not required. See the PDK documentation to get started.
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.