Bolt projects

To create a Bolt project:

1. 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.

2. Run bolt project init (or New-BoltProject for PowerShell cmdlet). Bolt creates a bolt-project.yaml file in your project directory. At this point, the bolt-project.yaml only contains a name key with the name of your project.

Congratulations, you've created a Bolt project! 🎉 Develop your Bolt plans and tasks in plans and tasks directories in the root of the project directory, next to bolt-project.yaml. Bolt loads tasks and plans from the tasks and 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

🔩 Tip: To create a project with a list of pre-installed modules, use the --modules option. For more information, see bolt_installing_modules.html#create-a-Bolt-project-with-pre-installed-modules.

Besides the 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 project.

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 bolt-project.yaml options.

The following are common files and directories found in a Bolt project.

Remember: A directory must have a bolt-project.yaml file before Bolt recognizes it as a Bolt project.

📖 Related information

• Modules overview

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 ~/.puppetlabs/bolt/.

Bolt uses the following methods, in order, to choose a Bolt directory.

1. Environment variable: You can specify a path to a project using the BOLT_PROJECT environment variable.

2. 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.

3. Parent directory: Bolt traverses parents of the current directory until it finds one of the following:

   • A bolt-project.yaml file.

   • A directory named Boltdir.

4. Default project directory: If Bolt reaches the root of the file system without finding a Boltdir directory or bolt-project.yaml file, Bolt uses ~/.puppetlabs/bolt/ as the project directory.

For information on Boltdir directories, see 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 subdirectory named 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 name field, Bolt loads your local Bolt content from the top level of the Boltdir. Your Boltdir can also contain modules.

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 project 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.yaml file to it and configuring the modulepath to match the modulepath in environment.conf.

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.

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 BOLT_PROJECT environment variable as:

export BOLT_PROJECT='~/project/my_project'

Note: Exported environment variables expire at the end of the current session. If you need a more permanent solution, add the export line to your ~/.bashrc or 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

Note: The BOLT_PROJECT environment variable takes precedence over the --project CLI option.

After upgrading to a newer version of Bolt, you might find that a Bolt project you created in the past no longer works as expected. Or there might be new features that you want to use in an existing project. The migrate command allows you to update old Bolt projects so that you can use them with the latest Bolt release.

Currently, the migrate command:

• Updates inventory files from version 1.

• Updates projects to use bolt-project.yaml and inventory.yaml instead of bolt.yaml.

• Updates projects to implement module dependency management. Dependency management was introduced in Bolt 2.30.0.

To migrate a project:

*nix shell command

bolt project migrate

PowerShell cmdlet

Update-BoltProject

The migrate command modifies files in your project and does not preserve comments or formatting. Before using the command, make sure to use source control or backup your projects.