add some docs

Author: adreyer

pre-docs/bolt_configuration_options.md

@@ -92,6 +92,15 @@ ssh:
 
 `service-options`: A hash of options to configure the Docker connection. Only necessary if using a non-default URL. See https://github.com/swipely/docker-api for supported options.
 
+## Remote transport configuration options
+
+*The remote transport is a new feature and currently experimental. It's configuration options and behavior may change between y releases*
+
+`run-on`: The proxy target the task should execute on. Default is `localhost`
+
+`conn-info`: A hash of connection info that will be passed to the device as `_target`.
+
+
 ## Log file configuration options
 
 Capture the results of your plan runs in a log file.

pre-docs/inventory_file.md

@@ -61,9 +61,9 @@ groups:
 ## Override a user for a specific node
 
 ```
-nodes: 
+nodes:
   - name: linux1.example.com
-    config: 
+    config:
       ssh:
         user: me
 ```
@@ -195,10 +195,24 @@ nodes:
           run-as: root
 ```
 
--   **[Generating inventory files](inventory_file_generating.md)**  
+Configure a remote target
+
+```yaml
+nodes:
+  - host1.example.com
+  - name: remote.example.com
+    config:
+      transport: remote
+      remote:
+        run-on: host1.example.com
+        conn-info:
+          url: https://user1:[email protected]
+```
+
+-   **[Generating inventory files](inventory_file_generating.md)**
  Use the `bolt-inventory-pdb` script to generate inventory files based on PuppetDB queries.
 
-**Related information**  
+**Related information**
 
 
 [Naming tasks](writing_tasks.md#)

pre-docs/writing_tasks.md

@@ -80,7 +80,7 @@ Pattern[/\A[^\/\\]*\z/] $path
 
 In addition to these task restrictions, different scripting languages each have their own ways to validate user input.
 
-###  PowerShell 
+###  PowerShell
 
 In PowerShell, code injection exploits calls that specifically evaluate code. Do not call `Invoke-Expression` or `Add-Type` with user input. These commands evaluate strings as C\# code.
 
@@ -129,7 +129,7 @@ Resolve file paths with `os.realpath` and confirm them to be within another path
 
 For more information on the vulnerabilities of Python or how to escape variables, see Kevin London's blog post on [Dangerous Python Functions](https://www.kevinlondon.com/2015/07/26/dangerous-python-functions.html).
 
-###  Ruby 
+###  Ruby
 
 In Ruby, command injection is introduced through commands like `eval`, `exec`, `system`, backtick \(\`\`\) or `%x()` execution, or the Open3 module. You can safely call these functions with user input by passing the input as additional arguments instead of a single string.
 
@@ -296,7 +296,7 @@ To create a task that includes additional files pulled from modules, include the
 
 -   the module name
 -   one of `lib`, `files`, or `tasks` for the directory within the module
--   the remaining path to a file or directory; directories must include a trailing slash `/` 
+-   the remaining path to a file or directory; directories must include a trailing slash `/`
 
 All path separators must be forward slashes. An example would be `stdlib/lib/puppet/`.
 
@@ -317,15 +317,15 @@ When a task includes the `files` property, all files listed in the top-level p
 
 For example, you can create a task and metadata in a new module at `~/.puppetlabs/bolt/site/mymodule/tasks/task.{json,rb}`.
 
- **Metadata** 
+ **Metadata**
 
 ```
 {
   "files": ["multi_task/files/rb_helper.rb"]
 }
 ```
 
- **File Resource** 
+ **File Resource**
 
 `multi_task/files/rb_helper.rb`
 
@@ -335,7 +335,7 @@ def useful_ruby
 end
 ```
 
- **Task** 
+ **Task**
 
 ```
 #!/usr/bin/env ruby
@@ -349,7 +349,7 @@ require_relative File.join(params['_installdir'], 'multi_task', 'files', 'rb_hel
 puts useful_ruby.to_json
 ```
 
- **Output** 
+ **Output**
 
 ```
 Started on localhost...
@@ -361,6 +361,18 @@ Successful on 1 node: localhost
 Ran on 1 node in 0.12 seconds
 ```
 
