Virtual Bolt Workshop - March 16, 2020
Download as PPTX, PDF•0 likes•226 views
This document provides an overview of a Bolt workshop covering the use of Bolt to execute commands, scripts, tasks, plans, and Puppet manifests across Linux and Windows systems. The workshop includes labs on running basic Bolt commands, using Bolt configuration files and inventory, converting scripts to tasks, writing Bolt tasks with metadata, creating and running a Bolt plan, applying a Puppet manifest, and developing a cross-platform Bolt plan. Attendees will learn how to progress from interactive commands to reusable automation using Bolt and leverage existing Puppet modules and desired state configuration. Connecting Bolt automation to Puppet Enterprise is discussed to allow continuous enforcement of infrastructure as code.
![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 WORKSHOP8](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-7-320.jpg)
![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 WORKSHOP12](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-11-320.jpg)
![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 WORKSHOP13](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-12-320.jpg)
![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 WORKSHOP16](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-15-320.jpg)
![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 WORKSHOP17
Nesting of groups is allowed:
groups:
- name: top_group
groups:
- name: sub_group
targets:
- …](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-16-320.jpg)
![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 WORKSHOP23](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-22-320.jpg)
![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 WORKSHOP34](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-33-320.jpg)
![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 WORKSHOP36](https://image.slidesharecdn.com/virtualboltworkshop-public-200312170834/85/Virtual-Bolt-Workshop-March-16-2020-35-320.jpg)
Virtual Bolt Workshop - March 16, 2020
- 1. Bolt Workshop Virtual 11 MARCH 2020
- 2. Meet our Presenter BOLT WORKSHOP2 Ryan Russell-Yates Senior Sales Engineer, Pacific Northwest ● Author of Mastering Puppet 5 ● Puppet User since 2013 ● Puppet Instructor since 2015
- 4. 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 WORKSHOP4
- 6. Environment Setup • Create a Bolt playground directory (i.e. ~/boltworkshop or c:usersyouboltworkshop) • Create a Boltdir within your playground directory (i.e. ~/boltworkshop/Boltdir) • Grab the Linux cert: • Web Browser Method • Visit https://vbolt.classroom.puppet.com/download/student.pem • Log in as client<X>@puppet.com • <X> refers to your student number • Store the contents in your Bolt playground directory as student.pem. • i.e. ~/boltworkshop/Boltdir/student.pem • c:usersyouboltworkshopBoltdir/student.pem BOLT WORKSHOP7
- 7. 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 WORKSHOP8
- 8. BOLT WORKSHOP9 Lab One: Bolt Command
- 9. Lab One Instructions (A Long Command For A Ping!) • Student Bolt Instances Linux: vbolt#nix.classroom.puppet.com Windows: vbolt#win.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 WORKSHOP10
- 10. 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 WORKSHOP11
- 11. 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 WORKSHOP12
- 12. 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 WORKSHOP13
- 13. BOLT WORKSHOP14 Lab Two: Use Bolt with bolt.yaml
- 14. 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 WORKSHOP15
- 15. 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 WORKSHOP16
- 16. 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 WORKSHOP17 Nesting of groups is allowed: groups: - name: top_group groups: - name: sub_group targets: - …
- 17. BOLT WORKSHOP18 Lab Three: Build an Inventory File
- 18. 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: http://bit.ly/vboltinventory Note: ● You’ll need to use your student number in the provided file. Replace # BOLT WORKSHOP19
- 19. BOLT WORKSHOP20 Lab Four: Use Bolt with Inventory
- 20. Lab Four Reference (Using our Inventory) 1. Run bolt command run 'ping 8.8.8.8 -c2’ --targets linux 1. Run bolt command run 'ping 8.8.8.8 -n 2’ --targets windows 1. Run bolt command run 'hostname’ --targets linux,windows BOLT WORKSHOP21
- 21. 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 WORKSHOP22
- 22. 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 WORKSHOP23
- 23. BOLT WORKSHOP24 Lab Five: Run Scripts with Bolt
- 24. Lab Five Instructions (Running a Script) 1. On your laptop, recreate the timesync.ps1 script at http://bit.ly/vbolttimesync • Place this file above your Boltdir, in our ~/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 WORKSHOP25
- 25. 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 name spaced 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 WORKSHOP26
- 26. BOLT WORKSHOP27 Lab Six: Convert a Script to a Task
- 27. Lab Six Instructions (Turning Scripts into Tasks) 1. Create Boltdir/site/tools/tasks 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 WORKSHOP28
- 28. 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 WORKSHOP29
- 29. 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 WORKSHOP30
- 30. BOLT WORKSHOP31 Lab Seven: Create and Run Bolt Task with Metadata
- 31. Lab Seven Instructions (Parameterizing Tasks) 1. Retrieve timesync.json from http://bit.ly/vbolttimesyncjson 2. Retrieve upgraded timesync.ps1 from http://bit.ly/vbolttimesyncrestart • 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 WORKSHOP32
- 32. 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 WORKSHOP33
- 33. 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 WORKSHOP34
- 34. Bolt Functions Puppet Task Plans are written in Puppet DSL, with extra plan-specific functions: BOLT WORKSHOP35 ● 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
- 35. 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 WORKSHOP36
- 36. BOLT WORKSHOP37 Lab Eight: Create and Run a Bolt Plan
- 37. Lab 8 Instructions (Building a Plan) 1. Retrieve http://bit.ly/vbolttimesyncplan 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 WORKSHOP38
- 38. Desired State 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 WORKSHOP39
- 41. Desired State What Now? • 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 WORKSHOP42
- 42. BOLT WORKSHOP43 Lab Nine: Apply a Puppet Manifest
- 43. Lab Nine Instructions (Applying Puppet Code) • Retrieve Plan manifest from http://bit.ly/timesyncmanifest and save it as timesync_windows.pp in your working directory (above Boltdir) • 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 WORKSHOP44
- 45. BOLT WORKSHOP46 Lab Ten: Apply a Puppet Manifest with a Puppetfile
- 46. Lab Ten Instructions (Dependencies, the Puppetfile and You!) 1. Create boltworkshop/Boltdir/Puppetfile 1. Enter in dependencies: Stdlib, Registry, Windowstime and NTP # 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' 1. bolt puppetfile install 2. With the modules now installed, let’s try this again: bolt apply timesync_windows.pp --targets windows BOLT WORKSHOP47
- 48. BOLT WORKSHOP49 Lab Eleven: Cross Platform Plans
- 49. Lab Eleven Instructions (Let’s get Multi-Platform!) 1. Retrieve http://bit.ly/vboltmultiplatform and place it in boltworkshop/Boltdir/site/tools/plans/timesync_code.pp 2. Run bolt plan run tools::timesync_code --targets windows,linux BOLT WORKSHOP50
- 50. 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 WORKSHOP51
- 51. 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 WORKSHOP52
- 52. BOLT WORKSHOP53 Bolt in the Wild