The steps key is an array of step objects, each of which corresponds to a specific action to take.

When the plan runs, each step is executed in order. If a step fails, the plan halts execution and raises an error containing the result of the step that failed.

Steps use these fields:

• name: (Optional) A unique name that can be used to refer to the result of the step later.

• description: (Optional) An explanation of what the step is doing.

Other available keys depend on the type of step.

Plans accept parameters with the parameters key. The value of parameters is a map, where each key is the name of a parameter and the value is a map describing the parameter.

Parameter values can be referenced from steps as variables.

Parameters use these fields:

• type: (Optional) A valid Puppet data type. The value supplied must match the type or the plan fails.

• default: (Optional) Used if no value is given for the parameter

• description: (Optional)

For example, this plan accepts a load_balancer name as a string, two sets of targets called frontends and backends, and a version string:

parameters:
  # A simple parameter definition doesn't need a type or description
  load_balancer:
  frontends:
    type: TargetSpec
    description: "The frontend web servers"
  backends:
    type: TargetSpec
    description: "The backend application servers"
  version:
    type: String
    description: "The new application version to deploy"

As a plan author, you may not want users to run your plan directly or know it exists. This is useful for plans that are used by other plans 'under the hood', but aren't designed to be run by a human. Plans accept a private key. The value of private is a boolean that tells Bolt whether to display the plan in bolt plan show or Get-BoltPlan output. Private plans are still viewable with bolt plan show <PLAN NAME> and Get-BoltPlan -Name <PLAN NAME>, and can still be run with Bolt.

private: true
parameters:
  targets:
    type: TargetSpec
    description: "The targets to run on"

steps:
  - command: hostname -f
    targets: $targets

The private metadata is cached in your Bolt project. Bolt updates the cache:

• When you update plans in the current Bolt project.

• When you update modules in the <PROJECT DIRECTORY>/modules/ directory.

• When you install modules using a Bolt command that installs modules.

• When you generate Puppet types using a generate command.

If you manually edit a plan that is located outside of the <PROJECT DIRECTORY>/plans/ directory or <PROJECT DIRECTORY>/modules/ path, Bolt might not pick up manual edits to metadata. If your plan still appears in the output of bolt plan show and Get-BoltPlan, clear the metadata cache by running with the --clear-cache flag.

The behavior of strings is defined by how they're written in the plan.

'single-quoted strings' are treated as string literals without any interpolation.

"double-quoted strings" are treated as Puppet language double-quoted strings with variable interpolation.

| block-style strings are treated as expressions of arbitrary Puppet code. Note the string itself must be on a new line after the | character.

bare strings are treated dynamically based on their content. If they begin with a $, they're treated as Puppet code expressions. Otherwise, they're treated as YAML literals.

Here's an example of different kinds of strings in use:

parameters:
  message:
    type: String
    default: "hello"

steps:
  - eval: hello
    description: 'This will evaluate to: hello'
  - eval: $message
    description: 'This will evaluate to: hello'
  - eval: '$message'
    description: 'This will evaluate to: $message'
  - eval: "${message} world"
    description: 'This will evaluate to: hello world'
  - eval: |
      [$message, $message, $message].join(" ")
    description: 'This will evaluate to: hello hello hello'

You can retrieve a value from an Array or a Hash using the [] operator. This operator can also be used when interpolating a value inside a string.

parameters:
  users:
    # Array[String] is a Puppet data type representing an array of strings
    type: Array[String]

steps:
  - task: user::add
    targets: 'host.example.com'
    parameters:
      name: $users[0]
  - task: echo
    targets: 'host.example.com'
    parameters:
      message: "hello ${users[0]}"

You can call a built-in Bolt function or Puppet function to compute a value.

parameters:
  users:
    type: Array[String]

steps:
  - task: user::add
    parameters:
      name: $users.first
  - task: echo
    message: "hello ${users.join(',')}"

Some Puppet functions take a block of code as an argument. For instance, you can filter an array of items based on the result of a block of code.

The result of the filter function is an array here, not a string, because the expression isn't inside quotes.

parameters:
  numbers:
    type: Array[Integer]

steps:
  - task: sum
    description: "add up the numbers > 5"
    parameters:
      indexes: $numbers.filter |$num| { $num > 5 }

The name key makes its result available to later steps in a variable with that name.

This example uses the map function to get the value of stdout from each command result and then joins them into a single string separated by commas.

parameters:
  targets:
    type: TargetSpec

steps:
  - name: hostnames
    command: hostname -f
    targets: $targets
  - task: echo
    parameters:
      message: $hostnames.map |$hostname_result| { $hostname_result['stdout'] }.join(',')

The eval step evaluates an expression and saves the result in a variable. This is useful to compute a variable to use multiple times later.

parameters:
  count:
    type: Integer

steps:
  - name: double_count
    eval: $count * 2
  - task: echo
    targets: web1.example.com
    parameters:
      message: "The count is ${count}, and twice the count is ${double_count}"

