A Bolt project is a simple directory that serves as the launching point for Bolt. You store your inventory file and configuration files in a project, together with your Bolt content such as plans and tasks.
In addition to working with your local Bolt content, Bolt projects give you a way to share that content with other users in your organization. You can create orchestration that is specific to the infrastructure you're working with, and then commit the project directory to version control for others to consume.
Bolt identifies a directory as a Bolt project as long as a
file exists at the root of the directory, and the
Create a Bolt project
To create a Bolt project:
Create a directory for your Bolt project. To avoid having to specify a project name in the next step, follow project naming conventions. Project names can contain only lowercase letters, numbers, and underscores, and begin with a lowercase letter.
bolt project init. Bolt creates a
bolt-project.yamlfile in your project directory. At this point, the
bolt-project.yamlonly contains a
namekey with the name of your project.
Congratulations, you've created a Bolt project! 🎉 Develop your Bolt plans and
tasks directories in the root of the project directory,
bolt-project.yaml. Bolt loads tasks and plans from the
plans directories and namespaces them to the project name.
Here is an example of a typical project with a task, a plan, and an inventory file:
. ├── bolt-project.yaml ├── inventory.yaml ├── plans │ └── myplan.yaml └── tasks ├── mytask.json └── mytask.py
Configuring a project
name key, the
bolt-project.yaml file holds options to configure
your Bolt project, as well as options to control how Bolt behaves when you run a
For example, if you want to add a little flair to your Bolt output, use the
rainbow output format:
# bolt-project.yaml name: myproject format: rainbow
For a list of all the available project configuration options, see
Limiting displayed plans and tasks
Projects allow you to limit which plans and
tasks a user can see when running
bolt plan show or
bolt task show.
Limiting tasks and plans is useful for the following reasons:
Bolt is bundled with several plans and tasks that might not be useful in your project.
You might have written a task or plan that is only used by another task or plan, and you don't want your users to run that task or plan directly.
Displaying only specific content in the
showcommands makes it easier for your users to find what they're looking for.
To control what plans and tasks appear when your users run
bolt plan show or
bolt task show, add
tasks keys to your
include an array of plan and task names. For example, to surface a
myproject::myplan, and a task named
myproject::mytask, you would
use the following
name: myproject plans: - myproject::myplan tasks: - myproject::mytask
If your user runs the
bolt plan show command, they'll get similar output to
$ bolt plan show myproject::myplan MODULEPATH: /PATH/TO/BOLT_PROJECT/site Use `bolt plan show <plan-name>` to view details and parameters for a specific plan.
Common files and directories in a project
The following are common files and directories found in a Bolt project.
|Contains configuration options for Bolt and Bolt projects. This file must exist for Bolt to find any of the other files or directories in this list.|
|Contains a list of known targets and target specific data.|
|A directory for storing your plans.|
|A directory for storing your tasks.|
|A directory for storing content consumed by your tasks and plans, such as scripts.|
|Specifies which modules to install for the project. 🧪 Experimental: If you've opted in to the experimental module management workflows, Bolt manages this file. Avoid editing it. For more information, see Managing modules.|
|The directory where modules from the |
|Local modules that are edited and versioned with the Bolt directory.|
|A directory for storing your Puppet code files, known as manifests.|
|Contains the Hiera config to use for target-specific data when using |
|The standard path to store static Hiera data files.|
|Contains debug log output for the most recent Bolt command.|
|Contains configuration options for Bolt. ⛔ |
|🧪 Experimental: The directory where Bolt installs modules. Avoid committing this directory to source control. For more information, see Managing modules.|
Remember: A directory must have a
bolt-project.yamlfile before Bolt recognizes it as a Bolt project.
How Bolt chooses a project directory
Most of the time, you run Bolt commands from within a Bolt project directory that you've created. Running Bolt from inside your project allows Bolt to find your inventory and other configuration files.
However, Bolt always runs in the context of a project. If you don't run from
within your own Bolt project, or you don't specify a project, Bolt uses the
default project directory at
Bolt uses the following methods, in order, to choose a Bolt directory.
Environment variable: You can specify a path to a project using the
Command-line specification: You can specify a directory path on the command line with
--project <DIRECTORY_PATH>. There is not an equivalent configuration setting because the Bolt directory must be known in order to load configuration.
Parent directory: Bolt traverses parents of the current directory until it finds one of the following:
A directory named
Default project directory: If Bolt reaches the root of the file system without finding a
bolt-project.yamlfile, Bolt uses
~/.puppetlabs/bolt/as the project directory.
For information on
Boltdir directories, see Embedded project directories.
Embedded project directories
If you need to embed your Bolt management code into another repo, you can use an embedded project directory. For example, you can store Bolt management code in the same repo as the application that Bolt manages. This prevents file clutter in the top level of the repo and allows you to run Bolt from anywhere in the application's directory structure.
To create an embedded project directory, create a subdirectory in your
application's repo and name it
Boltdir. Bolt treats a directory containing a
Boltdir as an embedded project directory.
The contents the
Boltdir directory follows the same pattern as a local project
directory. As long as your
bolt-project.yaml file contains a
Bolt loads your local Bolt content from the top level of the
Boltdir can also contain modules. For more information, see
An embedded Bolt directory looks like this:
project/ ├── Boltdir │ ├── bolt-project.yaml │ ├── inventory.yaml │ ├── plans │ │ ├── deploy.pp │ │ └── diagnose.pp │ └── tasks │ ├── init.json │ └── init.py ├── src #non Bolt source code for the project └── tests #non Bolt tests for the project
In this example, you could run a Bolt command from the parent
directory, and Bolt would still find your Bolt project.
🔩 Tip: You can use an existing Puppet control repo as a Bolt directory by adding a
bolt-project.yamlfile to it and configuring the
modulepathto match the
Using modules in a Bolt project
Bolt projects make it easier for you to get started with Bolt without following Puppet's module structure. However, if you're developing a custom module, you can still use the Puppet module directory structure with Bolt. For more information, see Module structure.
Note: When you're naming your modules or Bolt project, keep in mind that projects take precedence over installed modules of the same name.
🧪 Experimental: Bolt 2.30.0 introduced changes to how modules are managed in Bolt projects. To find out how to opt in to the changes, see Managing modules.
World-writable project directories
On Unix-like systems, Bolt will not load a project from a world-writable directory by default, as loading from a world-writable directory presents a potential security risk. If you attempt to load a project from a world-writable directory, Bolt does not load any content and raises an exception.
If you wish to override this behavior and force Bolt to load a project from a
world-writable directory, you can set the
BOLT_PROJECT environment variable
to the project directory path.
For example, if you wanted to load a project named
my_project from the
world-writable directory at
~/project/, you would set the
environment variable as:
Note: Exported environment variables expire at the end of the current session. If you need a more permanent solution, add the
exportline to your
~/.bashrcor the relevant profile for the shell you're using.
If you want to use a world-writable directory for a single Bolt execution, set the environment variable before the Bolt command:
BOLT_PROJECT='~/project/my_project' bolt command run uptime -t target1
BOLT_PROJECTenvironment variable takes precedence over the
📖 Related information