Bolt Workshop virtual event on May 5th, 2020. The workshop will introduce Bolt, an agentless automation tool from Puppet. Attendees will learn how to use Bolt to run commands, scripts, tasks and plans across Linux and Windows nodes. The document provides an agenda for the workshop including an introduction to Bolt's capabilities and functionality. Links are also provided for workshop files and materials.

1. Bolt Workshop
Virtual
05 May 2020

2. Meet the Team
Presenter:
Thomas Krieger (Senior Sales Engineer, DACH)
thomas.krieger@puppet.com
Moderators:
Keith Apps (Senior Sales Engineer, UK)
keith.apps@puppet.com
Ajay Sridhar (Senior Sales Engineer, UK)
ajay.sridhar@puppet.com
BOLT WORKSHOP2

3. Useful links
VM distribution: https://bit.ly/bw050520vmsheet
Course slides: https://bit.ly/bw050520slides
Solutions and
files download: https://bit.ly/bw050520
Please download the zip archive bw050520.zip and unpack it if not yet done.
It contains the source files, the slides and the solutions for the labs.
3

4. BOLT WORKSHOP4

5. All About Bolt
• Bolt provides a simple way to execute agentless automation against remote hosts
• Zero requirements to the remote host. No agents, no python, no nothing
• Authenticate via SSH, WinRM, PCP
• Execute arbitrary commands, scripts, Bolt Tasks and Bolt Plans
• Use scripts in any language the remote host can execute
• Mature at your own pace from scripts → tasks → plans → puppet code
• If you have Puppet Enterprise, leverage PE from Bolt
BOLT WORKSHOP5

6. bolt command run <cmd> --targets … bolt script run <file> --targets … bolt task run <task> --targets …
6
Version Control
1. Commands
[root /]# systemctl start ntpd[root /]#
PS C:> Start-Service W32Time
2. Scripts
.sh .ps1
3. Tasks
.json
- Description
- Parameters
- Input Validation
+.sh
4. Plans
plan timesync::manage {
run_task ( ‘timesync::reset’, $nodes, default => true )
apply ( $nodes ) {
# some Puppet code here to manage time synchronize
}
run_task ( ‘timesync::restart’, $nodes, force => true )
}
bolt plan run <plan> --targets …

7. BOLT WORKSHOP7
Environment Setup

8. Environment Setup
• Create a Bolt workshop directory (i.e. ~/boltworkshop or c:usersyouboltworkshop)
• Unpack the downloaded bw050520.zip into your Bolt workshop directory. The archive
contains an empty Boltdir directory and files and solutions for several labs.
The bw050520.zip can be downloaded here: https://bit.ly/bw050520
• Copy the ssh key file student.pem from the Lab1 folder in your Bolt playground
directory (with correct permissions!).
• i.e. ~/boltworkshop/Boltdir/student.pem
or
• c:usersyouboltworkshopBoltdirstudent.pem
8

9. Using Bolt
• Bolt command line syntax:
bolt [command|script|task|plan] run <name> --targets <targets> [options]
• To run a simple Bash command on a remote SSH host:
bolt command run 'echo Hello World!' --targets 10.0.0.1,10.0.0.2
--user root --private-key /path/to/key --transport ssh --no-host-key-check
• To run a simple PowerShell command on a remote WinRM host:
bolt command run 'write-host Hello World!' --targets 10.0.0.1,10.0.0.2
--user Administrator --password ‘Puppetlabs!' --transport winrm --no-ssl
BOLT WORKSHOP9

10. BOLT WORKSHOP10
Lab One:
Bolt Command

11. Lab One Instructions (A Long Command For A Ping!)
• Student Bolt Nodes
Linux: bw050520nixN.classroom.puppet.com
Windows: bw050520winN.classroom.puppet.com
• Credentials
Linux: centos / student.pem
Windows: Administrator / Puppetlabs!
• Run these from the command line
bolt command run 'ping 8.8.8.8 -c2' --targets <linux_node>
--user centos --private-key ./Boltdir/student.pem --no-host-key-check
bolt command run 'ping 8.8.8.8 -n 2' --targets <win_node> --user
Administrator --password Puppetlabs! --transport winrm --no-ssl
BOLT WORKSHOP11

12. Easing Bolt Configuration
http://www.puppet.com/docs/bolt
• Bolt provides ways to make common activities more efficient
• Use a bolt.yaml file to store generic settings like modulepath or PE integration
• Use an inventory.yaml file to prevent typing in connection info every time
• Use a Boltdir to bundle all the files you need and have Bolt automatically use it
BOLT WORKSHOP12

