Getting Started With Puppet Bolt

Puppet Bolt is an open source automation and orchestration tool that can be used for various use cases from running a simple command on a remote system to orchestrating a multi-tier application deployment.

Puppet Bolt Concepts

Now that we know what Puppet Bolt is and why we would use it, let’s take a look at some of it’s concepts and terminology.

Commands: Arbitrary commands that can be run against remote systems.

Scripts: Arbitrary scripts that can be run against remote systems.

Tasks: Packaged scripts that can be written in any programming language that is installed on the remote system.

Plans: A set of tasks that can be combined in a logical manner to support complex orchestration. Plans also support the application of Puppet code.

Transport: The connection protocol used by Bolt to connect to the system such as SSH or WinRM.

Inventory: An inventory file is used to store connection information about targets such as user credentials, ip address or hostname and the connection transport (winrm, ssh, etc.).

Installing Puppet Bolt

Puppet Bolt can be installed on Windows, Linux and Mac OS X to support execution from just about any operating system an administrator might be running.

Installing Bolt

Mac OS X

Puppet Bolt can be installed on Mac OS X with Homebrew or from a DMG. Run the command below to install it using HomeBrew.

brew cask install puppetlabs/puppet/puppet-bolt

To install it using a DMG download the DMG file and double-click on the downloaded file to start the installation wizard.

Linux (RHEL or CentOS)

Add the puppet-tools yum repository to the system.

sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-7.noarch.rpm

Install the puppet-bolt package

sudo yum -y install puppet-bolt

Using Puppet Bolt

Now that Puppet Bolt has been installed, we’re ready to start using it to manage our systems. Puppet Bolt supports running arbitrary commands and scripts but we’ll start with Tasks to take advantage of existing tasks that can be found on the Puppet Forge.

List available tasks

Puppet Bolt includes a number of built-in tasks that we can view by running the following command.

bolt task show

The command should output a list of tasks similar to that displayed below.

facts                      Gather system facts
package                    Manage and inspect the state of packages
pkcs7::secret_createkeys   Create a key pair
pkcs7::secret_decrypt      Encrypt sensitive data with pkcs7
pkcs7::secret_encrypt      Encrypt sensitive data with pkcs7
puppet_agent::install      Install the Puppet agent package
puppet_agent::version      Get the version of the Puppet agent package installed. Returns nothing if none present.
puppet_conf                Inspect puppet agent configuration settings
reboot                     Reboots a machine
reboot::last_boot_time     Gets the last boot time of a Linux or Windows system
service                    Manage and inspect the state of services
terraform::apply           Apply an HCL manifest
terraform::destroy         Destroy resources managed with Terraform
terraform::initialize      Initialize a Terraform project directory
terraform::output          JSON representation of Terraform outputs

Running a task against the local system

Now that we know what tasks are available to us, we’ll run the facts task to gather information about our local machine. This allows us to work with Bolt without needing to make any changes our system. Run the following command to gather system facts.

bolt task run facts --targets localhost

The command should have returned a JSON payload of “facts” or system information about the local system similar to those displayed below.

bolt task run facts --targets localhost
Started on localhost...
Finished on localhost:
  {
    "aio_agent_version": "5.5.20",
    "architecture": "x86_64",
    "augeas": {
      "version": "1.12.0"
    },
    "augeasversion": "1.12.0",
    "dhcp_servers": {
      "en0": "10.0.0.1",
      "system": "10.0.0.1"
    },
    "dmi": {
      "product": {
        "name": "MacBookPro15,2"
      }
    },
    "domain": "domain.local",
    "facterversion": "3.11.13",
    "filesystems": "apfs,autofs,devfs,nullfs",
    "fqdn": "macbook.domain.local",
    "hardwareisa": "i386",
    ...
}

Running a task against a remote system

Now that we have seen how to run a task against our local machine we’re ready to do the same against remote systems.

We can target remote systems by passing the connection information at the command line when we run Puppet Bolt or referencing a target from an inventory file. Both methods are valuable to know so we’ll take a look at both methods.

Command Line

The command below runs the facts task against a remote node as the root user and no host key checking for the SSH connection to the node. In this we’re assuming that key based authentication is being used but the --password-prompt flag can be passed to manually supply the password.

bolt task run facts --targets 10.0.0.134 --user root --no-host-key-check

The command should have returned a JSON payload of “facts” or system information about the remote system similar to those displayed below.

Started on 10.0.0.134...
Finished on 10.0.0.134:
  {
    "aio_agent_build": "5.5.20",
    "aio_agent_version": "5.5.20",
    "architecture": "x86_64",
    "augeas": {
      "version": "1.12.0"
    },
    "augeasversion": "1.12.0",
    "bios_release_date": "04/05/2016",
    "bios_vendor": "Phoenix Technologies LTD",
    "bios_version": "6.00",
    "blockdevice_sda_model": "Virtual disk",
    "blockdevice_sda_size": 37580963840,
    "blockdevice_sda_vendor": "VMware",
    "blockdevices": "sda",
    "boardmanufacturer": "Intel Corporation",
    "boardproductname": "440BX Desktop Reference Platform",
    "boardserialnumber": "None",
    "chassisassettag": "No Asset Tag",
    ...
}

Inventory

Now that we’ve seen how to target a remote system by specifying the connection information at the command line, let’s look at how to use an inventory file. The following command runs the facts tasks against the web targets that we have specified in our inventory.yaml file that we’ll create in a moment.

bolt task run facts --targets web -i inventory.yaml

Instead of including all the connection information at the command line we’ve defined it in the inventory file below and simply reference it when running our task. The web targets from the command above corresponds the web group defined in the inventory file which could include multiple remote systems. The following inventory file should be created and named inventory.yaml.

groups:
  - name: web
    targets:
      - 10.0.0.134
    config:
      transport: ssh
      ssh:
        user: root
        private-key: ~/.ssh/id_rsa
        host-key-check: false

The command should have returned the facts JSON payload just as the first Bolt command that we ran against the remote system did. There are a number of other pre-built tasks that can be found on the Puppet Forge in addition to writing custom tasks to fit a specific need not covered by a Forge module.