Puppet tasks, plans, functions, classes and types must exist inside a Puppet module in order for Bolt to load them. Bolt loads modules by searching for module directories on the modulepath.
By default, the modulepath includes the
in the Bolt project directory. If
exists at the root of the project directory, the project itself is also
loaded as a module and namespaced to either
bolt-project.yaml if it's
set, or the name of the directory if
name is not set.
bolt-project.yamlfile is part of an experimental feature. For more information, see Bolt projects.
Directory structure of a module
A module is a sub-directory of one of the directories on the modulepath. In order for Bolt to load tasks and plans, they must exist in the
plans/ directory of a module with the correct name.
🔩 Tip: You can use the Puppet Development Kit (PDK) to create modules and add tasks to it.
A typical module for use with Bolt may contain these directories:
├── data/ ├── files/ ├── hiera.yaml ├── lib/ ├── manifests/ ├── metadata.json ├── plans/ └── tasks/
|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 code
You can develop modules directly in the Bolt project directory or install them from the Puppet
Forge into the
Modules for projects
Modules developed to support a particular project can be developed directly in the Bolt project directory. You can use
pdk new module to create a skeleton structure, and
bolt project init inside a directory to make it a Bolt project directory.
Note: To use the
pdk command, you must install the Puppet Development Kit
Standalone modules can be published to the Forge or saved in a shared code repository so that modules can be used from multiple projects or shared publicly.
To use a standalone module, install the module into the project directory.
To create a standalone module, run
pdk new module outside of the project directory, develop the module, then push it to a code repository or the Forge before using it in your project.
Follow these tips for managing standalone modules:
.gitignoreof your project to prevent accidentally committing standalone modules.
When you run tasks and plans within a project directory the modulepath is searched in order for modules containing Bolt content. The Bolt project directory itself is loaded as a module at the front of the modulepath, and the default modulepath is
<project directory>/modules:<project directory>/site-modules. If you have a module in both the
site-modulesdirectories, the version in
moduleswill be used.
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).