Writing plans in Puppet Language

It is important to name plans correctly according to the module name, file name, and path to ensure easy code readability.

Plan names are composed of two or more name segments, indicating:

For example, given a module called mymodule with a plan defined in ./mymodule/plans/myplan.pp, the plan name is mymodule::myplan.

A plan defined in ./mymodule/plans/service/myplan.pp would be mymodule::service::myplan. This name is how you refer to the plan when you run commands.

The plan filename init is special: the plan it defines is referenced using the module name only. For example, in a module called mymodule, the plan defined in init.pp is the mymodule plan.

Avoid giving plans the same names as constructs in the Puppet language. Although plans do not share their namespace with other language constructs, giving plans these names makes your code difficult to read.

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

• May include lowercase letters.

• May include digits.

• May include underscores.

• Must not be a reserved word.

• Must not have the same name as any Puppet data types.

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

Take user permissions into consideration when writing plans by understanding how RBAC for plans works.

RBAC for plans is separate from RBAC for individual tasks. This means that a user can be excluded from running a certain task, but still have permission to run a plan that contains that task. Setting one permission does not affect the other.

This structure allows you to write plans with more robust, custom control over task permissions. Instead of allowing a user free rein to run a task that can potentially damage your infrastructure under the right conditions, you can wrap a task in a plan and only allow them to run it under circumstances you can control.

For example, say you are configuring permissions for a new user and allow them to run the plan plan infra::upgrade_git:

plan infra::upgrade_git (
  TargetSpec $nodes,
  Integer $version,
) {
  run_task(‘package’, $nodes, name => ’git’, action => ‘upgrade’, version => $version)
}

Within this plan, they can run the package task, but can only interact with the git package. The plan does not allow them to use any other parameters for the package task.

Even though they can run this plan, they do not have access to individually run the package task outside of this plan unless you grant them permission to do so. In that case, they would have the option to add any parameters they want to the task.

plan infra::upgrade_git (
  TargetSpec $nodes,
  Enum['1:2.17.0-1ubuntu1', '1:2.17.1-1ubuntu0.4'] $version,
) {
  run_task(‘package’, $nodes, name => ‘git’, action => ‘upgrade’, version => $version)
}

plan infra::upgrade_git (
   Enum['1:2.17.0-1ubuntu1', '1:2.17.1-1ubuntu0.4'] $version,
) {
  # Use puppetdb to find the nodes from the “other” team's web cluster
  $query = [from, nodes, ['=', [fact, cluster], "other_team"]]
  $selected_nodes = puppetdb_query($query).map() |$target| {
    $target[certname]
  }
  run_task(‘package’, $selected_nodes, name => ‘git’, action => ‘upgrade’, version => $version)
}

Specify parameters within your plan.

Specify each parameter in your plan with its data type. For example, you might want parameters to specify which nodes to run different parts of your plan on.

The following example shows node parameters specified as data type TargetSpec. This allows this parameter to be passed as a single URL, comma-separated URL list, Target data type, or Array of either. For more information about these data types, see the common data types table in the related metadata type topic.

This allows the user to pass, for each parameter, either a node name or a URI that describes the protocol to use, the hostname, username, and password.

The plan then calls the run_task function, specifying which nodes to run the tasks on. The Target names are collected and stored in $webserver_names by iterating over the list of Target objects returned by get_targets. Task parameters are serialized to JSON format; therefore, extracting the names into an array of strings ensures that the webservers parameter is in a format that can be converted to JSON.

plan mymodule::my_plan(
  TargetSpec $load_balancer,
  TargetSpec  $webservers,
) {

  # Extract the Target name from $webservers
  $webserver_names = get_targets($webservers).map |$n| { $n.name }
  
  # process webservers
  run_task('mymodule::lb_remove', $load_balancer, webservers => $webserver_names)
  run_task('mymodule::update_frontend_app', $webservers, version => '1.2.3')
  run_task('mymodule::lb_add', $load_balancer, webservers => $webserver_names)
 }

To execute this plan from the command line, pass the parameters as parameter=value. The Targetspec accepts either an array as json or a comma separated string of target names.

bolt plan run mymodule::myplan --modulepath ./PATH/TO/MODULES load_balancer=lb.myorg.com webservers='["kermit.myorg.com","gonzo.myorg.com"]'
        

Parameters that are passed to the run_* plan functions are serialized to JSON.

plan test::parameter_passing (
  TargetSpec $nodes,
  Optional[String[1]] $example_nul = undef,
) {
  return run_task('test::demo_undef_bash', $nodes, example_nul => $example_nul)
     }