13. Bolt Configuration File
• Bolt supports a configuration file to manage default configuration settings
• The configuration file is YAML and can have any name you want
• If unspecified, Bolt will look in these locations for an configuration file
• ./Boltdir/bolt.yaml
• ~/.puppetlabs/bolt/bolt.yaml (~ = %HOMEPATH%)
• A custom configuration file can be specified at runtime with --configfile [full
path]
BOLT WORKSHOP13

14. Bolt Configuration File Syntax
http://www.puppet.com/docs/bolt/latest/bolt_configuration_options.html
modulepath: "/path/one:/path/two:/path/three“
inventoryfile: "~/.puppetlabs/bolt/inventory.yaml“
ssh:
host-key-check: false
winrm:
ssl: false
pcp:
[options]
log:
console: # or /path/to.log
level: info
BOLT WORKSHOP14

15. BOLT WORKSHOP15
Lab Two:
Use Bolt with
bolt.yaml

16. Lab Two Instructions (Making some Defaults)
1. Create a Boltdir directory in your playground folder
2. Create Boltdir/bolt.yaml in your bolt playground folder.
3. add host-key-check: false to SSH section of bolt.yaml and ssl: false to
WinRM section of bolt.yaml
ssh:
host-key-check: false
winrm:
ssl: false
3. Run commands to targets without specifying these 2 options
bolt command run 'ping 8.8.8.8 -c2' --targets <linux_node>
--user centos --private-key ./Boltdir/student.pem
bolt command run 'ping 8.8.8.8 -n 2’ --targets <win_node> --user Administrator
--password Puppetlabs! --transport winrm
BOLT WORKSHOP16

17. Bolt Inventory
• Bolt supports an inventory file to maintain a list of known targets
• The inventory file is YAML and can have any name you want
• If unspecified, Bolt will look in these locations for an inventory file:
• ./Boltdir/inventory.yaml
• ~/.puppetlabs/bolt/inventory.yaml (~ = %HOMEPATH%)
• A custom inventory file can be specified on the command line with --inventoryfile
[full path]
• A custom inventory file can be specified in bolt.yaml with the inventoryfile keyword.
BOLT WORKSHOP17

18. Bolt Inventory
groups:
- name: group_name
targets:
- IP_address_or_name_of_node1
- IP_address_or_name_of_node2
config:
transport: [ ssh | winrm ]
ssh:
user: user_name
run-as: root_name
private-key: /path/to/key
host-key-check: [ true | false ]
winrm:
user: user_name
password: password
ssl: [ true | false ]
BOLT WORKSHOP18
Nesting of groups is allowed:
groups:
- name: top_group
groups:
- name: sub_group
targets:
- …

19. BOLT WORKSHOP19
Lab Three:
Build an
Inventory File

20. Lab Three Reference
1. Create an inventory.yaml in your workshop folder
2. One group for your Linux node, connecting over SSH
3. One group for your Windows node, connecting over WinRM
Reference:
Lab3 folder
Note:
● You’ll need to replace N with your student number in the provided inventory.yaml file.
● Change the settings for the private key according to your needs
BOLT WORKSHOP20

21. BOLT WORKSHOP21
Lab Four:
Use Bolt with
Inventory

22. Lab Four Reference (Using our Inventory)
1. Run bolt command run 'ping 8.8.8.8 -c2' --targets linux
2. Run bolt command run 'ping 8.8.8.8 -n 2' --targets windows
3. Run bolt command run 'hostname' --targets linux,windows
BOLT WORKSHOP22

23. The Boltdir
To assist in packaging Bolt with source code, Bolt supports a Boltdir
When Bolt sees a directory called ./Boltdir it overrides all other configuration
The Boltdir has the following structure:
./Boltdir/bolt.yaml # Configuration settings
./Boltdir/inventory.yaml # Node inventory
./Boltdir/Puppetfile # Additional Forge modules
./Boltdir/modules # Path where modules are installed via Puppetfile
./Boltdir/site # Another modulepath, safe from Puppetfile
./Boltdir/modules/mymod/tasks # Bolt Tasks in module ‘mymod’
./Boltdir/modules/mymod/plans # Bolt Task Plans in module ‘mymod’
BOLT WORKSHOP23

24. Running Scripts
• Bolt will copy the script file to the remote host and run it in the native shell
• Linux = Bash
• Powershell = Windows
• Bolt expects the shell to execute the correct parser (based on file extension)
• You can pass arguments, but Bolt doesn’t do input validation for scripts
bolt script run <script> [[arg1] ... [argN]] [options]
BOLT WORKSHOP24

