Writing tasks

You use a task name to interact with a task from the Bolt command line. For example, you can use bolt task run puppet_agent::version --targets localhost to run the puppet_agent::version task.

Task names are composed of one or two name segments, indicating:

• The name of the module where the task is located.

• The name of the task file, without the extension.

For example, in the puppetlabs/mysql module, the sql task is located at ./mysql/tasks/sql.rb, so the task name is mysql::sql.

You can write tasks in any language that runs on the targets. Give task files the extension for the language they are written in (such as .rb for Ruby), and place them in the top level of your module's ./tasks directory.

Each task or plan name segment must begin with a lowercase letter and:

• Can include digits.

• Can include underscores.

• Namespace segments must match the regular expression: \A[a-z][a-z0-9_]*\Z.

• The file extension must not use the reserved extensions .md or .json.

Note: The task filename init is special: the task it defines is referenced using the module name only. For example, in the puppetlabs-service module, the task defined in init.rb is the service task.

Task metadata files describe task parameters, validate input, and control how Bolt executes the task.

Your task must have metadata to be published and shared on the Forge. Specify task metadata in a JSON file with the naming convention <TASKNAME>.json. Place this file in the module's ./tasks folder along with your task file.

For example, the module puppetlabs/mysql includes the mysql::sql task with the metadata file, sql.json.

{
  "description": "Allows you to execute arbitrary SQL",
  "input_method": "stdin",
  "parameters": {
    "database": {
      "description": "Database to connect to",
      "type": "Optional[String[1]]"
    },
    "user": {
      "description": "The user",
      "type": "Optional[String[1]]"
    },
    "password": {
      "description": "The password",
      "type": "Optional[String[1]]",
      "sensitive": true
    },
     "sql": {
      "description": "The SQL you want to execute",
      "type": "String[1]"
    }
  }
}

Tasks can receive input as either environment variables, a JSON hash on standard input, or as PowerShell arguments. By default, Bolt submits parameters as both environment variables and as JSON on stdin. Environment variables work well for simple JSON types such as strings and numbers. For arrays and hashes, use structured input instead, because parameters with undefined values (nil, undef) passed as environment variables have the String value null. For more information, see Structured input and output.

To add a parameter to your task as an environment variable, pass the argument prefixed with the Puppet task prefix PT_.

For example, to add a message parameter to your task, read it from the environment in task code as PT_message. When a user runs the task, they can specify the value for the parameter on the command line as message=hello, and the task runner submits the value hello to the PT_message variable.

#!/usr/bin/env bash
echo your message is $PT_message

If your task must receive parameters only in a certain way, such as only stdin, you can set the input method in your task metadata using input_method. For more information on input_method, see Task metadata reference.

If you have a task that has many options, returns a lot of information, or is part of a task plan, consider using structured input and output with your task.

The task API is based on JSON. Task parameters are encoded in JSON, and the task runner attempts to parse the output of the tasks as a JSON object.

Bolt can inject keys into that object, prefixed with _. If the task does not return a JSON object, Bolt creates one and places the output in an _output key.

Tasks support no-operation functionality, also known as no-op mode. This function shows what changes the task would make, without actually making those changes.

No-op support allows a user to pass the --noop flag with a command to test whether the task will succeed on all targets before making changes.

To support no-op, your task must include code that looks for the _noop metaparameter.

If the user passes the --noop flag with their command, this parameter is set to true, and your task must not make changes. You must also set supports_noop to true in your task metadata or Bolt will refuse to run the task in noop mode.

In most cases, tasks are developed for a single platform and consist of a single executable with or without a corresponding metadata file. For instance, ./mysql/tasks/sql.rb and ./mysql/tasks/sql.json. In this case, no other ./mysql/tasks/sql.* files can exist.

A task can have multiple implementations, with metadata that explains when to use each one. A primary use case for this is to support different implementations for different target platforms, referred to as cross-platform tasks.

For instance, consider a module with the following files:

- tasks
  - sql_linux.sh
  - sql_linux.json
  - sql_windows.ps1
  - sql_windows.json
  - sql.json

