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
site-modules directories in the
Bolt project directory.
Directory structure of a module
A module is a sub-directory of one of the directories on the modulepath. In
Bolt to load tasks and plans, they must exist in the
plans/ directory of a module with the correct name.
├── 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
Modules can either be written directly in
site-modules/ or be installed from
the Puppet Forge or a code repository into
Modules for projects
Modules developed to support a particular project can be developed directly in
site-modules directory of the
Create a new directory for each module
site-modules that matches the modules name or use
module to create a skeleton
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.
.gitignoreof your project to prevent accidentally committing standalone modules.
- When you run tasks and plans within a project directory, the modulepath (
site-modules/) is searched for modules containing Bolt content. If a module is found in
modules, tasks and plans from the version of the module in
site-modulesare ignored. Remove a module from
site-modulesif you convert it to a standalone 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).