25. BOLT WORKSHOP25
Lab Five:
Run Scripts with
Bolt

26. Lab Five Instructions (Running a Script)
1. On your laptop, recreate the timesync.ps1 script. You can find it in the Lab5 folder and
copy it from there.
• Place this file above your Boltdir, in your ~/boltworkshop directory
2. From our boltworkshop directory: Use Bolt to run the script on your Windows node
bolt script run timesync.ps1 --targets windows
BOLT WORKSHOP26

27. Scripts into Tasks!
• Make your scripts more useful in Bolt by turning them into Puppet Tasks
• Any script file in a tasks directory of a module becomes a Task
• Tasks are namespaced automatically, using familiar Puppet syntax:
site/mymod/tasks/script1.ps1 # mymod::script1
site/aws/tasks/show_vpc.sh # aws::show_vpc
site/mysql/tasks/sql.rb # mysql::sql
site/yum/tasks/init.rb # yum
BOLT WORKSHOP27

28. BOLT WORKSHOP28
Lab Six:
Convert a Script
to a Task

29. Lab Six Instructions (Turning Scripts into Tasks)
1. Create Boltdir/site/tools/tasks directories
2. Move the timesync.ps1 script into the tasks directory
3. Run bolt task show to verify the new task is available
4. Run bolt task run tools::timesync --targets windows to execute the task.
BOLT WORKSHOP29

30. Bolt Task Metadata
• Make your Tasks more useful and robust by writing metadata files for them
• A metadata file has the same name as the script file, but with a .json extension
• Metadata files using the following (JSON) syntax:
{
"description": "Description of your Puppet Task",
"input_method": "environment | stdin | powershell",
"parameters": {
"param1": {
"description": "Description of the parameter usage",
"type": "String | Enum | Pattern | Integer | Array | Hash | Boolean“
}
}
}
BOLT WORKSHOP30

31. Bolt Task Input Methods
• The chosen input method determines how variables are accessible in the script
"input_method": "environment | stdin | powershell“
• environment: creates environment variable for each parameter as $PT_<variable>
• stdin: creates a JSON hash of all parameters and passes it via stdin
• powershell: creates a PowerShell named argument for each parameter
• The default for Linux is environment and stdin
• The default for Windows is powershell
BOLT WORKSHOP31

32. BOLT WORKSHOP32
Lab Seven:
Create and Run Bolt Task
with Metadata

33. Lab Seven Instructions (Parameterizing Tasks)
1. Retrieve timesync.json from the Lab7 folder and review it
2. Retrieve upgraded timesync.ps1 from Lab7 folder and review it
• Adds a “Restart” Parameter
• Adds an if statement restarting W32Time if Restart is passed
3. Copy timesync.json and timesync.ps1 to ./Boltdir/site/tools/tasks
4. Run bolt task show (Look, we have a description now!)
5. Run bolt task show tools::timesync
6. Run bolt task run tools::timesync -t windows restart=true
BOLT WORKSHOP33

34. Writing Bolt Plans
Bolt Plans can use all the previously covered capabilities, and more, in a single plan.
It’s ideally suited to:
• Orchestrate multiple tasks
• Perform more complex logic & error handling, or interact with Puppet Enterprise
• Combine command/scripts/Tasks with applying desired-state Puppet code
• Plans are stored in a plans directory of a module and have a .pp extension
• Plans must be name spaced according to their module & plan name
BOLT WORKSHOP34

