Deploying Bolt Plans

Plans let you link commands, scripts, and tasks, combining them to create powerful workflows. Basically, you can use Puppet's own language or YAML for your plans.

The next example installs an Apache web server on the Docker targets created previously. It also takes care of starting the Apache services and uploads a simple home page. To begin, you need some installation instructions for the Apache web server. In the apache subdirectory, create the plans directory and the install.yaml installation script:

parameters:
    targets:
        type: TargetSpec
steps:
    - name: install_apache
        task: package
        targets: $targets
        parameters:
            action: install
            name: apache2
        description: "Installs Apache"

In the first section of the Bolt plan, you need to define the parameters that your plan will accept. In this example, it is the TargetSpec type, which you use to pass multiple targets to a plan. For the parameters specified in the plan to be used, you need to pass in the --targets option at the command line during execution.

The steps section is where you specify the main part of your plan. In this example, it is named install_apache and uses the Bolt package task to install Apache on the target systems. Bolt makes generous use of these predefined task configurations – in particular, reused tasks are defined there. The plan also defines the actions to be performed (installation) plus the name of the package. Having the install.yaml file in place in the plans subdirectory is important. To run the plan in a container group, use:

bolt plan run apache::install -t containers

The plan is designated by two segments separated by a double colon. The first segment specifies the name of the module in which the plan resides, and the second segment specifies the plan file, but without the file extension. In this example, the plan is located in the Apache modules directory and is named install.yaml. The name of the plan is therefore apache::install.

You can watch your plan running at the console. Typical output is shown in Listing 2.

Starting: plan apache::install
Starting: task package on target1, target2
Finished: task package with 0 failures in 18.00 sec
Finished: plan apache::install in 20.00 sec
Plan completed successfully with no result
KE:

In a practical use case, it makes sense to use Bolt to install Apache on your target systems. The orchestration software offers a solution. To begin, create a script file in which you store the specific startup parameters for the Apache startup process. Drop this script (i.e., start_apache.sh in this example) in the files subdirectory below the Apache module directory. Next, add the following block to your install.yaml file:

- name: start_apache
    script: apache/start_apache.sh
    targets: $targets
    description: "Start Apache Services"

The next time the plan is executed, the Apache install will also start, basically clearing the way to access the various Apache web servers. Note that Bolt assigns port 3000 to the first target, port 3001 to the second, and so on. In this example, the default home page is 127.0.0.1:3000 for the first target.

To store your HTML pages on the various Apache installations, create a simple HTML file, name it index.html, and store it in the /apache/files directory of your plan configuration. Before you can upload, you first need to create a scr parameter of the String type in the parameter configuration. The extended configuration then looks like this:

parameters:
   targets:
      type: TargetSpec
   src:
      type: String

Now extend the steps section, adding the following block of code:

- name: upload_homepage
   upload: $src
   destination: /var/www/html/index.html
   targets: $targets
   description: "Upload the Homepage"

After running the plan again, you should see the new homepage when you access 127. 0.0.1:3000 (i.e., the address of the Apache installation).

Advanced Bolt

One key feature of Bolt is its modules, which bundle plans and tasks into typical workflows to facilitate integration. Another benefit is that you can share the modules with third parties; therefore, you can perform identical actions on external networks. However, if you plan to use elements, note that the functionality of the modules often depends on other modules. If you install the module from the Bolt console, Bolt automatically manages these dependencies for you. To do so, the module is added to the module section of the project configuration file (bolt-project.yaml).

In the next step, Bolt resolves the modules and their dependencies and generates a Puppet file. Do not modify this file. Finally, Bolt installs the modules and dependencies in the module directory (module-dir), which you will find in the Bolt project directory (.modules).

Plugins also simplify orchestration. They support dynamic loading and modification of information at Bolt runtime, which means that Bolt actions can be controlled in a targeted way. You can use three different types of plugins:

• Reference plugins are used to retrieve data from an external source and store the data in a static data object.
• Secret plugins are extensions that provide encryption and decryption facilities.
• Puppet library plugins are used when installing Puppet libraries if the associated plan uses the apply_prep function.

You can control the execution of the plugins with entries in the Bolt configuration files.

Conclusions

Puppet Bolt is an excellent administrative tool for orchestrating typical management tasks. Its strengths lie in its simplicity, flexibility, and ability to do without agents. For administrators who can do without the convenience of a web interface in favor of a powerful environment, Bolt is an exciting tool. However, if the lack of a web interface is an issue for you, check out the "Commercial GUI" box for fundamental details of the commercially licensed Bolt variant.