Writing plans in YAML

Use a message step to print a message. The step prints a message to standard out (stdout) when using the human output format, and prints to standard error (stderr) when using the json output format.

Message steps support the following keys:

For example:

steps:
  - message: hello world

You can pass variables to the message step to print them to stdout. If the variable contains a valid plan result, Bolt formats the plan result using a JSON representation of the result object. If the object is not a plan result, Bolt prints the object as a string.

For information on printing a step result with message, see Debugging plans.

Use a verbose step to print a message in verbose mode. The step prints a message to standard out (stdout) when using the human output format, and prints to standard error (stderr) when using the json output format.

Verbose steps support the following keys:

For example:

steps:
  - verbose: hello world

You can pass variables to the verbose step to print them to stdout. If the variable is a Bolt datatype it will be formatted as a Hash. Once the object is formatted, if it's a Hash or Array it is printed as JSON, otherwise Bolt prints the object as a string.

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 support the following keys:

For example:

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

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

Task steps support the following keys:

For example:

steps:
  - task: package
    targets:
      - 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

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 support the following keys:

For example:

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

Use a file download step to download a file or directory from a list of targets to a destination directory on the local host.

Files and directories are downloaded to the destination directory within a subdirectory matching the target's URL-encoded safe name. If the destination directory is a relative path, it will expand relative to the project's downloads directory, <PROJECT DIRECTORY>/downloads.

File download steps support the following keys:

For example:

steps:
  - download: /etc/ssh/sshd_config
    destination: sshd_config
    targets:
      - web1.example.com
      - ssh://web2.example.com
      - web3
    description: "Download ssh daemon config from the webservers"

If the specified file exists on each of the targets, it would be saved to the following locations:

• ~/.puppetlabs/bolt/downloads/sshd_config/web1.example.com/sshd_config

• ~/.puppetlabs/bolt/downloads/sshd_config/ssh%3A%2F%2Fweb2.example.com/sshd_config

• ~/.puppetlabs/bolt/downloads/sshd_config/web3/sshd_config

Since files are downloaded to a directory matching the target's safe name, the target's safe name is URL encoded to ensure it's a valid directory name.

🔩 Tip: To avoid URL encoding the target's safe name, give the target a simple, human-readable name in your inventory file.

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 support the following keys:

• upload: The location of the local file to be uploaded

• destination: The remote location to upload the file to

• targets: A target or list of targets to upload the file to

For example:

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

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

Plan steps support the following keys:

For example:

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

Use a resources step to apply a list of Puppet resources. A resource defines the desired state for part of a target. Bolt ensures each resource is in its desired state. Like the steps in a plan, if any resource in the list fails, the rest are skipped.

Note: For each resources step, Bolt executes the apply_prep plan function against the targets specified with the targets field. For more information about apply_prep, see Applying manifest blocks.

Resources steps support the following keys:

Each resource is a YAML map with a type and title, and optionally a parameters key. The resource type and title can either be specified separately with the type and title keys, or can be specified in a single line by using the type name as a key with the title as its value.

For example:

steps:
  - resources:
    # This resource is type 'package' and title 'nginx'
    - package: nginx
      parameters:
        ensure: latest
    # This resource is type 'service' and title 'nginx'
    - type: service
      title: nginx
      parameters:
        ensure: running
    targets:
      - web1.example.com
      - web2.example.com
      - web3.example.com
    description: "Set up nginx on the webservers"

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.

Eval steps support the following keys:

For example:

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