Connecting Bolt to PE
Although it's possible to connect Bolt to Puppet Enterprise (PE) using the Puppet Communications Protocol (PCP) transport, in most cases this is not necessary, because tasks and plans are already supported from the console or the command line using PE orchestrator. Wherever possible, we recommend using PE tasks and plans instead of connecting Bolt to PE over PCP. For more information, see Tasks and plans.
For some Bolt features, connecting Bolt to PE over PCP requires the
module. Before you attempt to use the
bolt_shim module, note that:
- If you're only interested in using Bolt tasks, you can use the PCP transport
- In order to use Bolt plan functionality like commands, scripts or file uploads
over PCP, you must install the
bolt_shimmodule. Basic plans without commands, scripts or file uploads do not require the module to function over PCP.
bolt_shimmodule requires you to grant permissions to run all tasks on all nodes to any user that needs to use the module. This grants those users the ability to run any command as root on the nodes. Use this configuration at your own risk.
You might want to use the PCP transport for the following reasons:
- You want to use a Bolt feature that isn't supported in PE yet. Many of the features that are available in Bolt eventually make it into the Puppet orchestrator and PE.
- You want to develop and test Bolt plans locally and can't use SSH or WinRM to do so. If you do have access, you can use SSH or WinRM to test locally.
- You want to interact with nodes attached to different PE instances at the
same time. For example, if you have different PE instances running for
different teams and you want to orchestrate change across all of the
instances. You can achieve this by setting up an inventory file with groups of
targets, and configuring the
pcptransport differently for each group. For more information, see the Bolt Transport configuration reference for
How it works
bolt_shim module, you can configure Bolt to use the orchestrator API
and perform actions on PE nodes. When you run Bolt plans, the plan logic is
processed locally on the node running Bolt, while corresponding commands,
scripts, tasks, and file uploads run remotely using the orchestrator API.
Connecting Bolt to PE
Before you can connect Bolt to PE, you must install Bolt.
To set up Bolt to use the orchestrator API, you must:
- Install the
bolt_shimmodule in a PE environment.
- Assign permissions to run all tasks on all nodes to a user role.
- Adjust the orchestrator configuration files, as needed.
- Configure Bolt to connect to PuppetDB.
bolt_shim module in a PE environment
Bolt uses a task to execute commands, upload files, and run scripts over
orchestrator. To install this task, install the
module from the Forge. Install
the code in the same environment as the other tasks you want to run.
In addition to the
bolt_shim module, any task or module content you want to
execute over Puppet Communications Protocol (PCP) must be present in the PE
environment. For details about downloading and installing modules for Bolt, see
Set up Bolt to download and install
By allowing only content that is present in the PE environment to be executed
over PCP, you maintain role-based access control over the nodes you manage in
To enable the Bolt
apply action, you must install the
Note: Bolt over orchestrator can require a large amount of memory to convey
large messages, such as the plugins and catalogs sent by
apply. You might need
to increase the Java heap
for orchestration services.
Assign task permissions to a user role
CAUTION: Tasks executed with the
bolt_shimmodule allow users to run any command as root on the nodes. Use the module at your own risk.
In the console, click Access control > User roles.
From the list of user roles, click the role you want to have task permissions.
On the Permissions tab, in the Type box, select Tasks.
For Permission, select Run tasks, and select All from the Instance drop-down list.
Click Add permission, and commit the change.
Specify and configure the PCP transport
Bolt runs tasks through the orchestrator when a target uses the
You can configure Bolt to connect to orchestrator in the
config section of
your inventory file, or in the
inventory-config section of your
bolt-defaults.yaml file. This configuration is not shared with
puppet task. By default, Bolt uses the
production environment in PE when running tasks.
For example, your inventory file might look something like this:
groups: - name: linux targets: - nix0.example.com - name: windows targets: - win0.example.com config: transport: pcp pcp: cacert: "certs/cert.pem" service-url: "https://master.example.com" token-file: "tokens/token"
If you want to connect to multiple PE instances, create groups for each instance
and configure the
pcp transport for each group.
For more information on configuration options for the
pcp transport, see
Configure Bolt to connect to PuppetDB
Bolt can authenticate with PuppetDB through an SSL client certificate or a PE RBAC token. For more information see the Bolt docs for Connecting Bolt to PuppetDB.
puppetdb: server_urls: ["https://expensive-tower.delivery.puppetlabs.net:8081", "https://amber-publisher.delivery.puppetlabs.net:8081"] cacert: /tmp/ca.pem token: ~/.puppetlabs/token
In order to run tasks on nodes connected to your PE instance, each task must be
installed on the PE master. To view tasks or plans installed on the PE master's
production environment, run
puppet task show or
puppet plan show
respectively. To specify an environment other than production, use the
--environment flag. For example,
puppet task show --environment test.