You can see the results for the following types of steps by running the plan with the --verbose CLI option:

• commands

• scripts

• plans

• tasks

You can print the result of a step to stdout by passing the step name to a message step as a parameter.

To print the result of a step to stdout using message, use the following structure:

- message: $<STEP_NAME> 

For example, the following plan uses a task step named check_mysql to run the package task and check for MySQL. A message step prints the result of the check_mysql task:

parameters:
  targets:
    type: TargetSpec   

steps:
  - name: check_mysql
    targets: $targets
    task: package
    parameters:
     action: status
     name: mysql
    description: "Check for MySQL"

  - message: $check_mysql

The output from this plan looks something like this:

Starting: plan wordpress::test
Starting: Check for MySQL on target1
Finished: Check for MySQL with 0 failures in 0.59 sec
[
  {
    "target": "target1",
    "action": "task",
    "object": "package",
    "status": "success",
    "value": {
      "status": "uninstalled",
      "version": ""
    }
  }
]
Finished: plan wordpress::test in 0.6 sec
Plan completed successfully with no result

Bolt logs additional information about a plan run, including output sent to standard error (stderr), at the debug level. Use the --log-level debug CLI option or the log configuration setting.

$ bolt task run mytask param1=foo param2=bar -t all --log-level debug

Each time you run a Bolt command, Bolt prints a debug level log to a bolt-debug.log file in the root of your project directory. You can disable the log file by specifying the following in your bolt-project.yaml:

log:
  bolt-debug.log: disable

The eval step allows snippets of Puppet code to be expressed in YAML plans. When converting a multi-line eval step to Puppet code and storing the result in a variable, use the with lambda.

For example, here is a YAML plan with a multi-line eval step:

parameters:
  foo:
    type: Optional[Integer]
    description: foo
    default: 0

steps:
  - eval: |
      $x = $foo + 1
      $x * 2
    name: eval_step

return: $eval_step

And here is the same plan, converted to the Puppet language:

plan yaml_plans::with_lambda(
  Optional[Integer] $foo = 0
) {
  $eval_step = with() || {
    $x = $foo + 1
    $x * 2
  }

  return $eval_step
}

Writing this plan from scratch using the Puppet language, you would probably not use the lambda. In this example the converted Puppet code is correct, but not as natural or readable as it could be.

When applying Puppet resources in a resource step, variable interpolation behaves differently in YAML plans and Puppet language plans. To illustrate this difference, consider this YAML plan:

steps:
  - targets: localhost
    description: Apply a file resource
    resources:
    - type: file
      title: '/tmp/foo'
      parameters:
        content: $facts['os']['family']
        ensure: present
  - name: file_contents
    description: Read contents of file managed with file resource
    eval: >
      file::read('/tmp/foo')
      
return: $file_contents

This plan performs apply_prep on a localhost target. Then it uses a Puppet file resource to write the OS family discovered from the Puppet $facts hash to a temporary file. Finally, it reads the value written to the file and returns it. Running bolt plan convert on this plan produces this Puppet code:

plan yaml_plans::interpolation_pp() {
  apply_prep('localhost')
  $interpolation = apply('localhost') {
    file { '/tmp/foo':
      content => $facts['os']['family'],
      ensure => 'present',
    }
  }
  $file_contents = file::read('/tmp/foo')

  return $file_contents
}

This Puppet language plan works as expected, whereas the YAML plan it was converted from fails. The failure stems from the $factsvariable being resolved as a plan variable, instead of being evaluated as part of compiling the manifest code in an applyblock.

The resources in a resources list are applied in order. It is possible to set dependencies explicitly, but when doing so you must refer to them in a particular way. Consider the following YAML plan:

parameters:
  targets:
    type: TargetSpec
steps:
  - name: pkg
    targets: $targets
    resources:
      - title: openssh-server
        type: package
        parameters:
          ensure: present
          before: File['/etc/ssh/sshd_config']
      - title: /etc/ssh/sshd_config
        type: file
        parameters:
          ensure: file
          mode: '0600'
          content: ''
          require: Package['openssh-server']

Executing this plan fails during catalog compilation because of how Bolt parses the resources referenced in the before and require parameters. You will see the error message Could not find resource 'File['/etc/ssh/sshd_config']' in parameter 'before'. The solution is to not quote the resource titles:

parameters:
  targets:
    type: TargetSpec
steps:
  - name: pkg
    targets: $targets
    resources:
      - title: openssh-server
        type: package
        parameters:
          ensure: present
          before: File[/etc/ssh/sshd_config]
      - title: /etc/ssh/sshd_config
        type: file
        parameters:
          ensure: file
          mode: '0600'
          content: ''
          require: Package[openssh-server]

In general, declare resources in order. This is an unusual example to illustrate a case where parameter parsing leads to non-intuitive results.