Before Bolt can load content like tasks, plans, functions, classes and types, that content must exist inside a Puppet module on the current Bolt project's modulepath.
By default, the Bolt modulepath includes the
directories, as well as any project-level content in the current Bolt project
directory. You can create project-level content to use with Bolt, or create a
standalone module that you can install with Bolt and use as you would any other
module you downloaded from the Forge.
Directory structure of a module
Modules have a specific directory structure outlined in the Puppet documentation. However, a typical module for use with Bolt may contain these files and directories:
|Hiera data that can be used when applying a manifest block.|
|Static files that can be loaded by a plan or required as a dependency of a task. Prefer putting non-Ruby libraries used by a task here.|
|Puppet language functions that can be used from a plan.|
|Hiera configuration for this module.|
|Typically Ruby code, such as custom Puppet functions, types, or providers.|
|Classes and other Puppet code usable when applying a manifest block.|
|Typical metadata for a module describing version, operating system compatibility, and other module dependencies.|
|Plans, which must end in the |
|Tasks and their metadata.|
Where to put module content
You have two options when it comes to storing and developing module content:
You can develop modules directly in the Bolt project directory inside the
You can develop your module content outside of a project directory and then add the module's directory to your project's modulepath for use with Bolt. Alternatively, you can publish the module to the Forge and install it to your Bolt project.
Modules for projects
If you're developing a module to support a particular project, you can develop
the module directly in the Bolt project directory. To create a skeleton
structure for your module, run
pdk new module inside the
in your project. For information on creating a new project, see Bolt
Note: To use the
pdk command, you must install the Puppet Development
If you want to share a module publicly, you can develop the module outside of a Bolt project and publish it to the Puppet Forge. If you want to use the module in multiple Bolt projects, but don't want to publish it, you can add the directory that contains the module to your modulepath.
To create a standalone module and publish it on the Forge:
pdk new moduleoutside of a Bolt project directory.
Develop the module.
Push the module to a code repository or the Forge.
After you've published the module to the Forge, you can add it to a Bolt project using the Bolt command line. For more information, see Installing modules.
Follow these tips for managing standalone modules:
If you're testing a standalone module inside a project, add
modules/*to the project's
.gitignorefile to prevent accidentally committing the module.
As a best practice, write automated tests for the tasks and plans in your module, if possible. For information about automated testing patterns, check out these resources: Example of unit testing plans and integration (acceptance) testing tasks (GitHub) and Writing Robust Puppet Bolt Tasks: A Guide (Puppet blog).