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
ďŹles download: https://bit.ly/bw050520
Please download the zip archive bw050520.zip and unpack it if not yet done.
It contains the source ďŹles, the slides and the solutions for the labs.
3
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 âŚ
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 ďŹles and solutions for several labs.
The bw050520.zip can be downloaded here: https://bit.ly/bw050520
⢠Copy the ssh key ďŹle 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
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 ConďŹguration
http://www.puppet.com/docs/bolt
⢠Bolt provides ways to make common activities more eďŹcient
⢠Use a bolt.yaml ďŹle to store generic settings like modulepath or PE integration
⢠Use an inventory.yaml ďŹle to prevent typing in connection info every time
⢠Use a Boltdir to bundle all the ďŹles you need and have Bolt automatically use it
BOLT WORKSHOP12
13. Bolt ConďŹguration File
⢠Bolt supports a conďŹguration ďŹle to manage default conďŹguration settings
⢠The conďŹguration ďŹle is YAML and can have any name you want
⢠If unspeciďŹed, Bolt will look in these locations for an conďŹguration ďŹle
⢠./Boltdir/bolt.yaml
⢠~/.puppetlabs/bolt/bolt.yaml (~ = %HOMEPATH%)
⢠A custom conďŹguration ďŹle can be speciďŹed at runtime with --configfile [full
path]
BOLT WORKSHOP13
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 ďŹle to maintain a list of known targets
⢠The inventory ďŹle is YAML and can have any name you want
⢠If unspeciďŹed, Bolt will look in these locations for an inventory ďŹle:
⢠./Boltdir/inventory.yaml
⢠~/.puppetlabs/bolt/inventory.yaml (~ = %HOMEPATH%)
⢠A custom inventory ďŹle can be speciďŹed on the command line with --inventoryfile
[full path]
⢠A custom inventory ďŹle can be speciďŹed in bolt.yaml with the inventoryfile keyword.
BOLT WORKSHOP17
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 ďŹle.
â Change the settings for the private key according to your needs
BOLT WORKSHOP20
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 conďŹguration
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 ďŹle 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 ďŹle extension)
⢠You can pass arguments, but Bolt doesnât do input validation for scripts
   bolt script run <script> [[arg1] ... [argN]] [options]
BOLT WORKSHOP24
26. Lab Five Instructions (Running a Script)
1. On your laptop, recreate the timesync.ps1 script. You can ďŹnd it in the Lab5 folder and
copy it from there.
⢠Place this ďŹle 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 ďŹle 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
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 ďŹles for them
⢠A metadata ďŹle has the same name as the script ďŹle, but with a .json extension
⢠Metadata ďŹles 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
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-speciďŹc 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
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 ďŹx 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
41.
42.
43. Desired State
⢠To ensure Puppet modules are easy to use, the attributes a module supports for
conďŹguration often align closely to the technology the module manages.Â
⢠Time synchronization on Linux and Windows are diďŹerent enough that the attributes for
one platform are diďŹcult 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 conďŹguration and translate those to
each platform as appropriate.
⢠     ^^^ Which is exactly what desired state conďŹguration is all about!
BOLT WORKSHOP43
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 ďŹnd declared class windowstime is the proper
error!
BOLT WORKSHOP45
48. Lab Ten Instructions (Dependencies, the PuppetďŹle and You!)
1. Create boltworkshop/Boltdir/PuppetďŹle
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
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