Packaged versions of Bolt are available for many modern Linux distributions, as well as macOS and Windows.
Have questions? Get in touch. We're in #bolt on the Puppet community Slack.
Tip: Bolt uses an internal version of Puppet that supports tasks and plans, so you do not need to install Puppet. If you use Bolt on a machine that has Puppet installed, Bolt uses its internal version of Puppet and does not conflict with the Puppet version you have installed.
Note: Bolt automatically collects data about how you use it. If you want to opt out of providing this data, you can do so. For more information see, Analytics data collection
Use one of the supported Windows installation methods to install Bolt.
Use the MSI installer package to install Bolt on Windows.
- Download the Bolt installer package.
- Double-click the MSI file and run the installer.
- Run a Bolt command and get started.
bolt --help
If you see an error message instead of the expected output, you probably need to follow one or both of the additional steps below. See Add the Bolt module to PowerShell and Change execution policy restrictions.
Use the package manager Chocolatey to install Bolt on Windows.
You must have the Chocolatey package manager installed.
- Download and install the bolt package.
choco install puppet-bolt
- Run a Bolt command and get started.
bolt --help
If you see an error message instead of the expected output, you probably need to follow one or both of the additional steps below. See Add the Bolt module to PowerShell and Change execution policy restrictions.
PowerShell versions 2.0 and 3.0 cannot automatically discover and load the Bolt module, so you'll need to add it manually. Unless your system dates from 2013 or earlier, this situation probably does not apply to you. To confirm your version, run echo $PSTableVersion
in PowerShell.
To allow PowerShell to load Bolt, add the correct module to your PowerShell profile.
- Update your PowerShell profile.
'Import-Module -Name ${Env:ProgramFiles}\WindowsPowerShell\Modules\PuppetBolt' | Out-File -Append $PROFILE
- Load the module in your current PowerShell window.
. $PROFILE
Some Windows installations have security restrictions that do not allow Bolt to run. These restrictions are easy to change, but check with your security team first.
If you see this or a similar error when trying to run Bolt, you probably need to change your script execution policy restrictions, as described here.
bolt : The 'bolt' command was found in the module 'PuppetBolt', but the module could not be loaded.
For more information, run 'Import-Module PuppetBolt'.
At line:1 char:1
+ bolt --help
+ ~~~~
+ CategoryInfo : ObjectNotFound: (bolt:String) [], CommandNotFoundExceptio
n
+ FullyQualifiedErrorId : CouldNotAutoloadMatchingModule
- Run PowerShell as an administrator:
Windows-X, a
- Set your script execution policy to at least
RemoteSigned
:For more information about PowerShell execution policies, see Microsoft's documentation about execution policies and how to set them.Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
Use one of the supported macOS installation methods to install Bolt.
Use the Apple Disk Image (DMG) to install Bolt on macOS.
-
Download the Bolt installer package for your macOS version.
Tip: To find the macOS version number on your Mac, go to the Apple () menu in the corner of your screen and choose About This Mac.
- 10.11 (El Capitan) https://downloads.puppet.com/mac/puppet6/10.11/x86_64/puppet-bolt-latest.dmg
- 10.12 (Sierra) https://downloads.puppet.com/mac/puppet6/10.12/x86_64/puppet-bolt-latest.dmg
- 10.13 (High Sierra) https://downloads.puppet.com/mac/puppet6/10.13/x86_64/puppet-bolt-latest.dmg
- 10.14 (Mojave) https://downloads.puppet.com/mac/puppet6/10.14/x86_64/puppet-bolt-latest.dmg
-
Double-click the
puppet-bolt-latest.dmg
file to mount it and then double-clickpuppet-bolt-[version]-installer.pkg
to run the installer. -
Run a Bolt command and get started.
bolt --help
Use the package manager Homebrew to install Bolt on macOS.
You must have the command line tools for macOS and the Homebrew package manager installed.
- Download and install the Bolt package.
brew cask install puppetlabs/puppet/puppet-bolt
- Run a Bolt command and get started.
bolt --help
Use one of the supported *nix installation methods to install Bolt.
CAUTION: These instructions include enabling the Puppet Tools repository. While Bolt can also be installed from the Puppet 6 or 5 platform repositories, adding these repositories to a Puppet-managed target, especially a PE master, might result in an unsupported version of a package like puppet-agent
being installed. This can cause downtime, especially on a PE master.
Packaged versions of Bolt are available for Debian 8-10 and Ubuntu 16.04 and 18.04.
The Puppet Tools repository for the APT package management system is https://apt.puppet.com. Packages are named using the convention puppet-tools-release-<VERSION CODE NAME>.deb
. For example, the release package for Puppet Tools on Debian 8 “Jessie” is puppet-tools-release-jessie.deb
.
-
Download and install the software and its dependencies. Use the commands appropriate to your system.
- Debian 8
wget https://apt.puppet.com/puppet-tools-release-jessie.deb sudo dpkg -i puppet-tools-release-jessie.deb sudo apt-get update sudo apt-get install puppet-bolt
- Debian 9
wget https://apt.puppet.com/puppet-tools-release-stretch.deb sudo dpkg -i puppet-tools-release-stretch.deb sudo apt-get update sudo apt-get install puppet-bolt
- Debian 10
wget https://apt.puppet.com/puppet-tools-release-buster.deb sudo dpkg -i puppet-tools-release-buster.deb sudo apt-get update sudo apt-get install puppet-bolt
- Ubuntu 16.04
wget https://apt.puppet.com/puppet-tools-release-xenial.deb sudo dpkg -i puppet-tools-release-xenial.deb sudo apt-get update sudo apt-get install puppet-bolt
- Ubuntu 18.04
wget https://apt.puppet.com/puppet-tools-release-bionic.deb sudo dpkg -i puppet-tools-release-bionic.deb sudo apt-get update sudo apt-get install puppet-bolt
- Debian 8
-
Run a Bolt command and get started.
bolt --help
Packaged versions of Bolt are available for Red Hat Enterprise Linux 6 and 7, SUSE Linux Enterprise Server 12, and Fedora 28-30.
The Puppet Tools repository for the YUM package management system is http://yum.puppet.com/puppet-tools/. Packages are named using the convention puppet-tools-release-<OS ABBREVIATION>-<OS VERSION>.noarch.rpm
. For example, the release package for Puppet Tools on Linux 7 is puppet-tools-release-el-7.noarch.rpm
.
- Download and install the software and its dependencies. Use the commands appropriate to your system.
- RHEL 6
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-6.noarch.rpm sudo yum install puppet-bolt
- RHEL 7
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-7.noarch.rpm sudo yum install puppet-bolt
- RHEL 8
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-8.noarch.rpm sudo yum install puppet-bolt
- SUSE Linux Enterprise Server 12
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-sles-12.noarch.rpm sudo zypper install puppet-bolt
- Fedora 28
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-fedora-28.noarch.rpm sudo dnf install puppet-bolt
- Fedora 29
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-fedora-29.noarch.rpm sudo dnf install puppet-bolt
- Fedora 30
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-fedora-30.noarch.rpm sudo dnf install puppet-bolt
- Fedora 31
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-fedora-31.noarch.rpm sudo dnf install puppet-bolt
- RHEL 6
- Run a Bolt command and get started.
bolt --help
Bolt packages include their own copy of Ruby.
When you install gems for use with Bolt, use the --user-install
flag to avoid requiring privileged access for installation. This option also enables sharing gem content with Puppet installations — such as when running apply
on localhost
— that use the same Ruby version.
To install a gem for use with Bolt, use the command appropriate to your operating system:
- On Windows with the default install location:
"C:/Program Files/Puppet Labs/Bolt/bin/gem.bat" install --user-install <GEM>
- On other platforms:
/opt/puppetlabs/bolt/bin/gem install --user-install <GEM>
Starting with Bolt 0.20.0, gem installations no longer include core task modules.
To install Bolt reliably and with all dependencies, use one of the Bolt installation packages instead of a gem.
Bolt is available on Docker Hub, as an image called puppet-bolt
. There are a number of ways to run Bolt from a Docker image.
Docker Hub contains different versions of Bolt, with tags corresponding to Bolt system package and Rubygem versions. The newest version has a latest
tag.
You can download the latest image with this command:
docker pull puppet/puppet-bolt
When running Bolt from a Docker image, Docker creates a container and executes the Bolt command within that container. Running Bolt in this way is simple:
$ docker run puppet/puppet-bolt command run 'cat /etc/os-release' -t localhost
Started on localhost...
Finished on localhost:
STDOUT:
NAME="Ubuntu"
VERSION="16.04.6 LTS (Xenial Xerus)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 16.04.6 LTS"
VERSION_ID="16.04"
HOME_URL="http://www.ubuntu.com/"
SUPPORT_URL="http://help.ubuntu.com/"
BUG_REPORT_URL="http://bugs.launchpad.net/ubuntu/"
VERSION_CODENAME=xenial
UBUNTU_CODENAME=xenial
Successful on 1 target: localhost
Ran on 1 target in 0.00 seconds
As you can see from the above example, the localhost
target is the container environment, not the host environment.
Typically you would want to run Bolt not against the container environment, but against a different computer. To do this, you must pass information to the Bolt container about how to connect to the target computer. You might also want to pass the container some custom module content for Bolt to use. The next sections describe three different techniques for sharing this kind of information between the host and the Docker container.
If you only need to pass information on how to connect to targets, and not any custom module content, you can pass the inventory information by assigning it to an environment variable. This inventory.yaml
file contains all the information needed for connecting to an example target:
version: 2
targets:
- name: pnz2rzpxfzp95hh.delivery.puppetlabs.net
alias: docker-example
config:
transport: ssh
ssh:
user: root
password: secret-password
host-key-check: false
Here is an example of running the built-in facts
task against the target listed in inventory. Note that the command passes the contents of the inventory file via an environment variable:
$ docker run --env "BOLT_INVENTORY=$(cat Boltdir/inventory.yaml)" \
puppet/puppet-bolt task run facts -t docker-example
Started on pnz2rzpxfzp95hh.delivery.puppetlabs.net...
Finished on pnz2rzpxfzp95hh.delivery.puppetlabs.net:
{
"os": {
"name": "CentOS",
"release": {
"full": "7.2",
"major": "7",
"minor": "2"
},
"family": "RedHat"
}
}
Successful on 1 target: pnz2rzpxfzp95hh.delivery.puppetlabs.net
Ran on 1 target in 0.55 seconds
Another way of passing information is to make your Bolt project directory (Boltdir) available to the container. Here is the directory structure of a typical Boltdir:
$ tree
.
└── Boltdir
├── bolt.yaml
├── inventory.yaml
├── keys
│ └── id_rsa-acceptance
└── site-modules
└── docker_task
└── tasks
└── init.sh
5 directories, 4 files
Here is sample content from relevant files in the Boltdir above.
bolt.yaml
This is a basic Bolt configuration file.
log:
console:
level: notice
inventory.yaml
This lists a target, and connection information for that target.
version: 2
targets:
- name: pnz2rzpxfzp95hh.delivery.puppetlabs.net
alias: docker-example
config:
transport: ssh
ssh:
user: root
private-key: /Boltdir/keys/id_rsa-acceptance
host-key-check: false
init.sh
This is a shell task that prints the contents of the message
parameter.
#!/bin/bash
echo "Message: ${PT_message}"
This command executes the Bolt task above within a Docker container, using a shared Boltdir to pass information to the container:
$ docker run --mount type=bind,source=/path/to/Boltdir,destination=/Boltdir \
puppet/puppet-bolt task run docker_task message=hi -t docker-example
Started on pnz2rzpxfzp95hh.delivery.puppetlabs.net...
Finished on pnz2rzpxfzp95hh.delivery.puppetlabs.net:
Message: hi
{
}
Successful on 1 target: pnz2rzpxfzp95hh.delivery.puppetlabs.net
Ran on 1 target in 0.56 seconds
The --mount
flag maps the Bolt project directory on the Docker host to /Boltdir
in the container. The container is tagged as puppet-bolt
and the rest of the command is all native to Bolt.
You can also extend the puppet-bolt
image and copy in data that will always be available for that image.
For example, create a file called Dockerfile
in this location within your Boltdir:
$ tree
.
└── Boltdir
├── bolt.yaml
├── Dockerfile
├── inventory.yaml
├── keys
│ └── id_rsa-acceptance
└── site-modules
└── docker_task
└── tasks
└── init.sh
5 directories, 5 files
Give the Dockerfile the following content:
FROM puppet/puppet-bolt
COPY . /Boltdir
Now you can build a Docker image with your custom module content and tag it my-extended-puppet-bolt
with this command:
$ docker build . -t my-extended-puppet-bolt
Sending build context to Docker daemon 10.75kB
Step 1/2 : FROM puppet-bolt
---> 5d8d2c1166fc
Step 2/2 : COPY . /Boltdir
---> 03162d29a1ee
Successfully built 03162d29a1ee
Successfully tagged my-extended-puppet-bolt:latest
You can run that container with the custom module content and connection information available inside the container:
$ docker run my-extended-puppet-bolt task run docker_task message=hi -t docker-example
Started on pnz2rzpxfzp95hh.delivery.puppetlabs.net...
Finished on pnz2rzpxfzp95hh.delivery.puppetlabs.net:
Message: hi
{
}
Successful on 1 target: pnz2rzpxfzp95hh.delivery.puppetlabs.net
Ran on 1 target in 0.56 seconds
Bolt collects data about how you use it. You can opt out of providing this data.
- Version of Bolt
- The Bolt command executed (for example,
bolt task run
orbolt plan show
), excluding arguments - The functions called from a plan, excluding arguments
- User locale
- Operating system and version
- Transports used (SSH, WinRM, PCP) and number of targets
- The number of targets and groups defined in the Bolt inventory file
- The number of targets targeted with a Bolt command
- The output format selected (human-readable, JSON)
- Whether the Bolt project directory was determined from the location of a
bolt.yaml
file or with the--boltdir
flag - The number of times Bolt tasks and plans are run (not including user-defined tasks or plans.)
- The number of statements in a manifest block, and how many resources that produces for each target
- The number of steps in a YAML plan
- The return type (expression vs. value) of a YAML plan
- Which bundled plugins Bolt is using (not including user-installed plugins)
This data is associated with a random, non-identifiable user UUID.
To see the data Bolt collects, add --debug
to a command.
Bolt collects data to help us understand how it's being used and make decisions about how to improve it.
To disable the collection of analytics data add the following line to ~/.puppetlabs/bolt/analytics.yaml
:
disabled: true