Getting Started with Puppet Bolt on VMware

Bolt is an open-source orchestration tool created by Puppet. It allows VMware administrators to orchestrate changes among their VMware infrastructure. This product fills a gap in the standard Puppet configuration management tooling, which uses the pull methodology for configuration. The pull methodology used by Puppet configuration management requires an agent to be installed on servers. Each agent routinely pulls down their configurations from the puppet master server. This has quite a few benefits, however, there are some caveats, e.g. not being able to push immediate changes throughout the infrastructure; this is where Bolt comes into play.

When I first heard about Bolt, I immediately thought, “Why would I use this? I can just do everything through PowerShell remoting”. As I started to learn about the tool I realized, Bolt is much more than just a remoting tool, it’s an orchestration tool. Bolt allows for complex logic to be scripted using the powerful language of Puppet code. It also has a very robust remoting system that allows it to remotely connect to servers through SSH and WinRM. This open source tool has many integrations through other products like Terraform. Microsoft has also recently integrated Bolt natively into the Azure Cloud Shell, which means even they see a benefit in using Bolt for orchestration.

For VMware administrators, Bolt can cover holes that are prevalent in other tools.  It can be used to patch ESXi hosts or perform maintenance tasks like starting or stopping services. In this example, we are going to install Bolt on a Windows 10 machine and use it to upload and install the HPE Utilities Bundle Smart Component for ESXi 6.7 on several ESXi hosts.

Installing Bolt and Creating a Project

To get started, download the Bolt MSI installer. Run the installer selecting the default settings for everything. Once Bolt has installed successfully, open up a PowerShell console and type in the following command to verify Bolt is installed correctly:

bolt help

We should now see that Puppet Bolt is installed on our system:

Now, let’s make a new Bolt project. We will create a project in the C:\Bolt directory using the bolt project command to create a new project called “InstallHPEUtil”:

bolt project init InstallHPEUtil

This creates a Bolt project directory in C:/Bolt/InstallHPEUtil. Note, this directory is typically referred to as Boltdir in online documentation references. Bolt projects allow for users to easily share different Bolt code with the community as well as provide easy integration with other tools. Also notice that now we have a bolt.yaml file in our new project directory. YAML stands for Yet Another Markup Language, it is used to store key value pairs similar to JSON. The bolt.yaml file is used for making configuration changes to Bolt:

Now that we have installed Bolt and set up a project, lets run our first command against an ESXi host.

Running a Command

Before we can run a command against an ESXi host, we need to establish our target. We can do this in two ways. By quickly referencing a target with the –target parameter when we run bolt command; or by using inventory files. To set up a target with an inventory.yaml file, run the following command in the bolt project directory. This will create an inventory file and then immediately open it in notepad:

new-item -name inventory.yaml ; notepad inventory.yaml

Now paste in the following yaml configuration. It contains the information for our target group. We are going to call the group “esxi”, with only one referenced target (192.168.0.6). Under targets configuration we have our SSH settings, including username and password. Notice the password section is using a plugin. Plugins are used to lookup information on the fly, like from Vault, Azure, or another YAML file. In this case, it is used to prompt for the ESXi password when bolt runs in order to refrain from saving the password to the inventory file:

# Inventory file for Bolt
version: 2
groups:
  - name: esxi
    targets:
      - 192.168.0.6
    config:
      ssh:
        host-key-check: false
        user: root
        password: 
          _plugin: prompt
          message: Enter your ESXi password

After saving the notepad, we are ready to run our command. We’ll run a simple hostname command by using the bolt command syntax:

bolt command run 'hostname' --targets esxi

We are prompted for the ESXi password because of the prompt plugin. Once entered, bolt establishes a connection to the host in the esxi group. The hostname command is then executed against the host successfully.

Running a Script

Now that we ran a command against a host, how can we run an entire script? Paste the following syntax into a notepad and save it as simplescript.sh:

echo "This is a simple script ran by Puppet Bolt!"

We can simply run the bolt script command to run our script on the ESXi host:

bolt script run simplescript.sh --targets esxi