This task has a task metadata file (sql.json), two implementation metadata files (sql_linux.json, and sql_windows.json), and two executables (sql_linux.sh and sql_windows.ps1). The implementation metadata files document how to use the implementation directly, or mark the implementation as private to hide it from UI lists.

For example, the sql_linux.json implementation metadata file contains the following:

{
  "name": "SQL Linux",
  "description": "A task to perform sql operations on linux targets",
  "private": true
}

The task metadata file, sql.json, contains an implementations section:

{
  "implementations": [
    {"name": "sql_linux.sh", "requirements": ["shell"]},
    {"name": "sql_windows.ps1", "requirements": ["powershell"]}
  ]
}

Each implementations has a name and a list of requirements. Task requirements correspond directly to Bolt features. A feature must be available on the target in order for Bolt to use an implementation. You can specify additional features for a target using the set_feature function in a Bolt plan, or by adding features to your inventory file. Bolt chooses the first implementation whose requirements are satisfied.

Bolt defines the following features by default:

• puppet-agent: Present if the target has the Puppet agent package installed. This feature is automatically added to hosts with the name localhost.

• shell: Present if the target has a POSIX shell.

• powershell: Present if the target has PowerShell.

In the above example, the sql_linux.sh implementation requires the shell feature, and the sql_windows.ps1 implementation requires the PowerShell feature.

Some targets are hard or impossible to execute tasks on directly. In these cases, you can write a task that runs on a proxy target and remotely interacts with the real target.

For example, a network device might have a limited shell environment or a cloud service might be driven only by HTTP APIs. By writing a remote task, Bolt allows you to specify connection information for remote targets in their inventory file and injects them into the _target metaparameter.

This example shows how to write a task that posts messages to Slack and reads connection information from inventory.yaml:

#!/usr/bin/env ruby
# modules/slack/tasks/message.rb

require 'json'
require 'net/http'

params = JSON.parse(STDIN.read)
# the slack API token is passed in from inventory
token = params['_target']['token']
    
uri = URI('https://slack.com/api/chat.postMessage')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri, 'Content-type' => 'application/json')
req['Authorization'] = "Bearer #{params['_target']['token']}"
req.body = { channel: params['channel'], text: params['message'] }.to_json

resp = http.request(req)

puts resp.body

To prevent accidentally running a normal task on a remote target and breaking its configuration, Bolt won't run a task on a remote target unless its metadata defines it as remote:

{
  "remote": true
}

Add Slack as a remote target in your inventory file:

targets:
  - name: my_slack
    config:
      transport: remote
      remote:
        token: <SLACK_API_TOKEN>

Finally, make my_slack a target that can run the slack::message:

bolt task run slack::message --targets my_slack message="hello" channel=<slack channel id>

To convert an existing script to a task, you can either write a task that wraps the script, or you can add logic in your script to check for parameters in environment variables.

If the script is already installed on the targets, you can write a task that wraps the script. In the task, read the script arguments as task parameters and call the script, passing the parameters as the arguments.

If the script isn't installed, or you want to make it into a cohesive task so that you can manage its version with code management tools, add code to your script to check for the environment variables, prefixed with PT_, and read them instead of arguments.

Given a script that accepts positional arguments on the command line:

version=$1
[ -z "$version" ] && echo "Must specify a version to deploy && exit 1

if [ -z "$2" ]; then
  filename=$2
else
  filename=~/myfile
fi

To convert the script into a task, replace this logic with task variables:

version=$PT_version #no need to validate if we use metadata
if [ -z "$PT_filename" ]; then
  filename=$PT_filename
else
  filename=~/myfile
fi

Caution: If you intend to use a task with Puppet Enterprise and assign RBAC permissions, make sure the script safely handles parameters, or validate them to prevent shell injection vulnerabilities.

Multiple task implementations can refer to the same executable file.

Executables can access the _task metaparameter, which contains the task name. For example, the following creates the tasks service::stop and service::start, which live in the executable but appear as two separate tasks.

myservice/tasks/init.rb

#!/usr/bin/env ruby
require 'json'

