Writing plans in YAML

Naming plans

Plan names are named based on the filename of the plan, the name of the module containing the plan, and the path to the plan within the module.

Place plan files in your module's ./plans directory, using these file extensions:

Puppet plans — .pp
YAML plans — .yaml, not .yml

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

The name of the module the plan is located in.
The name of the plan file, without the extension.
The path within the module, if the plan is in a subdirectory of ./plans.

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

Plan structure

YAML plans contain a list of steps with optional parameters and results.

YAML maps accept these keys:

steps: The list of steps to perform
parameters: (Optional) The parameters accepted by the plan
return: (Optional) The value to return from the plan

Steps key

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

Command step

Use a command step to run a single command on a list of targets and save the results, containing stdout, stderr, and exit code.

The step fails if the exit code of any command is non-zero.

Command steps use these fields:

command: The command to run
target: A target or list of targets to run the command on

For example:

steps:
  - command: hostname -f
    target:
      - web1.example.com
      - web2.example.com
      - web3.example.com
    description: "Get the webserver hostnames"

Task step

Use a task step to run a Bolt task on a list of targets and save the results.

Task steps use these fields:

task: The task to run
target: A target or list of targets to run the task on
parameters: (Optional) A map of parameter values to pass to the task

For example:

steps:
  - task: package
    target:
      - web1.example.com
      - web2.example.com
      - web3.example.com
    description: "Check the version of the openssl package on the webservers"
    parameters:
      action: status
      name: openssl

Script step

Use a script step to run a script on a list of targets and save the results.

The script must be in the files/ directory of a module. The name of the script must be specified as <modulename>/path/to/script, omitting the files directory from the path.

Script steps use these fields:

script: The script to run
target: A target or list of targets to run the script on
arguments: (Optional) An array of command-line arguments to pass to the script

For example:

steps:
  - script: mymodule/check_server.sh
    target:
      - web1.example.com
      - web2.example.com
      - web3.example.com
    description: "Run mymodule/files/check_server.sh on the webservers"
    arguments:
      - "/index.html"
      - 60

File upload step

Use a file upload step to upload a file to a specific location on a list of targets.

The file to upload must be in the files/ directory of a Puppet module. The source for the file must be specified as <modulename>/path/to/file, omitting the files directory from the path.

File upload steps use these fields:

source: The location of the file to be uploaded
destination: The location where the file should be uploaded to

For example:

steps:
  - source: mymodule/motd.txt
    destination: /etc/motd
    target:
      - web1.example.com
      - web2.example.com
      - web3.example.com
    description: "Upload motd to the webservers"

Plan step

Use a plan step to run another plan and save its result.

Plan steps use these fields:

plan: The name of the plan to run
parameters: (Optional) A map of parameter values to pass to the plan

For example:

steps:
  - plan: facts
    description: "Gather facts for the webservers using the built-in facts plan"
    parameters:
      nodes:
        - web1.example.com
        - web2.example.com
        - web3.example.com

Parameters key

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 nodes 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"

How strings are evaluated

The behavior of strings is defined by how theyre 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'

Using variables and simple expressions

Parameters and step results are available as variables during plan execution, and they can be used to compute the value for each field of a step.

The simplest way to use a variable is to reference it directly by name. For example, this plan takes a parameter called nodes and passes it as the target list to a step:

parameters:
  nodes:
    type: TargetSpec

steps:
  - command: hostname -f
    target: $nodes

Variables can also be interpolated into string values. The string must be double-quoted to allow interpolation. For example:

parameters:
  username:
    type: String

steps:
  - task: echo
    message: "hello ${username}"
           target: $nodes

Many operations can be performed on variables to compute new values for step parameters or other fields.

Indexing arrays or hashes

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
    target: 'host.example.com'
    parameters:
      name: $users[0]
  - task: echo
    target: 'host.example.com'
    parameters:
      message: "hello ${users[0]}"

Calling functions

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(',')}"

Using code blocks

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 }

Connecting steps

You can connect multiple steps by using the result of one step to compute the parameters for another step.

`name` key

The name key makes its results 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:
  nodes:
    type: TargetSpec

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

`eval` step

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
    target: web1.example.com
    parameters:
      message: "The count is ${count}, and twice the count is ${double_count}"

Returning results

You can return a result from a plan by setting the return key at the top level of the plan. When the plan finishes, the return key is evaluated and returned as the result of the plan. If no return key is set, the plan returns undef.

steps:
  - name: hostnames
    command: hostname -f
    target: $nodes

return: $hostnames.map |$hostname_result| { $hostname_result['stdout'] }

Computing complex values

To compute complex values, you can use a Puppet code expression as the value of any field of a step except the name.

Bolt loads the plan as a YAML data structure. As it executes each step, it evaluates any expressions embedded in the step. Each plan parameter and the values of every previous named step are available in scope.

This lets you take advantage of the power of Puppet language in the places it's necessary, while keeping the rest of your plan simple.

When your plans need more sophisticated control flow or error handling beyond running a list of steps in order, it's time to convert them to Puppet language plans.

Converting YAML plans to Puppet plans

You can convert a YAML plan to a Puppet plan with the bolt plan convert command.

bolt plan convert path/to/my/plan.yaml

This command takes the relative or absolute path to the YAML plan to be converted and prints the converted Puppet plan to stdout.

Note: Converting a YAML plan might result in a Puppet plan which is syntactically correct, but behaviorally different from its YAML plan. Always manually verify a converted Puppet plan's functionality. If you convert a YAML plan to Puppet and it doesn't have the same behavior as the YAML plan, you can file an issue in our Git repo.

For example, with this YAML plan:

# site-modules/mymodule/plans/yamlplan.yaml
parameters:
  nodes:
    type: TargetSpec
steps:
  - name: run_task
    task: sample
    target: $nodes
    parameters:
      message: "hello world"
return: $run_task

Run the following conversion:

$ bolt plan convert site-modules/mymodule/plans/yamlplan.yaml
# WARNING: This is an autogenerated plan. It may not behave as expected.
plan mymodule::yamlplan(
  TargetSpec $nodes
) {
  $run_task = run_task('sample', $nodes, {'message' => "hello world"})
  return $run_task
}

Bolt

Naming plans

Plan structure

Steps key

Command step

Task step

Script step

File upload step

Plan step

Parameters key

How strings are evaluated

Using variables and simple expressions

Indexing arrays or hashes

Calling functions

Using code blocks

Connecting steps

name key

eval step

Returning results

Computing complex values

Converting YAML plans to Puppet plans

`name` key

`eval` step