(puppetlabsGH-3064) Document _required_modules parameter for apply

This adds documentation for the `_required_modules` parameter of the
`apply` plan function, including a section that describes what the
parameter does and when you would want to use it.

!no-release-note

bolt-modules/boltlib/lib/puppet/functions/apply_prep.rb

@@ -17,7 +17,8 @@
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param options Options hash.
   # @option options [Boolean] _catch_errors Whether to catch raised errors.
-  # @option options [Array] _required_modules An array of modules to sync to the target.
+  # @option options [Array[String]] _required_modules An array of modules to sync to the
+  #   target. For more information, see [Restrict modules synced to targets](applying_manifest_blocks.md#restrict-modules-synced-to-targets).
   # @option options [String] _run_as User to run as using privilege escalation.
   # @return [Bolt::ResultSet]
   # @example Prepare targets by name.

documentation/applying_manifest_blocks.md

@@ -180,6 +180,10 @@ The `apply` function supports the following options:
 - `_noop => true` applies the manifest block in Puppet no-operation mode,
   returning a report of the changes it would make, but takes no action.
 
+- `_required_modules => <MODULES>` a list of modules to sync to the target.
+  By default, this list includes all modules. For more information, see
+  [Restrict modules synced to target](#restrict-modules-synced-to-targets).
+
 - `_run_as => <USER>` applies the manifest block as the specified user. (This
   option is for transports that allow a user to run commands under a different
   username.)
@@ -274,6 +278,40 @@ NOTICE: Applied catalog in 0.01 seconds
 Finished: plan example in 8.64 sec
 ```
 
+### Restrict modules synced to targets
+
+When Bolt applies Puppet code to a target, it syncs modules to the target so
+files referenced in your Puppet code are available during the apply. These
+modules are added to a tarball, which is uploaded to each target during the
+apply run.
+
+By default, all of the modules available to your project are included in the
+tarball. If you have many modules available to your project, or modules that
+include large files, running an apply might run slowly. If you know which
+files need to be available during an apply run, you can improve performance
+by restricting which modules are included in the tarball and synced to
+each target.
+
+Both the `apply_prep` and `apply` plan functions have an optional
+`_required_modules` parameter, which accepts a list of module names to include
+in the tarball. When you set this parameter, Bolt will make sure to only
+sync the listed modules to each target.
+
+For example, if your Puppet code only needs access to a file from the module
+`mymodule`, you can tell Bolt to only sync `mymodule` during an apply:
+
+```puppet
+apply($targets, '_required_modules' => ['mymodule']) {
+  file { '/path/to/file':
+    ensure => present,
+    source => 'puppet:///modules/mymodule/myfile.txt'
+  }
+}
+```
+
+If you want to run an apply without syncing any modules, pass an empty array
+`[]` to the `_required_modules` parameter.
+
 ## Configuring concurrency
 
 Each target requires a separate catalog be compiled with its unique `facts` and

rakelib/docs.rake

@@ -329,6 +329,12 @@ begin
                           "during catalog compilation.",
                 "type" => "String"
               },
+              "_required_modules" => {
+                "desc" => "An array of modules to sync to the target. For more information, see "\
+                          "[Restrict modules synced to "\
+                          "targets](applying_manifest_blocks.md#restrict-modules-synced-to-targets).",
+                "type" => "Array[String]"
+              },
               "_run_as" => {
                 "desc" => "The user to apply the manifest block as. Only available for transports "\
                           "that support the `run-as` option.",