params = JSON.parse(STDIN.read)
action = params['action'] || params['_task']
if ['start',  'stop'].include?(action)
  `systemctl #{params['_task']} #{params['service']}`
end

myservice/tasks/start.json

{
  "description": "Start a service",
  "parameters": {
    "service": {
      "type": "String",
      "description": "The service to start"
    }
  },
  "implementations": [
    {"name": "init.rb"}
  ]
}

myservice/tasks/stop.json

{
  "description": "Stop a service",
  "parameters": {
    "service": {
      "type": "String",
      "description": "The service to stop"
    }
  },
  "implementations": [
    {"name": "init.rb"}
  ]
}

Multiple tasks can share common files between them. Tasks can additionally pull library code from other modules.

To create a task that includes additional files pulled from modules, include the files property in your metadata as an array of paths. A path consists of:

• The module name.

• One of the following directories within the module:

  • files — Most helper files. This prevents the file from being treated as a task or added to the Puppet Ruby load path.

  • tasks — Helper files that can be called as tasks on their own.

  • lib — Ruby code that might be reused by types, providers, or Puppet functions.

  • scripts — Scripts that can be called from a task.

• The remaining path to a file or directory; directories must include a trailing slash /.

All path separators must be forward slashes. For example, stdlib/lib/puppet/.

You can include the files property as a top-level metadata property and as a property of an implementation, for example:

{
  "implementations": [
    {"name": "sql_linux.sh", "requirements": ["shell"], "files": ["mymodule/files/lib.sh"]},
    {"name": "sql_windows.ps1", "requirements": ["powershell"], "files": ["mymodule/files/lib.ps1"]}
  ],
  "files": ["emoji/files/emojis/"]
}

When a task includes the files property, all files listed in the top-level property and in the specific implementation chosen for a target are copied to a temporary directory on the target. The directory structure of the specified files is preserved so that paths specified with the files metadata option are available to tasks prefixed with _installdir. The task executable itself is located in its module location under the _installdir as well, so other files can be found at ../../mymodule/files/ relative to the location of the task executable.

For example, you can create a task and metadata in a module at ~/.puppetlabs/bolt/site-modules/mymodule/tasks/task.{json,rb}.

Metadata

{
  "files": ["multi_task/files/rb_helper.rb"]
}

File resource

multi_task/files/rb_helper.rb

def useful_ruby
  { helper: "ruby" }
end

Task

#!/usr/bin/env ruby
require 'json'

params = JSON.parse(STDIN.read)
require_relative File.join(params['_installdir'], 'multi_task', 'files', 'rb_helper.rb')
# Alternatively use relative path
# require_relative File.join(__dir__, '..', '..', 'multi_task', 'files', 'rb_helper.rb')
puts useful_ruby.to_json

Output

Started on localhost...
Finished on localhost:
  {
    "helper": "ruby"
  }
Successful on 1 target: localhost
Ran on 1 target in 0.12 seconds

Use secure coding practices when you write tasks and help protect your system.

Note: The information in this topic covers basic coding practices for writing secure tasks. It is not an exhaustive list.

One of the methods attackers use to gain access to your systems is remote code execution, where they are able to gain access to other parts of your system and make arbitrary changes by running an allowed script. Because Bolt executes scripts across your infrastructure, it is important to be aware of certain vulnerabilities, and to code tasks in a way that guards against remote code execution.

Adding task metadata that validates input is one way to reduce vulnerability. When you require an enumerated (enum) or other non-string types, you prevent improper data from being entered. An arbitrary string parameter does not have this assurance.

For example, if your task has a parameter that selects from several operational modes that are passed to a shell command, instead of

String $mode = 'file'

use

Enum[file,directory,link,socket] $mode = file

If your task has a parameter that identifies a file on disk, ensure that a user can't specify a relative path that takes them into areas where they shouldn't be. Reject file names that have slashes.

Instead of

String $path

use

Pattern[/\A[^\/\\]*\z/] $path

In addition to these task restrictions, different scripting languages each have their own ways to validate user input.

There are several ways that you can debug tasks, including using remote debugging libraries, using methods available in the task helper libraries, running the task locally as a script, and redirecting stderr to stdout.