Introduction
In the last post we discussed the motivation behind using Puppet Bolt in your environment and demonstrated how to install Puppet Bolt and run one off ad hoc commands using some of the options provided by the tool. In this post we'll take things a little further from running commands and start creating and running tasks.
What is a task?
Tasks are basically scripts that perform single ad-hoc functions. Tasks can however be orchestrated using plans. All tasks are stored in Puppet modules. In case you do not wish to create your own tasks you could also download them from Puppet forge or GitHub and use them directly. You can also pass arguments to Bolt tasks.
Display available tasks:
Bolt comes with a couple of pre-installed tasks that you could use out of the box. To view a list of available tasks type:
[sahil@bolt-lab ~]$ bolt tasks show
Expected subcommand 'tasks' to be one of command, script, task, plan, file, puppetfile, secret, apply
[sahil@bolt-lab ~]$ bolt task show
facts Gather system facts
package Manage and inspect the state of packages
puppet_agent::install Install the Puppet agent package
puppet_agent::version Get the version of the Puppet agent package installed. Returns nothing if none present.
puppet_conf Inspect puppet agent configuration settings
reboot Reboots a machine
reboot::last_boot_time Gets the last boot time of a Linux or Windows system
service Manage and inspect the state of services
MODULEPATH:
/home/sahil/.puppetlabs/bolt/modules:/home/sahil/.puppetlabs/bolt/site-modules:/home/sahil/.puppetlabs/bolt/site
Use `bolt task show <task-name>` to view details and parameters for a specific task.
[sahil@bolt-lab ~]$
To view information about a particular task just append the task name at the end of the above executed command. Here's an example.
[sahil@bolt-lab ~]$ bolt task show facts
facts - Gather system facts
USAGE:
bolt task run --nodes <node-name> facts
MODULE:
built-in module
[sahil@bolt-lab ~]$
Executing a task:
To demonstrate how to execute tasks, lets take use the service task.
[sahil@bolt-lab ~]$ bolt task show service
service - Manage and inspect the state of services
USAGE:
bolt task run --nodes <node-name> service action=<value> name=<value> provider=<value>
PARAMETERS:
- action: Enum[start, stop, restart, enable, disable, status]
The operation (start, stop, restart, enable, disable, status) to perform on the service.
- name: String[1]
The name of the service to operate on.
- provider: Optional[String[1]]
The provider to use to manage or inspect the service, defaults to the system service manager. Only used when the 'puppet-agent' feature is available on the target so we can leverage Puppet.
MODULE:
built-in module
The above description states that we need to pass the action and name parameters to tell bolt the name of the service we want to work with and the action we want to take on the service. Let's run use the service task to check the status of the nfs service.
[sahil@bolt-lab ~]$ bolt task run --nodes bolt-lab service name=nfs action=status --user sahil
Started on bolt-lab...
Finished on bolt-lab:
{
"status": "MainPID=0,LoadState=loaded,ActiveState=active",
"enabled": "enabled"
}
Successful on 1 node: bolt-lab
Ran on 1 node in 1.45 seconds
[sahil@bolt-lab ~]$
Before we can start writing tasks we need to understand what is a module?
A puppet module consists of self contained code and data residing in a simple file structure. Modules can easily be shared and reused. You could even distribute your own modules as tar.gz files.
Given below are some rules we need to adhere to while creating puppet modules:
-
The directory name of the module is the name of the module itself.
-
It should contain a manifests directory with an init.pp file.
-
The init.pp file must contain a single class definition the same as the module's name.
-
A metadata.json file should be present in the parent directory.
If you do not intend to distribute your modules and use them primarily for running tasks then you could afford to ignore most of the above mentioned rules.
Creating our first task:
Since a module is basically some files arranged in a directory hierarchy, to create a module we just need to create that directory structure.
For our first module and task we'll be keeping things simple and create a very basic script to work with packages using yum.
We'll be naming our task my_pkg. When you run the 'bolt task show' command it'll show you the default directories where Bolt looks for modules. We could use a different directory and then specify that with the --modulepath parameter while using Bolt. but for this demonstration we'll use one of the default ones.
Let's create a directory named my_pkg under one of the default module paths.
[sahil@bolt-lab ~]$ mkdir -p /home/sahil/.puppetlabs/bolt/modules/my_pkg
Now we'll create a tasks sub-directory under this directory to store the tasks that we'll be creating under this module.
[sahil@bolt-lab ~]$ mkdir -p /home/sahil/.puppetlabs/bolt/modules/my_pkg/tasks
I would like to pass some parameters to the task that I'll be creating. To add parameters to your task as environment variables, pass the argument prefixed with the Puppet task prefix PT_ . There are more ways to pass parameters to Puppet tasks but for now we'll stick to this approach using environment variables.
I've created a small bash script named yum in the tasks directory and populated it with the following content:
[sahil@bolt-lab ~]$ cat /home/sahil/.puppetlabs/bolt/modules/my_pkg/tasks/yum.bash
#!/bin/bash
action="$PT_action"
name="$PT_name"
yum $action $name
[sahil@bolt-lab tasks]$
$
To make Bolt aware that we've added a new module and to able to use it, we'll need to install the module. To do that we first need to create a file named Puppetfile that has the following content.
[sahil@bolt-lab ~]$ cat Puppetfile
#Local modules
mod 'my_pkg', local:true
[sahil@bolt-lab ~]$
Before we can use our Puppet file we need to move it to the default Bolt directory.
[sahil@bolt-lab ~]$ mv Puppetfile /home/sahil/.puppetlabs/bolt/
[sahil@bolt-lab ~]$ ls /home/sahil/.puppetlabs/bolt/Puppetfile
/home/sahil/.puppetlabs/bolt/Puppetfile
[sahil@bolt-lab ~]$
To install the module we need to run the below command:
[sahil@bolt-lab ~]$ bolt puppetfile install
Successfully synced modules from /home/sahil/.puppetlabs/bolt/Puppetfile to /home/sahil/.puppetlabs/bolt/modules
[sahil@bolt-lab ~]$
If we run Bolt task show again we will be able to see the my_pkg module defined with the yum task:
[sahil@bolt-lab ~]$ bolt task show
facts Gather system facts
my_pkg::yum
package Manage and inspect the state of packages
puppet_agent::install Install the Puppet agent package
puppet_agent::version Get the version of the Puppet agent package installed. Returns nothing if none present.
puppet_conf Inspect puppet agent configuration settings
reboot Reboots a machine
reboot::last_boot_time Gets the last boot time of a Linux or Windows system
service Manage and inspect the state of services
MODULEPATH:
/home/sahil/.puppetlabs/bolt/modules:/home/sahil/.puppetlabs/bolt/site-modules:/home/sahil/.puppetlabs/bolt/site
Use `bolt task show <task-name>` to view details and parameters for a specific task.
[sahil@bolt-lab ~]$
If we weren't going to pass any parameters to the task then this would be enough. But since we do intend to pass parameters and would like to inform the users about the functionality of the task, we'll add a JSON metadata file in our tasks directory and populate it with the following content:
[sahil@bolt-lab ~]$ cat /home/sahil/.puppetlabs/bolt/modules/my_pkg/tasks/yum.json
{
"description": "Allow users to manipulate software packages using yum",
"parameters": {
"action": {
"description": "Task to perofmr on the package",
"type": "String"
},
"name": {
"description": "The package name",
"type": "String"
}
}
}
Now let's execute the bolt task show command for our my_pkg::yum task.
[sahil@bolt-lab tasks]$ bolt task show my_pkg::yum
my_pkg::yum - Allow users to manipulate software packages using yum
USAGE:
bolt task run --nodes <node-name> my_pkg::yum action=<value> name=<value>
PARAMETERS:
- action: String
Task to perform on the package
- name: String
The package name
MODULE:
/home/sahil/.puppetlabs/bolt/modules/my_pkg
[sahil@bolt-lab tasks]$
Now we are all done with the prep work. Let's run our task.
[sahil@bolt-lab tasks]$ bolt task run --nodes 10.31.19.151 my_pkg::yum action=info name=httpd --user sahil --run-as root
Started on 10.31.19.151...
Finished on 10.31.19.151:
Loaded plugins: fastestmirror
Loading mirror speeds from cached hostfile
* base: mirror.aktkn.sg
* epel: d2lzkl7pfhq30w.cloudfront.net
* extras: mirror.aktkn.sg
* nux-dextop: mirror.li.nux.ro
* updates: mirror.aktkn.sg
Available Packages
Name : httpd
Arch : x86_64
Version : 2.4.6
Release : 89.el7.centos
Size : 2.7 M
Repo : updates/7/x86_64
Summary : Apache HTTP Server
URL : http://httpd.apache.org/
License : ASL 2.0
Description : The Apache HTTP Server is a powerful, efficient, and extensible
: web server.
{
}
Successful on 1 node: 10.31.19.151
Ran on 1 node in 3.03 seconds
[sahil@bolt-lab tasks]$ bolt task run --nodes 10.31.19.151 my_pkg::yum action=list name=httpd --user sahil --run-as root
Started on 10.31.19.151...
Finished on 10.31.19.151:
Loaded plugins: fastestmirror
Loading mirror speeds from cached hostfile
* base: mirror.aktkn.sg
* epel: d2lzkl7pfhq30w.cloudfront.net
* extras: mirror.aktkn.sg
* nux-dextop: mirror.li.nux.ro
* updates: mirror.aktkn.sg
Available Packages
httpd.x86_64 2.4.6-89.el7.centos updates
{
}
Successful on 1 node: 10.31.19.151
Ran on 1 node in 3.60 seconds
As this point the action can only be info or list because I haven't added the -y option with yum to allow for install or erase operations. But we can tweak the script to suit our requirements.
Conclusion
This concludes our article on how to start writing tasks to run using Puppet Bolt. We hope you found it to be useful and look forward towards your feedback and suggestions.
