Plan functions

Sections

Plans can use functions that are built into Bolt and Puppet, or custom functions included in modules. This reference page includes a list of built-in Bolt functions. To see a list of built-in Puppet functions, see Puppet's built-in function reference. To learn how to write custom Puppet functions, see the Puppet documentation on writing functions.

add_facts

Deep merges a hash of facts with the existing facts on a target.

Note: Not available in apply block

add_facts($target, $facts) => Target

This function returns an object with the type Target and accepts the following parameters:

ParameterTypeDescription
targetTargetA target.
factsHashA hash of fact names to values that may include structured facts.

Example usage

Adding facts to a target

add_facts($target, { 'os' => { 'family' => 'windows', 'name' => 'windows' } })

add_to_group

Adds a target to specified inventory group.

Note: Not available in apply block

add_to_group($targets, $group) => Any

This function returns an object with the type Any and accepts the following parameters:

ParameterTypeDescription
targetsTargetSpecA pattern or array of patterns identifying a set of targets.
groupString[1]The name of the group to add targets to.

Example usage

Add new Target to group.

Target.new('foo@example.com', 'password' => 'secret').add_to_group('group1')

Add new target to group by name.

add_to_group('bolt:bolt@web.com', 'group1')

Add an array of targets to group by name.

add_to_group(['host1', 'group1', 'winrm://host2:54321'], 'group1')

Add a comma separated list list of targets to group by name.

add_to_group('foo,bar,baz', 'group1')

apply

Applies a block of manifest code to the targets.

Applying manifest code requires facts to compile a catalog. Targets must also have the Puppet agent package installed to apply manifest code. To prep targets for an apply, call the apply_prep function before the apply function.

To learn more about applying manifest code from a plan, see Applying manifest blocks from a Puppet plan.

Note: The apply function returns a ResultSet object containing ApplyResult objects.

apply($targets, $options, &block) => ResultSet

This function returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
targetsTargetSpecThe targets to apply the Puppet code to.
optionsOptional[Hash]A hash of additional options.
&blockCallableThe manifest code to apply to the targets.

This function accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhen true, returns a ResultSet including failed results, rather than failing the plan.
_descriptionStringAdds a description to the apply block, allowing you to distinguish apply blocks.
_noopBooleanWhen true, applies the manifest block in Puppet no-operation mode, returning a report of the changes it would make while taking no action.
_run_asStringThe user to apply the manifest block as. Only available for transports that support the run-as option.

Example usage

Apply manifest code, logging the provided description.

apply($targets, '_description' => 'Install Docker') {
  include 'docker'
}

Apply manifest code as another user, catching any errors.

$apply_results = apply($targets, '_catch_errors' => true, '_run_as' => 'bolt') {
  file { '/etc/puppetlabs':
    ensure => present
  }
}

apply_prep

Installs the puppet-agent package on targets if needed, then collects facts, including any custom facts found in Bolt's module path. The package is installed using either the configured plugin or the task plugin with the puppet_agent::install task.

Agent installation will be skipped if the target includes the puppet-agent feature, either as a property of its transport (PCP) or by explicitly setting it as a feature in Bolt's inventory.

Note: Not available in apply block

apply_prep($targets, $options) => Any

This function returns an object with the type Any and accepts the following parameters:

ParameterTypeDescription
targetsTargetSpecA pattern or array of patterns identifying a set of targets.
optionsOptional[Hash[String, Data]]Options hash.

This function accepts the following option:

OptionTypeDescription
_required_modulesArrayAn array of modules to sync to the target.

Example usage

Prepare targets by name.

apply_prep('target1,target2')

catch_errors

Catches errors in a given block and returns them. This will return the output of the block if no errors are raised. Accepts an optional list of error kinds to catch.

Note: Not available in apply block

catch_errors($error_types, &block) => Any

This function returns an object with the type Any and accepts the following parameters:

ParameterTypeDescription
error_typesOptional[Array[String[1]]]An array of error types to catch
&blockCallable[0, 0]The block of steps to catch errors on

Example usage

Catch errors for a block

catch_errors() || {
  run_command("whoami", $targets)
  run_command("adduser ryan", $targets)
}

Catch parse errors for a block of code

