[BOLT-791] Support running a task on a proxy node targeting a device or API with run-on Created: 2018/08/20  Updated: 2018/12/13  Resolved: 2018/12/12

Status: Resolved
Project: Puppet Task Runner
Component/s: None
Affects Version/s: None
Fix Version/s: BOLT 1.6.0

Type: New Feature Priority: Normal
Reporter: Alex Dreyer Assignee: Alex Dreyer
Resolution: Fixed Votes: 1
Labels: docs, docs_reviewed
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Epic Link: Remote Targets
Sprint: Bolt Kanban
Release Notes: New Feature
Release Notes Summary: Adds support for remote tasks to bolt. Connection information for non-server targets like HTTP endpoints can now be stored in inventory.
QA Risk Assessment: Needs Assessment



Some tasks such as those targetting network devices or HTTP APIs may execute on a proxy target but in the users mind the target is the device or HTTP API itself. Bolt should support this in a more natural fashion by allowing targets to specify arbitrary connection information and a reference to a different target to run-on.


We should support run-on as an option for bolt targets that specifies the target is remote.

Task spec changes

metadata should support a new remote: true option. When set the task runner will run the task on the 'run-on' value for the target and pass a new _target metaparam to the task that includes the real target's config.

Inventory changes

  • A new top level option on targets "run-on".
  • targets with run-on set will fail for all run_* commands except run_task where the task has remote: true.
  • The config for targets with run-on will accept arbitrary values
  • setting run-on and a transport will fail.

Plan language changes

  • The Target object in the plan language should expose run_on as an attribute of targets that is undef unless run-on is set.


  • What should we call the run-on option? run-on/proxy ?
  • What should transport be for run-on nodes? 'remote'
  • Do we need to support anything other than remote tasks?
  • When should other run_* fail.

Comment by David Schmitt [ 2018/09/03 ]

This sounds very much like what devices would need from bolt. I'd love to see an end-to-end example of how this will look like to the user to get a better understanding of the proposed UX.

Open questions:

  • would the _target metaparam contain the device's credentials (or credential reference) similar to the device.conf of puppet device?
  • how does bolt connect to the run-on proxy node? Is that "just" a reference to another target in the inventory?
  • What runtime environment can remote tasks rely on?
Comment by Alex Dreyer [ 2018/09/04 ]

Yes _target will contain the Target object which has the credentials and other connection info.

Yes it's just a reference to another target(including localhost)

The task framework is platform agnostic so there is no single runtime environment any task can rely on*. In practice is seems reasonable to base remote tasks on the puppet agent runtime. It will make it easiest to reuse device code and the puppet agent ruby libraries are always available at least on the bolt controller. Beyond that tasks can use feature requirements in metadata combined with documentation to control their runtime environment. We'll have to sort out how implementations and feature requirements work for remote tasks. I think they're most valuable is they relate to the proxy rather then the target.

Comment by Thomas Honey [ 2018/09/05 ]

At the very least if the target information hash is passed to the task/plan. Then the task author can deal with the connection creation there. 

Comment by Alex Dreyer [ 2018/09/05 ]

Yeah it will be 100% up the task author to handle connecting to the device from the target info hash. We can't abstract that in the general case. For tasks in puppet-device modules we can probably provide some helpers.

Comment by Melissa Amos [ 2018/12/13 ]

Docs updates:

  1. http://docs-internal.puppet.com/docs/bolt/dev/bolt_configuration_options.html#remote-transport-configuration-options
  2. http://docs-internal.puppet.com/docs/bolt/dev/inventory_file.html#remote-targets
  3. http://docs-internal.puppet.com/docs/bolt/dev/writing_tasks.html#concept-5348
  4. http://docs-internal.puppet.com/docs/bolt/dev/bolt_new_features.html#remote-tasks-1-6-0

Item 3 especially needs checking – the code blocks for pasting errors, and because I did more editing than usual. I'll transfer those edits back to pre-docs if everything looks good.

Comment by Alex Dreyer [ 2018/12/13 ]


It looks like the formatting of "generating inventory files" got messed up.

'<' missing around "slack channel id" may lead to escaping confusion for users. It should either be wrapped in < or ' to show it's a single argument and needs to be escaped

Comment by Melissa Amos [ 2018/12/13 ]

Thanks Alex Dreyer.

1. The "Generating inventory files" link is autogenerated based on the structure of the publication. It's actually not even in our source, so I definitely didn't change anything!
2. Good catch. I had to remove the '<' to paste the code in XML, and I forgot to add them back. Fixed.

Generated at Thu Oct 17 08:00:55 PDT 2019 using JIRA 7.7.1#77002-sha1:e75ca93d5574d9409c0630b81c894d9065296414.