+### Remote Tasks
+
+Some targets are hard or impossible to execute tasks on directly. For example a
+network device may have a limited shell environment or a cloud service may be
+driven only by HTTP APIs. In these cases it makes sense to write a task that
+runs on a proxy target and remotely interacts with real target. By writing a
+remote task Bolt allows users to specify connection information for remote
+targets in their inventory file and injects them into the `_target` metaparam.
+
+
+(example)[https://github.com/puppetlabs/puppetlabs-panos/pull/70]
+
 ### Task Helpers
 
 To simplify writing tasks, Bolt includes [python\_task\_helper](https://github.com/puppetlabs/puppetlabs-python_task_helper) and [ruby\_task\_helper](https://github.com/puppetlabs/puppetlabs-ruby_task_helper). It also makes a useful demonstration of including code from another module.
@@ -369,7 +381,7 @@ To simplify writing tasks, Bolt includes [python\_task\_helper](https://github.c
 
 Create task and metadata in a module at `~/.puppetlabs/bolt/site/mymodule/tasks/task.{json,py}`.
 
- **Metadata** 
+ **Metadata**
 
 ```
 {
@@ -378,7 +390,7 @@ Create task and metadata in a module at `~/.puppetlabs/bolt/site/mymodule/tasks/
 }
 ```
 
- **Task** 
+ **Task**
 
 ```
 #!/usr/bin/env python
@@ -395,7 +407,7 @@ if __name__ == '__main__':
     MyTask().run()
 ```
 
- **Output** 
+ **Output**
 
 ```
 $ bolt task run mymodule::task -n localhost name='Julia'
@@ -412,7 +424,7 @@ Ran on 1 node in 0.12 seconds
 
 Create task and metadata in a new module at `~/.puppetlabs/bolt/site/mymodule/tasks/mytask.{json,rb}`.
 
- **Metadata** 
+ **Metadata**
 
 ```
 {
@@ -421,7 +433,7 @@ Create task and metadata in a new module at `~/.puppetlabs/bolt/site/mymodule/ta
 }
 ```
 
- **Task** 
+ **Task**
 
 ```
 #!/usr/bin/env ruby
@@ -430,13 +442,13 @@ require_relative '../lib/task_helper.rb'
 class MyTask < TaskHelper
   def task(name: nil, **kwargs)
     { greeting: "Hi, my name is #{name}" }
-  end 
+  end
 end
 
 MyTask.run if __FILE__ == $0
 ```
 
- **Output** 
+ **Output**
 
 ```
 $ bolt task run mymodule::mytask -n localhost name="Robert'); DROP TABLE Students;--"
@@ -469,7 +481,7 @@ For example, to add a `message` parameter to your task, read it from the environ
 echo your message is $PT_message
 ```
 
-### Defining parameters in Windows 
+### Defining parameters in Windows
 
 For Windows tasks, you can pass parameters as environment variables, but it's easier to write your task in PowerShell and use named arguments. By default tasks with a `.ps1` extension use PowerShell standard argument handling.
 
@@ -805,16 +817,16 @@ To define a parameter as sensitive within the JSON metadata, add the `"sensitive
 
 The following table shows task metadata keys, values, and default values.
 
-####  **Task metadata** 
+####  **Task metadata**
 
 |Metadata key|Description|Value|Default|
 |------------|-----------|-----|-------|
 |"description"|A description of what the task does.|String|None|
-|"input\_method"|What input method the task runner should use to pass parameters to the task.| -    `environment` 
+|"input\_method"|What input method the task runner should use to pass parameters to the task.| -    `environment`
 
--    `stdin` 
+-    `stdin`
 
--    `powershell` 
+-    `powershell`
 
 
  | Both `environment` and `stdin` unless `.ps1` tasks, in which case `powershell`
@@ -833,7 +845,7 @@ Task metadata can accept most Puppet data types.
 
 #### Common task data types
 
-**Restriction:** 
+**Restriction:**
 
 Some types supported by Puppet can not be represented as JSON, such as `Hash[Integer, String]`, `Object`, or `Resource`. These should not be used in tasks, because they can never be matched.
 
@@ -850,7 +862,7 @@ Some types supported by Puppet can not be represented as JSON, such as `Hash[Int
 | `Variant[Integer, Pattern[/\A\d+\Z/]]` |Matches an integer or a String of an integer|
 | `Boolean` |Accepts Boolean values.|
 
-**Related information**  
+**Related information**
 
 
 [Data type syntax](https://puppet.com/docs/puppet/latest/lang_data_type.html)