Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 38 ยท Scale and Operations

Orchestration with Bolt: Tasks and Plans

Run ad hoc commands and multi-step workflows over SSH and WinRM with Bolt: inventory files, tasks with metadata, YAML and Puppet-language plans, apply blocks and error handling.

Puppet agents converge machines to a desired state every 30 minutes. That model is wrong for some jobs: restarting a service on all web servers one at a time, running a one-off cleanup, draining a node before a kernel update, or rolling a database upgrade in a particular order. These are orchestration tasks: ordered, targeted and immediate. Bolt is Puppet's open source tool for them. It connects over SSH or WinRM, needs no agent on the target and no Puppet server, and runs commands, scripts, tasks, plans and even Puppet code.

This lesson covers the building blocks and a safe way to use them. Bolt works from your workstation against real machines, so the commands are read-only here. The runnable blocks are JavaScript stand-ins for inventory targeting and a rolling plan.

Commands and scripts

The simplest use mirrors an ad hoc tool:

Terminal
bolt command run 'uptime' --targets web1.example.com,web2.example.com
bolt command run 'systemctl is-active nginx' --targets web
bolt script run ./cleanup.sh --targets all_servers
bolt file upload ./motd /etc/motd --targets web

--targets accepts host names, groups from the inventory, a query (--query 'inventory[certname] { ... }' to pull from PuppetDB) and patterns such as ssh://host:2222.

Inventory

The inventory lists targets, groups and how to connect, in inventory.yaml of a Bolt project (a directory with bolt-project.yaml):

YAML
groups:
  - name: web
    targets:
      - web1.example.com
      - web2.example.com
      - web3.example.com
    config:
      transport: ssh
      ssh:
        user: deploy
        private-key: ~/.ssh/deploy_ed25519
        run-as: root
  - name: db
    targets:
      - db1.example.com
    vars:
      role: database

vars hold data you can use in plans, config holds transport settings. Keep secrets out of the file: use a plugin (for example a Vault or environment variable lookup) so credentials are fetched at run time.

Tasks

A task is a script, in any language, plus a metadata file that describes its parameters. It lives in a module under tasks/:

Terminal
#!/bin/bash
# tasks/restart.sh  (module: ops)
service="$PT_service"
systemctl restart "$service" && echo "{\"status\": \"restarted\", \"service\": \"$service\"}"
JSON
{
  "description": "Restart a systemd service",
  "input_method": "environment",
  "parameters": {
    "service": { "type": "String[1]", "description": "Unit name" }
  }
}

Parameters reach the script as environment variables prefixed with PT_ (or as JSON on standard input). Because the metadata declares types, Bolt validates the arguments before touching any target, and the task is self-documenting: bolt task show ops::restart.

Terminal
bolt task run ops::restart service=nginx --targets web

A task is the right size for one action. Prefer an existing task or a Puppet resource over a long shell command, because a task has a defined input and an output you can check.

Plans

A plan strings steps together with logic: ordering, conditions, loops, error handling, and data passing between steps. Plans are written in the Puppet language, or in YAML for simple cases.

YAML
# plans/rolling_restart.yaml (YAML plan)
parameters:
  targets:
    type: TargetSpec
  service:
    type: String
    default: nginx

steps:
  - name: restart_each
    description: Restart one server at a time
    # steps in a YAML plan run once for all targets;
    # use a Puppet-language plan when you need a loop with checks
    task: ops::restart
    targets: $targets
    parameters:
      service: $service

The Puppet-language version can loop, and stop at the first problem:

PUPPET
plan ops::rolling_restart (
  TargetSpec $targets,
  String     $service = 'nginx',
) {
  $nodes = get_targets($targets)

  $nodes.each |$node| {
    $result = run_task('ops::restart', $node, service => $service, '_catch_errors' => true)

    unless $result.ok {
      fail_plan("Restart failed on ${node.name}, stopping the roll-out", 'ops/restart-failed')
    }

    # wait until the health check passes before the next machine
    run_command('curl -fs http://localhost/health', $node)
  }
}

Run it with bolt plan run ops::rolling_restart targets=web. Key ideas:

  • run_task, run_command, run_script, upload_file are the step functions.
  • Each returns a ResultSet: one result per target with ok, value and error details. By default a failing step aborts the plan; _catch_errors lets you decide.
  • apply() blocks and apply_prep let a plan run Puppet code on targets without a server, so you can combine orchestration and configuration in one workflow.
  • Plans can call other plans and use parallelize() for concurrent actions; use serial loops for rolling operations.

Safety practices

  1. Preview with a small target set. Run the plan against one canary host first; Bolt's --targets makes this easy.
  2. Idempotent tasks. Make the task safe to run twice, since runs are retried by humans.
  3. Check, then act. Gate each batch with a health check, as in the plan above.
  4. Least privilege. Use a dedicated user with run-as for sudo, instead of logging in as root.
  5. Audit. Run Bolt from CI so there is a log of who ran what and when.
flowchart LR
  W["Workstation / CI"] -->|SSH / WinRM| N1["web1"]
  W -->|SSH / WinRM| N2["web2"]
  W -->|SSH / WinRM| N3["db1"]
  W --- I["inventory.yaml + plans"]

Bolt pushes actions from one place; nothing has to be installed on the targets.

Stand-ins

The first stand-in resolves targets from a group-based inventory, with the same names as the YAML above. The second runs a rolling plan with a health gate and stops on the first failure. Both are JavaScript stand-ins; real Bolt connects to machines.

JS Stand-in: resolve targets from inventory groups

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: a rolling restart that stops on failure

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second run stops after web2, so web3 keeps serving traffic. That is the whole point of a plan over a single command that hits every machine at once.

Bolt and Puppet together

Bolt does not replace agents. A healthy division of labor: Puppet keeps servers configured (state), while Bolt handles one-off or ordered actions (events). Bolt can trigger puppet agent -t on selected nodes right after a code deploy, or query PuppetDB to pick targets.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What must be installed on a target to use Bolt?

    Bolt is agentless and connects over SSH or WinRM.
  2. 2. How does a task script receive a parameter named service by default?

    With input_method environment, parameters arrive as PT_<name> variables.
  3. 3. What does _catch_errors => true do in run_task?

    The ResultSet is returned even for failures, so the plan can decide what to do.
  4. 4. When is a plan better than a single command?

    Plans add ordering, logic and error handling to orchestration.

Summary

  • Bolt runs commands, scripts, tasks and plans over SSH/WinRM without agents.
  • The inventory defines targets, groups, variables and connection settings.
  • Tasks are scripts with typed metadata; parameters arrive as PT_ variables.
  • Plans add ordering, health checks, loops and error handling; apply() can run Puppet code.
  • Roll out gradually, gate each step and keep tasks idempotent.

Next: Troubleshooting and Debugging Puppet