4.11.26. HOWTO Set up and Utilize Bolt

This section details the steps required to set up and utilize Bolt. Bolt is an open source task runner developed by Puppet that facilitates execution of tasks on demand, allowing them to be “pushed” on an as needed basis instead of waiting for Puppet agent to run on a remote system in a “pull” fashion.

The simp_bolt module is intended to configure both Bolt controllers that manage Bolt tasks and Bolt target systems where the tasks are executed. The two parts can be used independently but are intended to work in unison, ensuring that the correct parameters are specified and available on both systems.

4.11.26.1. Setting up a Bolt Target

The target portion of SIMP Bolt ensures that an account with appropriate permissions exists on the target systems. To configure a target system, the simp_bolt class must be included on the target node and simp_bolt::bolt_target must be set to true via Hiera.

There are a variety of other parameters that are either optional or have default values specified that can be overridden in Hiera. A few of the significant parameters and their default values are:

---
simp_bolt::target_user_name:                 'simp_bolt'
simp_bolt::target_user_home:                 '/var/local/simp_bolt'
simp_bolt::target::create_user:              false
simp_bolt::target::disallowed_users:         ['root']
simp_bolt::target::user_password:            undef
simp_bolt::target::user_ssh_authorized_keys: undef
simp_bolt::target::user_allowed_from:        'puppet_server'

The target_user_name parameter specifies the name of the account on the target system that Bolt will use to logon to the system when connecting from a Bolt controller. On target systems, the target_user_home parameter specifies the full path to the home directory of the local account used by Bolt, and the directory will be created if it does not exist. This directory is used by Bolt to stage temporary files on the target system.

Note

By default, SIMP disables running files from the /tmp mount, so the home directory should not be on the /tmp partition.

The create_user parameter indicates whether the specified user account should be managed as a Puppet resource. If an existing account is utilized, this can be left with the default value of false; however, if a new account is required, an opt-in strategy requiring this parameter be set to true has been implemented.

SIMP’s Bolt configuration uses ssh by default to connect from a Bolt controller to a target system. Although both parameters are identified as optional in manifest and undefined by default, it is required that at least one of user_password or user_ssh_authorized_keys be configured for authentication from remote systems if create_user is true.

The disallowed_users parameter specifies accounts not permitted to be managed by SIMP Bolt. This is intended to prevent system accounts, such as root, from be configured in such a fashion as to render a system inoperable.

The user_allowed_from parameters resolves to the puppet server generating the manifest by default. It should be set to the Bolt controller(s) that will manage the target system. This is intended as a security feature to ensure access to an account with sudo privileges is restricted to selected sources.

4.11.26.2. Setting up a Bolt Controller

The controller portion of SIMP Bolt configures a system to run Bolt for execution of tasks on the remote systems. To configure a controller system, the simp_bolt class must be included on the target node and simp_bolt::bolt_controller must be set to true via Hiera.

With just these settings, Bolt will be installed on the controller system and it should be able to execute tasks on a target system. Once again there are a number other parameters that can be specified to refine or customize its performance, including of the following significant parameters and their default values:

---
simp_bolt::controller::local_user_name:           undef
simp_bolt::controller::local_user_home:           undef
simp_bolt::controller::config::disable_analytics: true
simp_bolt::controller::config::config_hash:       undef

The local_user_name parameter specifies the account to be used on the controller to issue Bolt commands. SIMP does not create or manage this account but does use it to set file permissions.

The local_user_home parameter is used to determine where files associated with Bolt should be saved. If local_user_name or local_user_home are not specified, SIMP will default to creating the files in /var/local/simp_bolt with root ownership but world readable permissions so the files can be used as a template for other users to copy to their home directory.

By default, SIMP opts-out of the Bolt analytics data collection to comply with best practices and NIST information limiting requirements. To opt-in, change the disable_analytics parameter to false.

The optional config_hash parameter can used to specify the desired content of the bolt.yaml configuration file. If this parameter is specified, all other configuration parameters will be ignored.

4.11.26.3. Using Bolt with Existing Puppet Modules

Once Bolt is installed, it can be used execute tasks on remote systems. The Bolt documentation provides detailed instructions on how to use Bolt for basic commands. The remainder of this section will focus on using Bolt to manage and apply existing Puppet modules.

To view a list of modules available to Bolt, execute the following command as the local user on the Bolt controller:

bolt puppetfile show-modules

The output of this command should be a list of modules. To download additional modules from the Puppet Forge or a Git repository, create a Puppetfile in the Bolt project directory for the local user on the controller. This will be ~{local_user_name}/.puppetlabs/bolt if it was specified; if not it would be wherever the /var/local/simp_bolt/puppetlabs/bolt directory was copied from the template. To specify modules to install, add them the Puppetfile, using the following format:

# To specify modules from the Puppet Forge
mod 'puppetlabs-stdlib', '5.2.0'
mod 'simp-simplib', '3.13.0'

# To specify modules from a Git repository
mod 'simp-simplib', git: 'https://github.com/simp/pupmod-simp-simplib.git', ref: '3.13.0'

Then execute the command:

bolt puppetfile install

to download and install the specified modules.

To configure Hiera for Bolt, create a hiera.yaml in the Bolt project directory, updating as necessary.

---
version: 5

defaults:  # Used for any hierarchy level that omits these keys.
  datadir: data  # This path is relative to the environment -- <ENVIRONMENT>/data
  data_hash: yaml_data  # Use the built-in YAML backend.

hierarchy:
  - name: "Per-node data"                   # Human-readable name.
    path: "nodes/%{trusted.certname}.yaml"  # File path, relative to datadir.
                                   # ^^^ IMPORTANT: include the file extension!

  - name: "Per-OS defaults"
    path: "os/%{facts.os.family}.yaml"

  - name: "Common data"
    path: "common.yaml"

Hiera data can then be specified as needed by making a data directory in the Bolt project directory and then creating the appropriate YAML files in the directory.

To apply a module to a Bolt target, create a manifest file, such as site.pp, in the Bolt project directory. In its simplest form, the manifest would call the desired module and consist of:

include simplib

The manifest can then be applied to target systems with the command:

bolt apply site.pp --nodes 'comma, separated, list, of, target, nodes'

As mentioned previously, Bolt is configured to use ssh as its transport mechanism to remote systems so it may be necessary to troubleshoot the connection. Some of the common issues could be:

  • No entry for the target system in the known hosts file,
  • The private key file corresponding to the public user_ssh_authorized_keys may not be available, or
  • The --password option should be specified to prompt for a password when connecting to the target system.

Note

Users should verify that an ssh connection can be established from the controller system to the target system as the target_user_name prior to trying to execute a Bolt command.