bring docs from master

website/data/docs-navigation.js

@@ -140,6 +140,7 @@ export default [
       },
       'variables',
       'locals',
+      'contextual-variables',
       'syntax',
       'onlyexcept',
       'expressions',

website/pages/docs/builders/amazon/chroot.mdx

@@ -328,13 +328,52 @@ variables are available:
 - `SourceAMIOwnerName` - The source AMI owner alias/name (for example `amazon`).
 - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.
 
-## Build function template engine variables
+## Build Shared Information Variables
 
-For the build function of [template engine](/docs/templates/engine), the following
+This builder generates data that are shared with provisioner and post-processor via build function of [template engine](/docs/templates/engine) for JSON and [contextual variables](/docs/from-1.5/contextual-variables) for HCL2.
-variables are available:
+
+The generated variables available for this builder are:
 
 - `SourceAMIName` - The source AMI Name (for example
   `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
   build the AMI.
 - `Device` - Root device path.
 - `MountPath` - Device mounting path.
+
+Usage example:
+
+<Tabs>
+<Tab heading="JSON">
+
+```json
+"post-processors": [
+    {
+      "type": "manifest",
+      "output": "manifest.json",
+      "strip_path": true,
+      "custom_data": {
+        "source_ami_name": "{{ build `SourceAMIName` }}",
+        "device": "{{ build `Device` }}",
+        "mount_path": "{{ build `MountPath` }}"
+      }
+    }
+]
+```
+
+</Tab>
+<Tab heading="HCL2">
+
+```hcl
+post-processor "manifest" {
+    output = "manifest.json"
+    strip_path = true
+    custom_data = {
+        source_ami_name = "${build.SourceAMIName}"
+        device = "${build.Device}"
+        mount_path = "${build.MountPath}"
+    }
+}
+```
+
+</Tab>
+</Tabs>

website/pages/docs/builders/amazon/ebs.mdx

@@ -235,15 +235,50 @@ variables are available:
 - `SourceAMIOwnerName` - The source AMI owner alias/name (for example `amazon`).
 - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.
 
-## Build function template engine variables
+## Build Shared Information Variables
 
-For the build function of [template engine](/docs/templates/engine), the following
+This builder generates data that are shared with provisioner and post-processor via build function of [template engine](/docs/templates/engine) for JSON and [contextual variables](/docs/from-1.5/contextual-variables) for HCL2.
-variables are available:
+
+The generated variables available for this builder are:
 
 - `SourceAMIName` - The source AMI Name (for example
   `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
   build the AMI.
 
+Usage example:
+
+<Tabs>
+<Tab heading="JSON">
+
+```json
+"post-processors": [
+    {
+      "type": "manifest",
+      "output": "manifest.json",
+      "strip_path": true,
+      "custom_data": {
+        "source_ami_name": "{{ build `SourceAMIName` }}"
+      }
+    }
+]
+```
+
+</Tab>
+<Tab heading="HCL2">
+
+```hcl
+post-processor "manifest" {
+    output = "manifest.json"
+    strip_path = true
+    custom_data = {
+        source_ami_name = "${build.SourceAMIName}"
+    }
+}
+```
+
+</Tab>
+</Tabs>
+
 ## Tag Example
 
 Here is an example using the optional AMI tags. This will add the tags

website/pages/docs/builders/amazon/ebssurrogate.mdx

@@ -207,15 +207,50 @@ variables are available:
 - `SourceAMIOwnerName` - The source AMI owner alias/name (for example `amazon`).
 - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.
 
-## Build function template engine variables
+## Build Shared Information Variables
 
-For the build function of [template engine](/docs/templates/engine), the following
+This builder generates data that are shared with provisioner and post-processor via build function of [template engine](/docs/templates/engine) for JSON and [contextual variables](/docs/from-1.5/contextual-variables) for HCL2.
-variables are available:
+
+The generated variables available for this builder are:
 
 - `SourceAMIName` - The source AMI Name (for example
   `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
   build the AMI.
 
+Usage example:
+
+<Tabs>
+<Tab heading="JSON">
+
+```json
+"post-processors": [
+    {
+      "type": "manifest",
+      "output": "manifest.json",
+      "strip_path": true,
+      "custom_data": {
+        "source_ami_name": "{{ build `SourceAMIName` }}"
+      }
+    }
+]
+```
+
+</Tab>
+<Tab heading="HCL2">
+
+```hcl
+post-processor "manifest" {
+    output = "manifest.json"
+    strip_path = true
+    custom_data = {
+        source_ami_name = "${build.SourceAMIName}"
+    }
+}
+```
+
+</Tab>
+</Tabs>
+
 -> **Note:** Packer uses pre-built AMIs as the source for building images.
 These source AMIs may include volumes that are not flagged to be destroyed on
 termination of the instance building the new image. In addition to those

website/pages/docs/builders/amazon/ebsvolume.mdx

@@ -243,13 +243,48 @@ termination of the instance building the new image. In addition to those
 volumes created by this builder, any volumes in the source AMI which are not
 marked for deletion on termination will remain in your account.
 
-## Build function template engine variables
+## Build Shared Information Variables
 
-For the build function of [template engine](/docs/templates/engine), the following
+This builder generates data that are shared with provisioner and post-processor via build function of [template engine](/docs/templates/engine) for JSON and [contextual variables](/docs/from-1.5/contextual-variables) for HCL2.
-variables are available:
+
+The generated variables available for this builder are:
 
 - `SourceAMIName` - The source AMI Name (for example
   `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
   build the AMI.
 
+Usage example:
+
+<Tabs>
+<Tab heading="JSON">
+
+```json
+"post-processors": [
+    {
+      "type": "manifest",
+      "output": "manifest.json",
+      "strip_path": true,
+      "custom_data": {
+        "source_ami_name": "{{ build `SourceAMIName` }}"
+      }
+    }
+]
+```
+
+</Tab>
+<Tab heading="HCL2">
+
+```hcl
+post-processor "manifest" {
+    output = "manifest.json"
+    strip_path = true
+    custom_data = {
+        source_ami_name = "${build.SourceAMIName}"
+    }
+}
+```
+
+</Tab>
+</Tabs>
+
 @include 'builders/aws-ssh-differentiation-table.mdx'

website/pages/docs/builders/amazon/instance.mdx

@@ -199,15 +199,50 @@ variables are available:
 - `SourceAMIOwnerName` - The source AMI owner alias/name (for example `amazon`).
 - `SourceAMITags` - The source AMI Tags, as a `map[string]string` object.
 
-## Build function template engine variables
+## Build Shared Information Variables
 
-For the build function of [template engine](/docs/templates/engine), the following
+This builder generates data that are shared with provisioner and post-processor via build function of [template engine](/docs/templates/engine) for JSON and [contextual variables](/docs/from-1.5/contextual-variables) for HCL2.
-variables are available:
+
+The generated variables available for this builder are:
 
 - `SourceAMIName` - The source AMI Name (for example
   `ubuntu/images/ebs-ssd/ubuntu-xenial-16.04-amd64-server-20180306`) used to
   build the AMI.
 
+Usage example:
+
+<Tabs>
+<Tab heading="JSON">
+
+```json
+"post-processors": [
+    {
+      "type": "manifest",
+      "output": "manifest.json",
+      "strip_path": true,
+      "custom_data": {
+        "source_ami_name": "{{ build `SourceAMIName` }}"
+      }
+    }
+]
+```
+
+</Tab>
+<Tab heading="HCL2">
+
+```hcl
+post-processor "manifest" {
+    output = "manifest.json"
+    strip_path = true
+    custom_data = {
+        source_ami_name = "${build.SourceAMIName}"
+    }
+}
+```
+
+</Tab>
+</Tabs>
+
 ## Custom Bundle Commands
 
 A lot of the process required for creating an instance-store backed AMI

website/pages/docs/from-1.5/blocks/build/post-processor.mdx

@@ -71,3 +71,8 @@ build {
 ```
 
 The values within `only` or `except` are _source names_, not builder types.
+
+## Build Contextual Variables
+
+Packer allows to access connection information and basic instance state information from a post-processor. These information are stored in the `build` variable.
+Check out the [Contextual Variables](/docs/from-1.5/contextual-variables) documentation to learn more about and see some examples of how to use them.

website/pages/docs/from-1.5/blocks/build/provisioner.mdx

@@ -160,3 +160,8 @@ For the above provisioner, Packer will cancel the script if it takes more than
 5 minutes.
 
 Timeout has no effect in debug mode.
+
+## Build Contextual Variables
+
+Packer allows to access connection information and basic instance state information from a provisioner. These information are stored in the `build` variable.
+Check out the [Contextual Variables](/docs/from-1.5/contextual-variables) documentation to learn more about and see some examples of how to use them.

website/pages/docs/from-1.5/contextual-variables.mdx

@@ -0,0 +1,71 @@
+---
+layout: docs
+page_title: Contextual Variables - HCL Configuration Language
+sidebar_title: Contextual Variables
+description: |-
+  Special variables provide connection information and basic instance state information.
+  This page covers all existing special variables.
+---
+
+# Build Variables
+
+`@include 'from-1.5/beta-hcl2-note.mdx'`
+
+Build variables will allow you to access connection information and basic instance state information for a builder.
+All special build variables are stored in the `build` variable:
+
+```hcl
+  provisioner "shell" {
+      environment_vars = ["TESTVAR=${build.PackerRunUUID}"]
+      inline = ["echo $TESTVAR"]
+  }
+```
+
+Here is the list of available build variables:
+
+- **ID**: Represents the vm being provisioned. For example, in Amazon it is the instance id; in digitalocean,
+  it is the droplet id; in Vmware, it is the vm name.
+
+- **Host**, **Port**, **User** and **Password**: The host, port, user, and password that Packer uses to access the machine.
+  Useful for using the shell local provisioner to run Ansible or Inspec against the provisioned instance.
+
+- **ConnType**: Type of communicator being used. For example, for SSH communicator this will be "ssh".
+
+- **PackerRunUUID**: Current build's unique id. Can be used to specify build artifacts.
+  An example of that, is when multiple builds runs at the same time producing the same artifact.
+  It's possible to differentiate these artifacts by naming them with the builds' unique ids.
+
+- **PackerHTTPIP**, **PackerHTTPPort**, and **PackerHTTPAddr**: HTTP IP, port, and address of the file server Packer creates to serve items in the "http" dir to the vm. The HTTP address is displayed in the format `IP:PORT`.
+
+- **SSHPublicKey** and **SSHPrivateKey**: The public and private key that Packer uses to connect to the instance.
+  These are unique to the SSH communicator and are unset when using other communicators.
+  **SSHPublicKey** and **SSHPrivateKey** can have escape sequences and special characters so their output should be single quoted to avoid surprises. For example:
+
+  ```hcl
+    provisioner "shell" {
+        inline = ["echo '${build.SSHPrivateKey}' > /tmp/packer-session.pem"]
+    }
+  ```
+
+For backwards compatibility, `WinRMPassword` is also available through this
+engine, though it is no different than using the more general `Password`.
+
+All build variables are valid to use with any of the [HCL2 functions](/docs/from-1.5/functions).
+Example of using [upper](/docs/from-1.5/functions/string/upper) to upper case the build ID:
+
+```hcl
+  post-processor "shell-local" {
+      inline = ["echo ${upper(build.ID)}"]
+  }
+```
+
+For builder-specific builder variables, please also refer to the builder docs:
+
+  - Amazon EC2: [chroot](/docs/builders/amazon/chroot#build-shared-information-variables),
+  [EBS Volume](/docs/builders/amazon/ebsvolume#build-shared-information-variables),
+  [EBS](/docs/builders/amazon/ebs#build-shared-information-variables),
+  [EBS Surrogate](/docs/builders/amazon/ebssurrogate#build-shared-information-variables),
+  [Instance](/docs/builders/amazon/instance#build-shared-information-variables).
+
+The HCL2 Special Build Variables is in beta; please report any issues or requests on the Packer
+issue tracker on GitHub.

website/pages/docs/templates/engine.mdx

@@ -83,6 +83,8 @@ Here is a full list of the available functions for reference.
   - **ConnType**: Type of communicator being used. For example, for SSH communicator this will be "ssh".
 
   - **PackerRunUUID**: Current build's unique id. Can be used to specify build artifacts.
+    An example of that, is when multiple builds runs at the same time producing the same artifact.
+    It's possible to differentiate these artifacts by naming them with the builds' unique ids.
 
   - **PackerHTTPIP**, **PackerHTTPPort**, and **PackerHTTPAddr**: HTTP IP, port, and address of the file server Packer creates to serve items in the "http" dir to the vm. The HTTP address is displayed in the format `IP:PORT`.
 
@@ -98,16 +100,20 @@ Here is a full list of the available functions for reference.
     }
     ```
 
-  For backwards compatability, `WinRMPassword` is also available through this
+  For backwards compatibility, `WinRMPassword` is also available through this
   engine, though it is no different than using the more general `Password`.
 
   This function is only for use within specific options inside of
   _provisioners_ -- these options will be listed as being template engines
-  in the provisioner documentation. This feature does not yet work
+  in the provisioner documentation.
-  if the provisioners are being used in conjunction with our chroot builders
-  or with lxc/lxd builders.
 
-  For builder-specific engine variables, please also refer to the builder docs.
+  For builder-specific builder variables, please also refer to the builder docs:
+
+    - Amazon EC2: [chroot](/docs/builders/amazon/chroot#build-shared-information-variables),
+    [EBS Volume](/docs/builders/amazon/ebsvolume#build-shared-information-variables),
+    [EBS](/docs/builders/amazon/ebs#build-shared-information-variables),
+    [EBS Surrogate](/docs/builders/amazon/ebssurrogate#build-shared-information-variables),
+    [Instance](/docs/builders/amazon/instance#build-shared-information-variables).
 
   This engine is in beta; please report any issues or requests on the Packer
   issue tracker on GitHub.