catch_errors(['bolt/parse-error']) || {
 run_plan('canary', $targets)
 run_plan('other_plan)
 apply($targets) || {
   notify { "Hello": }
 }
}

ctrl::do_until

Repeat the block until it returns a truthy value. Returns the value.

ctrl::do_until($options, &block) => Any

This function returns an object with the type Any and accepts the following parameters:

ParameterTypeDescription
optionsOptional[Hash[String[1], Any]]A hash of additional options.
&blockCallable

This function accepts the following options:

OptionTypeDescription
limitNumericThe number of times to repeat the block.
intervalNumericThe number of seconds to wait before repeating the block.

Example usage

Run a task until it succeeds

ctrl::do_until() || {
  run_task('test', $target, '_catch_errors' => true).ok()
}

Run a task until it succeeds or fails 10 times

ctrl::do_until('limit' => 10) || {
  run_task('test', $target, '_catch_errors' => true).ok()
}

Run a task and wait 10 seconds before running it again

ctrl::do_until('interval' => 10) || {
  run_task('test', $target, '_catch_errors' => true).ok()
}

ctrl::sleep

Sleeps for specified number of seconds.

ctrl::sleep($period) => Undef

This function returns an object with the type Undef and accepts the following parameter:

ParameterTypeDescription
periodNumericTime to sleep (in seconds)

Example usage

Sleep for 5 seconds

ctrl::sleep(5)

download_file

Downloads the given file or directory from the given set of targets and saves it to a directory matching the target's name under the given destination directory. Returns the result from each download. This does nothing if the list of targets is empty.

Note: Existing content in the destination directory is deleted before downloading from the targets.

Note: Not available in apply block

Download a file or directory

download_file($source, $destination, $targets, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
sourceString[1]The absolute path to the file or directory on the target(s).
destinationString[1]The relative path to the destination directory on the local system. Expands relative to <project>/downloads/.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.

Download a file or directory, logging the provided description

download_file($source, $destination, $targets, $description, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
sourceString[1]The absolute path to the file or directory on the target(s).
destinationString[1]The relative path to the destination directory on the local system. Expands relative to <project>/downloads/.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
descriptionStringA description to be output when calling this function.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.

Example usage

Download a file from multiple Linux targets to a destination directory

download_file('/etc/ssh/ssh_config', '~/Downloads', $targets)

Download a directory from multiple Linux targets to a project downloads directory

download_file('/etc/ssh', 'ssh', $targets)

Download a file from multiple Linux targets and compare its contents to a local file

$results = download_file($source, $destination, $targets)

$local_content = file::read($source)

$mismatched_files = $results.filter |$result| {
  $remote_content = file::read($result['path'])
  $remote_content == $local_content
}

Download a file from multiple Linux targets to a destination directory

download_file('/etc/ssh/ssh_config', '~/Downloads', $targets, 'Downloading remote SSH config')

facts

Returns the facts hash for a target.

Using the facts function does not automatically collect facts for a target, and will only return facts that are currently set in the inventory. To collect facts from a target and set them in the inventory, run the facts plan or puppetdb_fact plan.

facts($target) => Hash[String, Data]

This function returns an object with the type Hash[String, Data] and accepts the following parameter:

ParameterTypeDescription
targetTargetA target.

Example usage

Getting facts

facts($target)

fail_plan

Raises a Bolt::PlanFailure exception to signal to callers that the plan failed.

Plan authors should call this function when their plan is not successful. The error may then be caught by another plans run_plan function or in Bolt itself

Note: Not available in apply block

Fail a plan, generating an exception from the parameters

fail_plan($msg, $kind, $details, $issue_code) => Any

This function signature returns an object with the type Any and accepts the following parameters:

ParameterTypeDescription
msgString[1]An error message.
kindOptional[String[1]]An easily matchable error kind.
detailsOptional[Hash[String[1], Any]]Machine-parseable details about the error.
issue_codeOptional[String[1]]Unused.

Fail a plan, generating an exception from an existing Error object

fail_plan($error) => Any

This function signature returns an object with the type Any and accepts the following parameter:

ParameterTypeDescription
errorErrorAn error object.

Example usage

Raise an exception

fail_plan('We goofed up', 'task-unexpected-result', { 'result' => 'null' })

Raise an exception

fail_plan(Error('We goofed up', 'task-unexpected-result', { 'result' => 'null' }))

file::exists

Check if a local file exists using Puppet's Puppet::Parser::Files.find_file() function. This will only check files that are on the machine Bolt is run on.

file::exists($filename) => Boolean

This function returns an object with the type Boolean and accepts the following parameter:

ParameterTypeDescription
filenameStringAbsolute path or Puppet file path.

Example usage

Check a file on disk

file::exists('/tmp/i_dumped_this_here')

check a file from the modulepath

file::exists('example/VERSION')

file::join

Join file paths using ruby's File.join() function.

file::join($*paths) => String

This function returns an object with the type String and accepts the following parameter:

ParameterTypeDescription
*pathsStringThe paths to join.

Example usage

Join file paths

file::join('./path', 'to/files')

file::read

Read a file on localhost and return its contents using ruby's File.read. This will only read files on the machine you run Bolt on.

file::read($filename) => String

This function returns an object with the type String and accepts the following parameter:

ParameterTypeDescription
filenameStringAbsolute path or Puppet file path.

Example usage

Read a file from disk

file::read('/tmp/i_dumped_this_here')

Read a file from the modulepath

file::read('example/VERSION')

file::readable

Check if a local file is readable using Puppet's Puppet::Parser::Files.find_file() function. This will only check files on the machine you run Bolt on.

file::readable($filename) => Boolean

This function returns an object with the type Boolean and accepts the following parameter:

ParameterTypeDescription
filenameStringAbsolute path or Puppet file path.

Example usage

Check a file on disk

file::readable('/tmp/i_dumped_this_here')

check a file from the modulepath

file::readable('example/VERSION')

file::write

Write a string to a file on localhost using ruby's File.write. This will only write files to the machine you run Bolt on. Use write_file() to write to remote targets.

file::write($filename, $content) => Undef

This function returns an object with the type Undef and accepts the following parameters:

ParameterTypeDescription
filenameStringAbsolute path.
contentStringFile content to write.

Example usage

Write a file to disk

file::write('C:/Users/me/report', $apply_result.first.report)

get_resources

Query the state of resources on a list of targets using resource definitions in Bolt's module path. The results are returned as a list of hashes representing each resource.

Requires the Puppet Agent be installed on the target, which can be accomplished with apply_prep or by directly running the puppet_agent::install task. In order to be able to reference types without string quoting (for example get_resources($target, Package) instead of get_resources($target, 'Package')), run the command bolt puppetfile generate-types to generate type references in $Boldir/.resource_types.

Note: Not available in apply block

get_resources($targets, $resources) => ResultSet

This function returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
targetsTargetSpecA pattern or array of patterns identifying a set of targets.
resourcesVariant[String, Type[Resource], Array[Variant[String, Type[Resource]]]]A resource type or instance, or an array of such.

Example usage

Collect resource states for packages and a file

get_resources('target1,target2', [Package, File[/etc/puppetlabs]])

get_target

Get a single target from inventory if it exists, otherwise create a new Target.

Note: Calling get_target('all') returns an empty array.

get_target($name) => Target

This function returns an object with the type Target and accepts the following parameter:

ParameterTypeDescription
nameTargetSpecA Target name.

Example usage

Create a new Target from a URI

get_target('winrm://host2:54321')

Get an existing Target from inventory

get_target('existing-target')

get_targets

Parses common ways of referring to targets and returns an array of Targets.

Note: Not available in apply block

get_targets($names) => Array[Target]

This function returns an object with the type Array[Target] and accepts the following parameter:

ParameterTypeDescription
namesTargetSpecA pattern or array of patterns identifying a set of targets.

Example usage

Resolve a group

get_targets('group1')

Resolve a target URI

get_targets('winrm://host2:54321')

Resolve array of groups and/or target URIs

get_targets(['host1', 'group1', 'winrm://host2:54321'])

Resolve string consisting of a comma-separated list of groups and/or target URIs

get_targets('host1,group1,winrm://host2:54321')

Run on localhost

get_targets('localhost')

out::message

Output a message for the user.

This will print a message to stdout when using the human output format, and print to stderr when using the json output format

Note: Not available in apply block

out::message($message) => Undef

This function returns an object with the type Undef and accepts the following parameter:

ParameterTypeDescription
messageAnyThe message to output.

Example usage

Print a message

out::message('Something went wrong')

parallelize

Map a code block onto an array, where each array element executes in parallel. This function is experimental.

Note: Not available in apply block.

parallelize($data, &block) => Array[PlanResult]

This function returns an object with the type Array[PlanResult] and accepts the following parameters:

ParameterTypeDescription
dataArray[Any]The array to apply the block to.
&blockCallable[Any]

Example usage

Execute two tasks on multiple targets. Once the task finishes on one

target, that target can move to the next step without waiting for the task
to finish on the second target.

prompt

Display a prompt and wait for a response.

Note: Not available in apply block

prompt($prompt, $options) => Variant[String, Sensitive]

This function returns an object with the type Variant[String, Sensitive] and accepts the following parameters:

ParameterTypeDescription
promptStringThe prompt to display.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function accepts the following option:

OptionTypeDescription
sensitiveBooleanDisable echo back and mark the response as sensitive. The returned value will be wrapped by the Sensitive data type. To access the raw value, use the unwrap function (i.e. $sensitive_value.unwrap).

Example usage

Prompt the user if plan execution should continue

$response = prompt('Continue executing plan? [Y\N]')

Prompt the user for sensitive information

$password = prompt('Enter your password', 'sensitive' => true)
out::message("Password is: ${password.unwrap}")

puppetdb_fact

Collects facts based on a list of certnames.

If a node is not found in PuppetDB, it's included in the returned hash with an empty facts hash. Otherwise, the node is included in the hash with a value that is a hash of its facts.

puppetdb_fact($certnames) => Hash[String, Data]

This function returns an object with the type Hash[String, Data] and accepts the following parameter:

ParameterTypeDescription
certnamesArray[String]Array of certnames.

Example usage

Get facts for nodes

puppetdb_fact(['app.example.com', 'db.example.com'])

puppetdb_query

Makes a query to puppetdb using Bolt's PuppetDB client.

puppetdb_query($query) => Array[Data]

This function returns an object with the type Array[Data] and accepts the following parameter:

ParameterTypeDescription
queryVariant[String, Array[Data]]A PQL query. Learn more about Puppet's query language, PQL.

Example usage

Request certnames for all nodes

puppetdb_query('nodes[certname] {}')

remove_from_group

Removes a target from the specified inventory group.

The target is removed from all child groups and all parent groups where the target has not been explicitly defined. A target cannot be removed from the all group.

Note: Not available in apply block

remove_from_group($target, $group) => Any

This function returns an object with the type Any and accepts the following parameters:

ParameterTypeDescription
targetTargetSpecA pattern identifying a single target.
groupString[1]The name of the group to remove the target from.

Example usage

Remove Target from group.

remove_from_group('foo@example.com', 'group1')

Remove failing Targets from the rest of a plan

$result = run_command(uptime, my_group, '_catch_errors' => true)
$result.error_set.targets.each |$t| { remove_from_group($t, my_group) }
run_command(next_command, my_group) # does not target the failing nodes.

resolve_references

Evaluates all _plugin references in a hash and returns the resolved reference data.

resolve_references($references) => Data

This function returns an object with the type Data and accepts the following parameter:

ParameterTypeDescription
referencesDataA hash of reference data to resolve.

Example usage

Resolve a hash of reference data

$references = {
  "targets" => [
    "_plugin" => "terraform",
    "dir" => "path/to/terraform/project",
    "resource_type" => "aws_instance.web",
    "uri" => "public_ip"
  ]
}

resolve_references($references)

resource

Lookup a resource in the target's data.

For more information about resources see the documentation.

Note: The ResourceInstance data type is under active development and is subject to change. You can read more about the data type in the experimental features documentation.

Lookup a resource in the target's data

resource($target, $type, $title) => Optional[ResourceInstance]

This function signature returns an object with the type Optional[ResourceInstance] and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to add resources to. See get_targets.
typeType[Resource]The type of the resource
titleString[1]The title of the resource

Lookup a resource in the target's data, referring to resource as a string

resource($target, $type, $title) => Optional[ResourceInstance]

This function signature returns an object with the type Optional[ResourceInstance] and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to add resources to. See get_targets.
typeString[1]The type of the resource
titleString[1]The title of the resource

Example usage

Get the openssl package resource

$target.apply_prep
$resources = $target.get_resources(Package).first['resources']
$target.set_resources($resources)
$openssl = $target.resource('Package', 'openssl')

run_command

Runs a command on the given set of targets and returns the result from each command execution. This function does nothing if the list of targets is empty.

Note: Not available in apply block

Run a command

run_command($command, $targets, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
commandString[1]A command to run on target.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.
_env_varsHashMap of environment variables to set

Run a command, logging the provided description

run_command($command, $targets, $description, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
commandString[1]A command to run on target.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
descriptionStringA description to be output when calling this function.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.
_env_varsHashMap of environment variables to set

Example usage

Run a command on targets

run_command('hostname', $targets, '_catch_errors' => true)

Run a command on targets

run_command('hostname', $targets, 'Get hostname')

run_plan

Runs the plan referenced by its name. A plan is autoloaded from $MODULEROOT/plans.

Note: Not available in apply block

Run a plan

run_plan($plan_name, $args) => PlanResult

This function signature returns an object with the type PlanResult and accepts the following parameters:

ParameterTypeDescription
plan_nameStringThe plan to run.
argsOptional[Hash]A hash of arguments to the plan. Can also include additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation. This option sets the run-as user for all targets whenever Bolt connects to a target. This is set for all functions in the called plan, including run_plan().

Run a plan, specifying $nodes or $targets as a positional argument

Note: When running a plan with both a $nodes and $targets parameter, and using the second positional argument, the plan will fail.

run_plan($plan_name, $targets, $args) => PlanResult

This function signature returns an object with the type PlanResult and accepts the following parameters:

ParameterTypeDescription
plan_nameStringThe plan to run.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
argsOptional[Hash]A hash of arguments to the plan. Can also include additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation. This option sets the run-as user for all targets whenever Bolt connects to a target. This is set for all functions in the called plan, including run_plan().

Example usage

Run a plan

run_plan('canary', 'command' => 'false', 'targets' => $targets, '_catch_errors' => true)

Run a plan

run_plan('canary', $targets, 'command' => 'false')

run_script

Uploads the given script to the given set of targets and returns the result of having each target execute the script. This function does nothing if the list of targets is empty.

Note: Not available in apply block

Run a script

run_script($script, $targets, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
scriptString[1]Path to a script to run on target. May be an absolute path or a modulename/filename selector for a file in $MODULEROOT/files.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
argumentsArray[String]An array of arguments to be passed to the script.
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.
_env_varsHashMap of environment variables to set

Run a script, logging the provided description

run_script($script, $targets, $description, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
scriptString[1]Path to a script to run on target. May be an absolute path or a modulename/filename selector for a file in $MODULEROOT/files.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
descriptionStringA description to be output when calling this function.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
argumentsArray[String]An array of arguments to be passed to the script.
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.
_env_varsHashMap of environment variables to set

Example usage

Run a local script on Linux targets as 'root'

run_script('/var/tmp/myscript', $targets, '_run_as' => 'root')

Run a module-provided script with arguments

run_script('iis/setup.ps1', $target, 'arguments' => ['/u', 'Administrator'])

Run a script

run_script('/var/tmp/myscript', $targets, 'Downloading my application')

run_task

Runs a given instance of a Task on the given set of targets and returns the result from each. This function does nothing if the list of targets is empty.

Note: Not available in apply block

Run a task

run_task($task_name, $targets, $args) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
task_nameString[1]The task to run.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
argsOptional[Hash[String[1], Any]]A hash of arguments to the task. Can also include additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.
_noopBooleanRun the task in noop mode if available.

Run a task, logging the provided description

run_task($task_name, $targets, $description, $args) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
task_nameString[1]The task to run.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
descriptionOptional[String]A description to be output when calling this function.
argsOptional[Hash[String[1], Any]]A hash of arguments to the task. Can also include additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.
_noopBooleanRun the task in noop mode if available.

Example usage

Run a task as root

run_task('facts', $targets, '_run_as' => 'root')

Run a task

run_task('facts', $targets, 'Gather OS facts')

run_task_with

Runs a given instance of a Task with target-specific parameters on the given set of targets and returns the result from each. This function differs from run_task by accepting a block that returns a Hash of target-specific parameters that are passed to the task. This can be used to send parameters based on a target's attributes, such as its facts, or to use conditional logic to determine the parameters a task should receive for a specific target.

This function does nothing if the list of targets is empty.

Note: Not available in apply block

Note: Not available to targets using the pcp transport

Run a task with target-specific parameters

run_task_with($task_name, $targets, $options, &block) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
task_nameString[1]The task to run.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
optionsOptional[Hash[String[1], Any]]A hash of additional options.
&blockCallable[Target]A block that returns a Hash of target-specific parameters for the task.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_noopBooleanRun the task in noop mode if available.
_run_asStringUser to run as using privilege escalation.

Run a task with target-specific parameters, logging the provided description

run_task_with($task_name, $targets, $description, $options, &block) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
task_nameString[1]The task to run.
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
descriptionOptional[String]A description to be output when calling this function.
optionsOptional[Hash[String[1], Any]]A hash of additional options.
&blockCallable[Target]A block that returns a Hash of target-specific parameters for the task.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_noopBooleanRun the task in noop mode if available.
_run_asStringUser to run as using privilege escalation.

Example usage

Run a task with target-specific parameters as root

run_task_with('my_task', $targets, '_run_as' => 'root') |$t| {
  { 'param1' => $t.vars['var1'],
    'param2' => $t.vars['var2'] }
}

Run a task with target-specific parameters and a description

run_task_with('my_task', $targets, 'Update system packages') |$t| {
  { 'param1' => $t.vars['var1'],
    'param2' => $t.vars['var2'] }
}

set_config

Set configuration options on a target.

Note: Not available in apply block

Note: Only compatible with inventory v2

set_config($target, $key_or_key_path, $value) => Target

This function returns an object with the type Target and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to configure. See get_targets.
key_or_key_pathVariant[String, Array[String]]The configuration setting to update.
valueAnyThe configuration value

Example usage

Set the transport for a target

set_config($target, 'transport', 'ssh')

Set the ssh password

set_config($target, ['ssh', 'password'], 'secret')

Overwrite ssh config

set_config($target, 'ssh', { user => 'me', password => 'secret' })

set_feature

Sets a particular feature to present on a target.

Features are used to determine what implementation of a task should be run. Supported features are:

  • powershell

  • shell

  • puppet-agent

Note: Not available in apply block

set_feature($target, $feature, $value) => Target

This function returns an object with the type Target and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to add features to. See get_targets.
featureStringThe string identifying the feature.
valueOptional[Boolean]Whether the feature is supported.

Example usage

Add the puppet-agent feature to a target

set_feature($target, 'puppet-agent', true)

set_resources

Sets one or more ResourceInstances on a Target. This function does not apply or modify resources on a target.

For more information about resources see the documentation.

Note: The ResourceInstance data type is under active development and is subject to change. You can read more about the data type in the experimental features documentation.

Note: Not available in apply block

Set a single resource from a data hash

set_resources($target, $resource) => Array[ResourceInstance]

This function signature returns an object with the type Array[ResourceInstance] and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to add a resource to. See get_targets.
resourceHashThe resource data hash used to set a resource on the target.

Set a single resource from a ResourceInstance object

set_resources($target, $resource) => Array[ResourceInstance]

This function signature returns an object with the type Array[ResourceInstance] and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to add a resource to. See get_targets.
resourceResourceInstanceThe ResourceInstance object to set on the target.

Set multiple resources from an array of data hashes and ResourceInstance objects

set_resources($target, $resources) => Array[ResourceInstance]

This function signature returns an object with the type Array[ResourceInstance] and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to add resources to. See get_targets.
resourcesArray[Variant[Hash, ResourceInstance]]The resource data hashes and ResourceInstance objects to set on the target.

Example usage

Add a resource to a target from a data hash.

$resource_hash = {
  'type'  => File,
  'title' => '/etc/puppetlabs',
  'state' => { 'ensure' => 'present' }
}

$target.set_resources($resource_hash)

Add a resource to a target from a ResourceInstance object.

$resource_instance = ResourceInstance.new(
  'target' => $target,
  'type'   => File,
  'title'  => '/etc/puppetlabs',
  'state'  => { 'ensure' => 'present' }
)

$target.set_resources($resource_instance)

Add resources from resource data hashes returned from an apply block.

$apply_results = apply($targets) {
  File { '/etc/puppetlabs':
    ensure => present
  }
  Package { 'openssl':
    ensure => installed
  }
}

$apply_results.each |$result| {
  $result.target.set_resources($result.report['resource_statuses'].values)
}

Add resources retrieved with get_resources to a target.

$resources = $target.get_resources(Package).first['resources']
$target.set_resources($resources)

set_var

Sets a variable [ key => value ](# key => value ) for a target.

Note: Not available in apply block

set_var($target, $key, $value) => Target

This function returns an object with the type Target and accepts the following parameters:

ParameterTypeDescription
targetTargetThe Target object to set the variable for. See get_targets.
keyStringThe key for the variable.
valueDataThe value of the variable.

Example usage

Set a variable on a target

$target.set_var('ephemeral', true)

system::env

Get an environment variable.

system::env($name) => Optional[String]

This function returns an object with the type Optional[String] and accepts the following parameter:

ParameterTypeDescription
nameStringEnvironment variable name.

Example usage

Get the USER environment variable

system::env('USER')

upload_file

Uploads the given file or directory to the given set of targets and returns the result from each upload. This function does nothing if the list of targets is empty.

Note: Not available in apply block

Upload a file or directory

upload_file($source, $destination, $targets, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
sourceString[1]A source path, either an absolute path or a modulename/filename selector for a file or directory in $MODULEROOT/files.
destinationString[1]An absolute path on the target(s).
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.

Upload a file or directory, logging the provided description

upload_file($source, $destination, $targets, $description, $options) => ResultSet

This function signature returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
sourceString[1]A source path, either an absolute path or a modulename/filename selector for a file or directory in $MODULEROOT/files.
destinationString[1]An absolute path on the target(s).
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
descriptionStringA description to be output when calling this function.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function signature accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.

Example usage

Upload a local file to Linux targets and change owner to 'root'

upload_file('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, '_run_as' => 'root')

Upload a module file to a Windows target

upload_file('postgres/default.conf', 'C:/ProgramData/postgres/default.conf', $target)

Upload a file

upload_file('/var/tmp/payload.tgz', '/tmp/payload.tgz', $targets, 'Uploading payload to unpack')

vars

Returns a hash of the 'vars' (variables) assigned to a target.

Vars can be assigned through the inventory file or set_var function. Plan authors can call this function on a target to get the variable hash for that target.

vars($target) => Hash[String, Data]

This function returns an object with the type Hash[String, Data] and accepts the following parameter:

ParameterTypeDescription
targetTargetThe Target object to get variables from. See get_targets.

Example usage

Get vars for a target

$target.vars

wait_until_available

Wait until all targets accept connections.

Note: Not available in apply block

wait_until_available($targets, $options) => ResultSet

This function returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
optionsOptional[Hash[String[1], Any]]A hash of additional options.

This function accepts the following options:

OptionTypeDescription
descriptionStringA description for logging. (default: 'wait until available')
wait_timeNumericThe time to wait. (default: 120)
retry_intervalNumericThe interval to wait before retrying. (default: 1)
_catch_errorsBooleanWhether to catch raised errors.

Example usage

Wait for targets

wait_until_available($targets, wait_time => 300)

without_default_logging

Define a block where default logging is suppressed.

Messages for actions within this block will be logged at info level instead of notice, so they will not be seen normally but will still be present when verbose logging is requested.

Note: Not available in apply block

without_default_logging(&block) => Undef

This function returns an object with the type Undef and accepts the following parameter:

ParameterTypeDescription
&blockCallable[0, 0]The block where action logging is suppressed.

Example usage

Suppress default logging for a series of functions

without_default_logging() || {
  notice("Deploying on ${nodes}")
  get_targets($targets).each |$target| {
    run_task(deploy, $target)
  }
}

write_file

Write contents to a file on the given set of targets.

Note: Not available in apply block

write_file($content, $destination, $targets, $options) => ResultSet

This function returns an object with the type ResultSet and accepts the following parameters:

ParameterTypeDescription
contentStringFile content to write.
destinationString[1]An absolute path on the target(s).
targetsTargetSpecA pattern identifying zero or more targets. See get_targets for accepted patterns.
optionsOptional[Hash[String[1], Any]]

This function accepts the following options:

OptionTypeDescription
_catch_errorsBooleanWhether to catch raised errors.
_run_asStringUser to run as using privilege escalation.

Example usage

Write a file to a target

$content = 'Hello, world!'
write_file($content, '/Users/me/hello.txt', $targets)
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.