#!/bin/bash
example_env=$PT_example_nul
echo "Environment: $PT_example_nul"
echo "Stdin:" 
     cat -

By default, the task expects parameters passed as a JSON string on stdin to be accessible in prefixed environment variables.

bolt@bolt: bolt plan run test::parameter_passing -n localhost
Starting: plan test::parameter_passing
Starting: task test::demo_undef_bash on localhost
Finished: task test::demo_undef_bash with 0 failures in 0.0 sec
Finished: plan test::parameter_passing in 0.01 sec
Finished on localhost:
  Environment: null
  Stdin:
  {"example_nul":null,"_task":"test::demo_undef_bash"}
  {
  }
Successful on 1 node: localhost
     Ran on 1 node

The parameters example_nul and _task metadata are passed to the task as a JSON string over stdin.

Similarly, parameters are made available to the task as environment variables where the name of the parameter is converted to an environment variable prefixed with PT_. The prefixed environment variable points to the String representation in JSON format of the parameter value. So, the PT_example_nul environment variable has the value of null of type String.

Use plans to return results that you can use in other plans or save for use outside of Bolt

Plans, unlike functions, are primarily run for side effects but they can optionally return a result. To return a result from a plan use the return function. Any plan that does not call the return function returns undef.

plan return_result(
  $nodes
) {
  return run_task('mytask', $nodes)
}

The result of a plan must match the PlanResult type alias. This roughly includes JSON types as well as the Plan language types which have well defined JSON representations in Bolt.

or

Variant[Data, String, Numeric, Boolean, Error, Result, ResultSet, Target, Array[Boltlib::PlanResult], Hash[String, Boltlib::PlanResult]]

To return an error if your plan fails, call the fail_plan function.

Specify parameters to provide details about the failure.

plan mymodule::myplan {
  Error(
    message    => "Sorry, this plan does not work yet.",
    kind       => 'mymodule/error',
    issue_code => 'NOT_IMPLEMENTED'
    )
  }
  fail_plan("Sorry, this plan does not work yet.", 'mymodule/error')
}

There are indicators that a plan has run successfully or failed.

Any plan that completes execution without an error is considered successful. The bolt command exits 0 and any calling plans continue execution. If any calls to run_ functions fail without _catch_errors then the plan halts execution and is considered a failure. Any calling plans also halt until a run_plan call with _catch_errors or a catch_errors block is reached. If one isn't reached, the bolt command performs an exit 2. When writing a plan if you have reason to believe it has failed, you can fail the plan with the fail_plan function. This causes the bolt command to exit 2 and prevents calling plans executing any further, unless run_plan was called with _catch_errors or in a catch_errors block.

fail_plan('The plan is failing', 'mymodules/pear-shaped', {'failednodes' => $result.error_set.names})
# or
fail_plan($errorobject)

plan mymodule::handle_errors {
  $result = run_plan('mymodule::myplan', '_catch_errors' => true)
  case $result {
    Error['mymodule/not-serious'] : {
      notice("${result.message}")
    }
    Error : { fail_plan($result) } }
  run_plan('mymodule::plan2')
}

plan test (String[1] $role) {
  $result_or_error = catch_errors(['bolt/puppetdb-error']) || {
    puppetdb_query("inventory[certname] { app_role == ${role} }")
  }
  $targets = if $result_or_error =~ Error {
    # If the PuppetDB query fails
    warning("Could not fetch from puppet. Using defaults instead")
    # TargetSpec string
    "all"
  } else {
    $result_or_error
  }
}

You can define and call Puppet language and Ruby functions in plans.

This is useful for packaging common general logic in your plan. You can also call the plan functions, such as run_task or run_plan, from within a function.

Not all Puppet language constructs are allowed in plans. The following constructs are not allowed:

• Defined types.

• Classes.

• Resource expressions, such as file { title: mode => '0777' }

• Resource default expressions, such as File { mode => '0666' }

• Resource overrides, such as File['/tmp/foo'] { mode => '0444' }

• Relationship operators: -> <- ~> <~

• Functions that operate on a catalog: include, require, contain, create_resources.

• Collector expressions, such as SomeType <| |>, SomeType <<| |>>

• ERB templates are not supported. Use EPP instead.

Be aware of a few other Puppet behaviors in plans:

• The --strict_variables option is on, so if you reference a variable that is not set, you get an error.