The script is automatically uploaded to the ESXi host and executed.

Running a Task

Tasks are very similar to scripts but provide a better way to share with others. Think of them like a PowerShell cmdlet vs a script, you can run both, but cmdlets are much more reusable and can be packaged into a PowerShell module with a help file and shared out with others. Let’s convert our script into a task. Tasks must live in the “Boltdir/site-modules/<module name>/tasks” folder. So in our current folder structure, we will create the following folder directories from the root of the InstallHPEUtil folder:

mkdir site-modules/test/tasks

Next, we will move the script we just created over to the tasks folder:

mv ./simplescript.sh site-modules/test/tasks/simplescript.sh

Bolt will automatically look inside the tasks folder when we reference it in the “<modulename>::<scriptname>” format. We will run our task by using bolt task:

bolt task run test::simplescript --targets esxi

We can see the task runs just like the script:

Creating a Plan

Let’s get a little fancy with Bolt. We can create a Plan to orchestrate the installation of the HPE Utilities Bundle Smart Component on several ESXi hosts. A Bolt plan is a series of tasks and commands used to perform a larger complex process. Plans need to be inside the plans folder under the module. We will make a new module folder this time called hpeutil and create a plans folder underneath:

mkdir site-modules/hpeutil/plans/

Inside the plans folder, we will create a plan called install.pp:

Open notepad and paste the following contents and save it as a install.pp file which is our puppet plan file:

plan hpeutil::install (
  TargetSpec $targets,
  String     $filename,
) {

  upload_file("hpeutil/${filename}", "/tmp/${filename}", $targets)

  run_command("esxcli software vib install --depot=/tmp/${filename}", $targets, '_catch_errors' => true)

  run_command("rm /tmp/${filename}", $targets, '_catch_errors' => true)

}

The Bolt plan will upload the bundle file to the ESXi hosts and install the bundle using esxcli. Then it will clean up by removing the bundle file. Notice in the plan file, we have two parameters specified at the beginning, one for targets and one for the filename. This allows us to specify other bundle names rather than just hardcoding the name into the plan. Remember, we are creating tools to reuse. Bolt specializes in creating processes that can be shared with teams to run over and over again. We will also need to save the bundle file to a files folder under the module folder. When running the upload_file command from the plan, Bolt will only look for the file in this folder. If it doesn’t exist it will error:

We will also update our inventory file to include the three hosts we would like to update. In this example, I will be updating esxi1.lukelab.lcl, esxi2.lukelab.lcl, and esxi3.lukelab.lcl :

# Inventory file for Bolt
version: 2
groups:
  - name: esxi
    targets:
      - esxi1.lukelab.lcl
      - esxi2.lukelab.lcl
      - esxi3.lukelab.lcl
    config:
      ssh:
        host-key-check: false
        user: root
        password: 
          _plugin: prompt
          message: Enter your ESXi password

Now for the magic. We run bolt plan to execute our plan and include the filename argument to specify the name of the bundle file to install:

bolt plan run hpeutil::install filename=esxi6.7-util-bundle-3.4.0-11.zip targets=esxi

The bundle file is then transferred to all three ESXi hosts and installed.

Taking It Further

This is a very basic use case of Bolt and is just the beginning. There are many ways that Bolt can be used to orchestrate infrastructure in the VMware environment. We could get even more advanced and orchestrate our install as a canary deployment, where Bolt will install the update on 1 or 2 hosts to test, and if it fails it will stop the plan. There is even a plugin for Terraform that allows Bolt to orchestrate Terraform build. Also, there is a whole community on the Puppet Forge that are creating and sharing their Bolt tasks. For more information on Bolt, be sure to check out the documentation on Puppet’s site. Bolt tasks can also be integrated into Puppet Enterprise with a GUI tool used to run the tasks and also provide restrictions on access to certain tasks. After learning more about Bolt I quickly realized that it’s not the same as writing out scripts with PowerShell remoting, it has a lot more features built-in. It fills in many holes and is a no brainer for VMware administrators that are already running Puppet in their environments.