35. Writing Bolt Plans
located in modules/my_mod/plans/my_plan.pp
plan my_mod::my_plan(
String[1] $load_balancer,
TargetSpec $frontends,
TargetSpec $backends
) {
# process frontends
run_task('my_mod::lb_remove', $load_balancer, frontends => $frontends)
run_task('my_mod::update_frontend_app', $frontends, version => '1.2.3’)
run_task('my_mod::lb_add', $load_balancer, frontends => $frontends)
}
BOLT WORKSHOP35

36. Bolt Functions
Puppet Task Plans are written in Puppet DSL, with extra plan-specific functions:
BOLT WORKSHOP36
● add_facts: Add Facts
● add_to_group: Grouping
● apply_prep: Install Agent
● facts: Gather Facts
● fail_plan: Fail Condition
● get_targets: Target Node
● puppetdb_fact: Facts
● puppetdb_query: PQL Query
● run_command: Run Shell
● run_plan: Run a Plan
● run_script: Run a Script
● run_task: Run a Task
● set_feature: Shell/PS/Agent
● set_var: Set a Variable
● upload_file: Upload a File
● vars: Returns Variables
● wait_until_available: Wait
● without_default_logging: Slim
Logs
And More: https://puppet.com/docs/bolt/latest/plan_functions.html

37. Bolt Plan with Functions
plan loop(
TargetSpec $targets
) {
$targets = get_targets($targets)
$certnames = $targets.map |$target| { $target.host }
$targets.each |$target| {
run_task('my_task', $target, certificate => $certnames[$target.host] )
}
}
BOLT WORKSHOP37

38. BOLT WORKSHOP38
Lab Eight:
Create and Run a
Bolt Plan

39. Lab 8 Instructions (Building a Plan)
1. Retrieve timesync.pp from the Lab8 folder and review it
2. Place timesync.pp in Boltdir/site/tools/plans (New Directory)
3. Run bolt plan show
4. Run bolt plan show tools::timesync
5. Run bolt plan run tools::timesync --targets windows
BOLT WORKSHOP39

40. What Now?
• So far, we’ve been using scripting approaches to fix time synchronization issues
• But the script only works on Windows
• If we also built a script for Linux, it wouldn’t look anything like the Windows one
• We don’t want to keep running scripts on systems over and over
• How would we know if we needed to run the script again? Would that even work?
• Surely *someone* has solved this issue already, right?!
BOLT WORKSHOP40

43. Desired State
• To ensure Puppet modules are easy to use, the attributes a module supports for
configuration often align closely to the technology the module manages.
• Time synchronization on Linux and Windows are different enough that the attributes for
one platform are difficult to understand on the other
• It does not often happen that someone builds a fully cross platform module
• A fully cross platform time synchronization module could still emerge at some point, it
will just have to use more generic attributes for configuration and translate those to
each platform as appropriate.
• ^^^ Which is exactly what desired state configuration is all about!
BOLT WORKSHOP43

44. BOLT WORKSHOP44
Lab Nine:
Apply a Puppet
Manifest

45. Lab Nine Instructions (Applying Puppet Code)
• Retrieve Plan manifest from your Lab9 folder, review it and save it as
timesync_windows.pp in your working directory (above Boltdir)
• Run bolt apply timesync_windows.pp --targets windows
NOTE: This lab will fail to complete: Could not find declared class windowstime is the proper
error!
BOLT WORKSHOP45

47. BOLT WORKSHOP47
Lab Ten:
Apply a Puppet
Manifest with a
Puppetfile

48. Lab Ten Instructions (Dependencies, the Puppetfile and You!)
1. Create boltworkshop/Boltdir/Puppetfile
2. Enter in dependencies: Stdlib, Registry, Windowstime and NTP or copy it from the
Lab10 folder
# Modules from the Puppet Forge.
mod 'puppetlabs-stdlib', '5.1.0'
mod 'puppetlabs-registry', '2.1.0'
mod 'ncorrare-windowstime', '0.4.3'
mod 'puppetlabs-ntp', '7.3.0'
3. Run bolt puppetfile install
4. With the modules now installed, let’s try this again:
bolt apply timesync_windows.pp --targets windows
BOLT WORKSHOP48

50. BOLT WORKSHOP50
Lab Eleven:
Cross Platform
Plans

51. Lab Eleven Instructions (Let’s get Multi-Platform!)
1. Retrieve timesync_code.pp from the Lab11 folder, review it and place it in
boltworkshop/Boltdir/site/tools/plans/timesync_code.pp
2. Run bolt plan run tools::timesync_code --targets windows,linux
BOLT WORKSHOP51

52. Recap Time!
We’ve now learned how with Puppet Bolt:
• Commands, scripts, tasks, plans and manifests can be run with Puppet Bolt
• What the natural progression of automation looks like
• Turning interactive commands into scripts
• Turning scripts into tasks
• Turning tasks into plans
• Leveraging existing desired state modules and manifests
• Incorporating desired state code into plans
BOLT WORKSHOP52

53. Connecting to Puppet Enterprise
• To complete the automation journey, all that’s left to do is maturing into PE
• Leverage PE to continuously & automatically enforce desired state code
• Gain auditability in PE on Bolt Tasks, Task Plans and manifests
• Use RBAC in PE to delegate permissions to other teams/coworkers
• Connect Bolt to PE to gain direct control over PE-managed targets
BOLT WORKSHOP53

54. Keith Apps (Senior Sales Engineer, UK)
keith.apps@puppet.com
Thomas Krieger (Senior Sales Engineer, DACH)
thomas.krieger@puppet.com
Ajay Sridhar (Senior Sales Engineer, UK)
ajay.sridhar@puppet.com
Puppet Community Slack
https://slack.puppet.com/
BOLT WORKSHOP54

55. PUPPET OVERVIEW55