Merge pull request #8671 from hashicorp/pp_sharing_info_doc

Add custom-builders sharing info with post-processors doc

website/source/docs/extending/custom-builders.html.md

@@ -164,7 +164,7 @@ they aren't documented here other than to tell you how to hook in provisioners.
 ### Build variables
 
 Packer makes it possible to provide custom template engine variables to be shared with 
-provisioners using the `build` function. 
+provisioners and post-processors using the `build` function. 
  
 Part of the builder interface changes made in 1.5.0 was to make builder Prepare() methods 
 return a list of custom variables which we call `generated data`. 
@@ -199,4 +199,57 @@ func (b *Builder) Run(ctx context.Context, ui packer.Ui, hook packer.Hook) (pack
 }
 ```
 
+In order to make these same variables and the Packer default ones also available to post-processor, 
+it is necessary to add them to the Artifact returned by the builder. This can be done by adding an attribute of type
+`map[string]interface{}` to the Artifact and putting the generated data in it. The post-processor 
+will access this data later via the Artifact's `State` method.   
+
+The Artifact code should be implemented similar to the below:
+
+```
+type Artifact struct {
+	// ...
+
+	// StateData should store data such as GeneratedData
+	// to be shared with post-processors
+	StateData map[string]interface{}
+}
+
+// ...
+
+func (a *Artifact) State(name string) interface{} {
+	return a.StateData[name]
+}
+
+// ...
+```    
+   
+The builder should return the above Artifact containing the generated data and the code should be similar
+to the example snippet below:
+
+```
+func (b *Builder) Run(ctx context.Context, ui packer.Ui, hook packer.Hook) (packer.Artifact, error) {
+    // ...
+    
+    return &Artifact{
+                // ...
+                StateData: map[string]interface{}{"generated_data": state.Get("generated_data")},
+            }, nil
+}
+```
+The code above assigns the `generated_data` state to the `StateData` map with the key `generated_data`.   
+
+Here some example of how this data will be used by post-processors: 
+
+```
+func (p *PostProcessor) PostProcess(ctx context.Context, ui packer.Ui, source packer.Artifact) (packer.Artifact, bool, bool, error) {
+    generatedData := source.State("generated_data")
+    
+    // generatedData will then be used for interpolation
+  
+    // ...
+}
+```
+
+
 To know more about the template engine build function, please refer to the [template engine docs](/docs/templates/engine.html).

website/source/docs/templates/engine.html.md

@@ -62,7 +62,7 @@ Here is a full list of the available functions for reference.
     each function will behave.
 -   `env` - Returns environment variables. See example in [using home
     variable](/docs/templates/user-variables.html#using-home-variable)
--   `build` - This engine will allow you to access special variables that
+-   `build` - This engine will allow you to access, from provisioners and post-processors, special variables that
     provide connection information and basic instance state information.
     Usage example: