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, and not all directories are required. Use the following directory 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 primary Puppet server.

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 primary Puppet server 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.

plans/

Contains Puppet task plans, which are sets of tasks that can be combined with other logic. Plans are written in the Puppet language.

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 must match the expression: [a-z][a-z0-9_]*. In other words, they can contain only lowercase letters, numbers, and underscores, and begin with a lowercase letter.

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 returns 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')