OpenBolt projects
An OpenBolt project is a simple directory that serves as the launching point for OpenBolt. You store your inventory file and configuration files in a project, together with your OpenBolt content such as plans and tasks.
In addition to working with your local OpenBolt content, OpenBolt 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.
OpenBolt identifies a directory as an OpenBolt project as long as a bolt-project.yaml
file exists at the root of the directory, and the bolt-project.yaml file
contains a name key.
Create an OpenBolt project
To create an OpenBolt project:
- Create a directory for your OpenBolt 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.
- Run
bolt project init(orNew-BoltProjectfor PowerShell cmdlet). OpenBolt creates abolt-project.yamlfile in your project directory. At this point, thebolt-project.yamlonly contains anamekey with the name of your project.
Congratulations, youβve created an OpenBolt project! π Develop your plans and
tasks in plans and tasks directories in the root of the project directory,
next to bolt-project.yaml. OpenBolt 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
--modulesoption. For more information, see .
Configuring a project
Besides the name key, the bolt-project.yaml file holds options to configure
your OpenBolt project, as well as options to control how OpenBolt behaves when you run a
project.
For example, if you want to add a little flair to your OpenBolt 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.
Limiting displayed plans and tasks
Projects allow you to limit which plans and tasks a user can see when running
bolt plan|task show and Get-Bolt(Plan|Task).
Limiting tasks and plans is useful for the following reasons:
- OpenBolt 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 UI makes it easier for your users to find what theyβre looking for.
To control which plans and tasks appear when your users show project content,
add plans and tasks keys to your bolt-project.yaml. Both keys accept a list
of names and glob patterns to filter content by.
For example, to surface a plan named myproject::myplan, and a task named
myproject::mytask, you would use the following bolt-project.yaml file:
name: myproject
plans:
- myproject::myplan
tasks:
- myproject::mytask
If your user runs the bolt plan show command or Get-BoltPlan PowerShell
cmdlet, theyβll get similar output to this:
$ bolt plan show
myproject::myplan
MODULEPATH:
/PATH/TO/BOLT_PROJECT/.modules
Use `bolt plan show <plan-name>` to view details and parameters for a specific plan.
You can also use glob patterns to match multiple plan or task names. For
example, to surface all tasks and plans in a project named myproject, you
would use the following bolt-project.yaml file:
name: myproject
plans:
- myproject::*
tasks:
- myproject::*
Glob patterns that begin with a metacharacter might cause problems when the
configuration file is loaded and parsed, because the pattern might not be
recognized as a string. To avoid this parsing issue, wrap any glob pattern that
begins with a metacharacter in quotes. For example, you would write
"[abc]_module::*" instead of [abc]_module::*.
The following metacharacters can be used in a glob pattern:
| Metacharacter | Description |
|---|---|
* |
Matches any number of characters. |
? |
Matches any one character. |
[set] |
Matches any one character in the set. |
{a,b} |
Matches pattern a and pattern b. |
Common files and directories in a project
The following are common files and directories found in an OpenBolt project.
| Directory/File | Description |
|---|---|
bolt-project.yaml |
Contains configuration options for OpenBolt and OpenBolt projects. This file must exist for OpenBolt to find any of the other files or directories in this list. |
inventory.yaml |
Contains a list of known targets and target specific data. |
plans/ |
A directory for storing your plans. |
tasks/ |
A directory for storing your tasks. |
files/ |
A directory for storing content consumed by your tasks and plans, such as scripts. |
Puppetfile |
Specifies the modules installed in your project. OpenBolt manages this file. Avoid editing it. |
modules/ |
A directory for storing your custom modules. |
manifests |
A directory for storing your Puppet code files, known as manifests. |
hiera.yaml |
Contains the Hiera config to use for target-specific data when using apply. |
data/ |
The standard path to store static Hiera data files. |
bolt-debug.log |
Contains debug log output for the most recent OpenBolt command. |
.modules/ |
The directory where OpenBolt installs modules. Avoid committing this directory to source control. |
Remember: A directory must have a
bolt-project.yamlfile before OpenBolt recognizes it as an OpenBolt project.
π Related information
How OpenBolt chooses a project directory
Most of the time, you run OpenBolt commands from within an OpenBolt project directory that youβve created. Running OpenBolt from inside your project allows OpenBolt to find your inventory and other configuration files.
However, OpenBolt always runs in the context of a project. If you donβt run from
within your own OpenBolt project, or you donβt specify a project, OpenBolt uses the
default project directory at ~/.puppetlabs/bolt/.
OpenBolt uses the following methods, in order, to choose an OpenBolt directory.
- Environment variable: You can specify a path to a project using the
BOLT_PROJECTenvironment variable. - 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 OpenBolt directory must be known in order to load configuration. - Parent directory: OpenBolt traverses parents of the current directory until
it finds one of the following:
- A
bolt-project.yamlfile. - A directory named
Boltdir.
- A
- Default project directory: If OpenBolt reaches the root of the file system
without finding a
Boltdirdirectory orbolt-project.yamlfile, OpenBolt 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 OpenBolt management code into another repo, you can use an embedded project directory. For example, you can store OpenBolt management code in the same repo as the application that OpenBolt manages. This prevents file clutter in the top level of the repo and allows you to run OpenBolt 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. OpenBolt 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,
OpenBolt loads your local OpenBolt content from the top level of the Boltdir. Your
Boltdir can also contain modules.
An embedded OpenBolt directory looks like this:
project/
βββ Boltdir
β βββ bolt-project.yaml
β βββ inventory.yaml
β βββ plans
β β βββ deploy.pp
β β βββ diagnose.pp
β βββ tasks
β βββ init.json
β βββ init.py
βββ src #non-OpenBolt source code for the project
βββ tests #non-OpenBolt tests for the project
In this example, you could run an OpenBolt command from the parent project
directory, and OpenBolt would still find your OpenBolt project.
π© Tip: You can use an existing Puppet control repo as an OpenBolt directory by adding a
bolt-project.yamlfile to it and configuring themodulepathto match themodulepathinenvironment.conf.
Using modules in an OpenBolt project
OpenBolt projects make it easier for you to get started with OpenBolt without following Puppetβs module structure. However, if youβre developing a custom module, you can still use the Puppet module directory structure with OpenBolt. For more information, see Module structure.
Note: When youβre naming your modules or OpenBolt project, keep in mind that projects take precedence over installed modules of the same name.
World-writable project directories
On Unix-like systems, OpenBolt 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, OpenBolt does not load any content and raises an exception.
If you wish to override this behavior and force OpenBolt 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
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 OpenBolt execution, set the environment variable before the OpenBolt command:
BOLT_PROJECT='~/project/my_project' bolt command run uptime -t target1
Note: The
BOLT_PROJECTenvironment variable takes precedence over the--projectCLI option.
Migrate an OpenBolt project
After upgrading to a newer version of OpenBolt, you might find that an OpenBolt 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 OpenBolt projects so that you can use them with the latest
OpenBolt release.
Currently, the migrate command:
- Updates inventory files from version 1.
- Updates projects to use
bolt-project.yamlandinventory.yamlinstead ofbolt.yaml. - Updates projects to use module dependency management.
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.
How OpenBolt updates inventory files
OpenBolt locates the inventory file for the current OpenBolt project and migrates it in place.
The updates change the following keys in your inventory file:
nodesbecomestargets.- The
namekey in aTargetobject becomes aurikey.
For example, the following inventory file from Bolt version 1:
groups:
- name: linux
nodes:
- name: target1.example.com
alias: target1
- name: target2.example.com
alias: target2
Becomes:
groups:
- name: linux
targets:
- uri: target1.example.com
alias: target1
- uri: target2.example.com
alias: target2
How OpenBolt updates project configuration
OpenBolt locates a bolt.yaml file and moves its configuration to a new bolt-project.yaml file
and the inventory.yaml file. It then deletes the bolt.yaml file.
Project-specific configuration is moved to the bolt-project.yaml file, while transport
configuration is moved to the top-level config key in the inventory.yaml file. If the
inventory.yaml file has an existing top-level config key, the transport configuration
from bolt.yaml is deep merged, with the configuration in inventory.yaml having higher
precedence.
For example, a project with the following bolt.yaml and inventory.yaml files:
# bolt.yaml
format: json
transport: winrm
winrm:
user: Administrator
password: Bolt!
# inventory.yaml
groups:
- name: windows
targets:
- target1.example.com
- target2.example.com
config:
winrm:
ssl: false
Becomes:
# bolt-project.yaml
format: json
# inventory.yaml
groups:
- name: windows
targets:
- target1.example.com
- target2.example.com
config:
transport: winrm
winrm:
ssl: false
user: Administrator
password: Bolt!
How OpenBolt updates projects to use module dependency management
When you run the migrate command, OpenBolt reads your Puppetfile and prompts you
for the direct dependencies of your project. OpenBolt adds the direct dependencies
to a modules key in your bolt-project.yaml file and resolves the
dependencies of those modules. Next, OpenBolt installs the modules and dependencies
into a .modules directory and generates a Puppetfile with a list of the
installed modules. OpenBolt moves any modules from your site-modules directory
into modules.
For example, given a project named myproject with a custom module named
mymodule in your site-modules directory, and the following Puppetfile:
mod "puppetlabs-apache", "5.5.0"
mod "puppetlabs-apt", "7.6.0"
mod "puppetlabs-mysql", "10.7.1"
mod "puppetlabs-stdlib", "6.4.0"
mod "puppetlabs-concat", "6.2.0"
mod "puppetlabs-translate", "2.2.0"
mod "puppetlabs-resource_api", "1.1.0"
mod "puppetlabs-puppetserver_gem", "1.1.1"
If you ran the migrate command, and selected the apache, apt, and mysql
modules as direct dependencies of your OpenBolt project, OpenBolt would do the
following:
-
Update your
bolt-project.yamlfile to add themoduleskey, together with theapache,apt, andmysqlmodules:--- name: myproject modules: - name: puppetlabs-apache version_requirement: "=5.5.0" - name: puppetlabs-apt version_requirement: "=7.6.0" - name: puppetlabs-mysql version_requirement: "=10.7.1" -
Resolve your dependencies and generate a new Puppetfile:
# This Puppetfile is managed by Bolt. Do not edit. mod "puppetlabs-apache", "5.5.0" mod "puppetlabs-apt", "7.6.0" mod "puppetlabs-mysql", "10.7.1" mod "puppetlabs-stdlib", "6.4.0" mod "puppetlabs-concat", "6.2.0" mod "puppetlabs-translate", "2.2.0" mod "puppetlabs-resource_api", "1.1.0" mod "puppetlabs-puppetserver_gem", "1.1.1" - Install the modules from the Puppetfile into the
.modulesdirectory. - Remove the old managed modules from the
modules/directory. - Move
mymodulefromsite-modules/tomodules/.
π Related information