• --strict=error is always on, so minor language issues generate errors. For example { a => 10, a => 20 } is an error because there is a duplicate key in the hash.

• Most Puppet settings are empty and not-configurable when using Bolt.

• Logs include "source location" (file, line) instead of resource type or name.

Each execution function returns an object type ResultSet. For each node that the execution takes place on, this object contains a Result object. The apply action returns a ResultSet containing ApplyResult objects.

A ResultSet has the following methods:

A Result has the following methods:

An ApplyResult has the following methods:

An instance of ResultSet is Iterable as if it were an Array[Variant[Result, ApplyResult]] so that iterative functions such as each, map, reduce, or filter work directly on the ResultSet returning each result.

This example checks if a task ran correctly on all nodes. If it did not, the check fails:

$r = run_task('sometask', ..., '_catch_errors' => true)
unless $r.ok {
  fail("Running sometask failed on the nodes ${r.error_nodes.names}")
}

You can do iteration and checking if the result is an Error. This example outputs feedback about the result of a task:

$r = run_task('sometask', ..., '_catch_errors' => true)
$r.each |$result| {
  $node = $result.target.name
  if $result.ok {
    notice("${node} returned a value: ${result.value}")
  } else {
    notice("${node} errored with a message: ${result.error.message}")
  }
}

$r = run_command('whoami', 'localhost,local://0.0.0.0')
$r.to_data.each |$result_hash| { notice($result_hash['result']['stdout']) } 

$filtered = $result.filter_set |$r| {
  $r['tag'] == "you're it"
}.targets

Task parameters defined as sensitive are masked when they appear in plans.

You define a task parameter as sensitive with the metadata property "sensitive": true. When a task runs, the values for these sensitive parameters are masked.

run_task('task_with_secrets', ..., password => '$ecret!')

$pass = Sensitive('$ecret!')
run_task('task_with_secrets', ..., password => $pass.unwrap)

The Target object represents a node and its specific connection options.

The state of a target is stored in the inventory for the duration of a plan allowing you to collect facts or set vars for a target and retrieve them later. You can get a printable representation via the name function, as well as access components of the target: protocol, host, port, user, password.

plan loop(TargetSpec $nodes) {
  get_targets($nodes).each |$target| {
    run_task('my_task', $target)
  }
}

plan vars(String $host) {
	$target = get_targets($host)[0]
	$target.set_var('newly_provisioned', true)
	$targetvars = $target.vars
	run_command("echo 'Vars for ${host}: ${$targetvars}'", $host)
}

groups:
  - name: my_nodes
    nodes:
      - localhost
    vars:
      operatingsystem: windows
    config:
      transport: ssh

plan run_with_facts(TargetSpec $nodes) {
  # This collects facts on nodes and update the inventory
  run_plan(facts, nodes => $nodes)

  $centos_nodes = get_targets($nodes).filter |$n| { $n.facts['os']['name'] == 'CentOS' }
  $ubuntu_nodes = get_targets($nodes).filter |$n| { $n.facts['os']['name'] == 'Ubuntu' }
  run_task(centos_task, $centos_nodes)
  run_task(ubuntu_task, $ubuntu_nodes)
}

plan run_with_facts(TargetSpec $nodes) {
  # This collects facts on nodes and update the inventory
  run_plan(puppetdb_fact, nodes => $nodes)

  $centos_nodes = get_targets($nodes).filter |$n| { $n.facts['os']['name'] == 'CentOS' }
  $ubuntu_nodes = get_targets($nodes).filter |$n| { $n.facts['os']['name'] == 'Ubuntu' }
  run_task(centos_task, $centos_nodes)
  run_task(ubuntu_task, $ubuntu_nodes)
}

plan pdb_discover {
  $result = puppetdb_query("inventory[certname] { app_role == 'web_server' }")
  # extract the certnames into an array
  $names = $result.map |$r| { $r["certname"] }
  # wrap in url. You can skip this if the default transport is pcp
  $nodes = $names.map |$n| { "pcp://${n}" }
  run_task('my_task', $nodes)
}

Plan run information can be captured in log files or printed to a terminal session using the following methods.

run_task(my_task, $targets, "Better description", param1 => "val")

plan deploy( TargetSpec $nodes) {
  without_default_logging() || {
    get_targets($nodes).each |$node| {
      run_task(deploy, $node)
    }
  }
}

without_default_logging() || { run_command('echo hi', $nodes) }

without_default_logging { run_command('echo hi', $nodes) }

Check out some example plans for inspiration writing your own.