Writing plans in Puppet language

Name plans according to the module name, file name, and path to ensure 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. Use teh plan name to refer to the plan when you run commands.

The plan filename init is special because 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 don't 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.

• Can include lowercase letters, digits, or underscores.

• Must not be a reserved word.

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

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

RBAC for plans is distinct from RBAC for individual tasks. This distinction means that a user can be excluded from running a certain task, but still have permission to run a plan that contains that task.

The RBAC structure for plans 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, you can wrap a task in a plan and only allow them to run it under circumstances you control.

For example, if you are configuring permissions for a new user to run plan infra::upgrade_git, you can allow them to run the package task but limit it to the git package only.

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

plan infra::upgrade_git (
  TargetSpec $targets,
  Enum['1:2.17.0-1ubuntu1', '1:2.17.1-1ubuntu0.4'] $version,
) {
  run_task(‘package’, $targets, 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 plan parameters to do things like determine which targets to run different parts of your plan on. You can pass a parameter as a single target name, comma-separated list of target names, Target data type, or array. The target names can be either certnames or inventory node names.

The example plan below shows the target parameters $load_balancers and $webservers specified as data type TargetSpec. The plan then calls the run_task function to specify which targets 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 so that 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.

puppet plan run mymodule::myplan 
load_balancer=lb.myorg.com 
webservers='["kermit.myorg.com","gonzo.myorg.com"]'

curl -k -X POST -H "Content-Type: application/json" \
-H "X-Authentication:$TOKEN" \
-d '{ "environment": "$ENV", "plan_name": "mymodule::myplan", \
"params": {"targets": "$TARGET_NAME", "load_balancer": "lb.myorg.com", \
"webservers": ["kermit.myorg.com", "gonzo.myorg.com"]} }' \
"https://$PRIMARY_HOST:8143/orchestrator/v1/command/plan_run"

plan test::parameter_passing (
  TargetSpec $targets,
  Optional[String[1]] $example_nul = undef,
) {
  return run_task('test::demo_undef_bash', $targets, 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.

curl -k -X POST -H "Content-Type: application/json" -H 
"X-Authentication:$TOKEN" -d '{ "environment": "$ENV", 
"plan_name": "test::parameter_passing", "params": {"targets": 
"$TARGET_NAME"} }'
"https://$PRIMARY_HOST:8143/orchestrator/v1/command/plan_run"

Use the lookup() function in plans to look up Hiera data. You can look up data inside or outside of apply blocks, or use the plan_hierarchy key to look up data both inside and outside apply blocks within the same plan.

Inside apply blocks, PE compiles catalogs for each target and has unlimited access to your Hiera data. You can use the same Hiera configuration, data, and lookup process as you do throughout PE.

Outside apply blocks, the plan executes a script, doesn't have a concept of a target or context, and cannot load per-target data. These limitations make some common Hiera features, like interpolating target facts, incompatible with plans in PE outside of apply blocks.

You can look up static Hiera data outside of apply blocks by adding a plan_hierarchy key to your Hiera configuration at the same level as the hierarchy key. This allows you to look up data inside and outside apply blocks in the same plan, enabling you to use your existing Hiera configuration in plans without encountering an error if per-target interpolations exist and your plan tries to look up data outside an apply block.

Static Hiera data is also useful for user-specific data that you want the plan to look up.

version: 5
hierarchy:
  - name: "Target specific data"
    path: "targets/%{trusted.certname}.yaml"
  - name: "Per-OS defaults"
    path: "os/%{facts.os.family}.yaml"
  - name: Common
    path: hierarchy.yaml
 
plan_hierarchy:
  - name: Common
    path: plan_hierarchy.yaml

You can set a user-specific API key in the plan_hierarchy.yaml data file, as well as use Hiera to look up a per-target filepath inside an apply block by using the following pieces of data:

api_key: 12345

confpath: "C:\Program Files\Common Files\mytool.conf"

plan plan_lookup(
  TargetSpec $targets
) {
  $outside_apply = lookup('api_key')
  run_task("make_request", $targets, 'api_key' => $outside_apply)
  $in_apply = apply($targets) {
    file { ${confpath}:
      ensure  => file,
      content => "setting: false"
    }
  }
}

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

The state of a target is stored in the code for the duration of a plan, allowing you to collect facts or set variables for a target and retrieve them later. Target objects must reference a target in the PE inventory. This includes targets connected via the PCP protocol that have puppet-agent installed, or targets in the PE inventory added with either SSH or WinRM credentials or as network devices. Target objects in PE do not have control over their connection information, and the connection info cannot be changed from within a plan.

Because target objects in PE are references, and cannot control their own configuration, accessing target connection info will return empty data.

plan loop(TargetSpec $targets) {
  get_targets($targets).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_targets
    targets:
      - localhost
    vars:
      operatingsystem: windows
    config:
      transport: ssh

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

  $centos_targets = get_targets($targets).filter |$n| { $n.facts['os']['name'] == 'CentOS' }
  $ubuntu_targets = get_targets($targets).filter |$n| { $n.facts['os']['name'] == 'Ubuntu' }
  run_task(centos_task, $centos_targets)
  run_task(ubuntu_task, $ubuntu_targets)
}

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

  $centos_targets = get_targets($targets).filter |$n| { $n.facts['os']['name'] == 'CentOS' }
  $ubuntu_targets = get_targets($targets).filter |$n| { $n.facts['os']['name'] == 'Ubuntu' }
  run_task(centos_task, $centos_targets)
  run_task(ubuntu_task, $ubuntu_targets)
}

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
  $targets = $names.map |$n| { "pcp://${n}" }
  run_task('my_task', $targets)
}

Use the return function to return results that you can use in other plans or save for other uses.

Any plan that does not call the return function returns undef.

For example,

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

The result of a plan must match the PlanResult type alias. This includes JSON types as well as the plan language types, which have well defined JSON.

or

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

Any plan that completes execution without an error is considered successful. There are some specific scenarios that always cause a plan failure, such as calling the fail_plan function.

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

plan test (String[1] $role) {
  $result_or_error = catch_errors(['pe/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
  }
}

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')
}

You can package some common general logic in plans using Puppet language and Ruby functions; however, some functions are not allowed. You can also call plan functions, such as run_task or run_plan, from within a function.

These Puppet language constructs are not allowed in plans:

• 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.

Additionally, there are some nuances of the Puppet language to keep in mind when writing plans:

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

• The --strict=error option is 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 plans in PE.

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

Each execution function, or a function you use to operate on one or more targets, returns a ResultSet. Each target you executed on returns a Result. The apply action returns a ResultSet containing ApplyResult objects.

You can iterate on an instance of ResultSet as if it were an Array[Variant[Result, ApplyResult]]. This means iterative functions like each, map, reduce, or filter work directly on the ResultSet returning each result.

For example, to check if a task ran correctly on all targets, and the check fails if the task fails:

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

You can do iteration and check 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| {
  $target = $result.target.name
  if $result.ok {
    out::message("${target} returned a value: ${result.value}")
  } else {
    out::message("${target} errored with a message: ${result.error.message}")
  }
}

$r = run_command('whoami')
$r.to_data.each |$result_hash| { notice($result_hash['result']['stdout']) } 

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

You can apply manifest blocks, or chunks of Puppet code, to remote systems during plan execution using the apply and apply_prep functions.

You can create manifest blocks that use existing content from the Forge, or use a plan to mix procedural orchestration and action with declarative resource configuration from a block. Most features of the Puppet language are available in a manifest block.

If your plan includes a manifest block, use the apply_prep function in your plan before your manifest block. The apply_prep function syncs and caches plugins and gathers facts by running Facter, making the facts available to the manifest block.

apply_prep($target)
apply($target) { notify { foo: } }

# Preview installing docker as root on $targets.
apply($targets, _catch_errors => true, _noop => true) {
    include 'docker'
}

$results = apply($targets) { ... }
$results.each |$result| {
   out::message($result.report)
}

plan do_thing() {
  apply('node1.example.com') {
    notice("Some data in Hiera: ${lookup('mydata')}")
  }
}

You can view plan run information in log files or printed to a terminal session using the out::message function or built-in Puppet logging functions.

```
  warning('logging text') - logs at warn level
  err('logging text') - logs at error level

  notice('logging text') - logs at info level
  info('logging text') - logs at debug level
  debug('logging text') - logs at trace level
```

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

plan deploy( TargetSpec $targets) {
  without_default_logging() || {
    get_targets($targets).each |$target| {
      run_task(deploy, $target)
    }
  }
}

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

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

Check out some example plans for inspiration when writing your own.