From 110b1411d78706a4e9bbce75e3a4fa6ed3b25afb Mon Sep 17 00:00:00 2001
From: Moss <moss@hashicorp.com>
Date: Fri, 5 Jun 2020 15:49:09 +0200
Subject: [PATCH] Update provisioners and post-processor hcl2 docs

---
 .../from-1.5/blocks/build/post-processor.mdx  |  26 ++++-
 .../from-1.5/blocks/build/provisioner.mdx     | 110 ++++++++++++++++++
 2 files changed, 135 insertions(+), 1 deletion(-)

diff --git a/website/pages/docs/from-1.5/blocks/build/post-processor.mdx b/website/pages/docs/from-1.5/blocks/build/post-processor.mdx
index dd8c16afd..ada3a9569 100644
--- a/website/pages/docs/from-1.5/blocks/build/post-processor.mdx
+++ b/website/pages/docs/from-1.5/blocks/build/post-processor.mdx
@@ -26,4 +26,28 @@ build {
 Post-processors run after the image is built by the builder and provisioned by
 the provisioner(s). Post-processors are optional, and they can be used to
 upload artifacts, re-package, or more. The list of available post-processors
-can be found in the [post-processors](/docs/post-processors) section.
\ No newline at end of file
+can be found in the [post-processors](/docs/post-processors) section.
+
+# Run on Specific Builds
+
+You can use the `only` or `except` configurations to run a post-provessor only
+with specific builds. These two configurations do what you expect: `only` will
+only run the post-provessor on the specified builds and `except` will run the
+post-provessor on anything other than the specified builds.
+
+An example of `only` being used is shown below, but the usage of `except` is
+effectively the same:
+
+```hcl
+# builds.pkr.hcl
+build {
+  # ...
+  post-processor "checksum" {
+    checksum_types = [ "md5", "sha512" ]
+    keep_input_artifact = true
+    only = ["source.amazon-ebs.example"]
+  }
+}
+```
+
+The values within `only` or `except` are _build names_, not builder types.
diff --git a/website/pages/docs/from-1.5/blocks/build/provisioner.mdx b/website/pages/docs/from-1.5/blocks/build/provisioner.mdx
index 900fdacd9..c455ae3e5 100644
--- a/website/pages/docs/from-1.5/blocks/build/provisioner.mdx
+++ b/website/pages/docs/from-1.5/blocks/build/provisioner.mdx
@@ -30,3 +30,113 @@ machine image after booting. Provisioners prepare the system for use.
 
 The list of available provisioners can be found in the
 [provisioners](/docs/provisioners) section.
+
+# Run on Specific Builds
+
+You can use the `only` or `except` configurations to run a provisioner only
+with specific builds. These two configurations do what you expect: `only` will
+only run the provisioner on the specified builds and `except` will run the
+provisioner on anything other than the specified builds.
+
+An example of `only` being used is shown below, but the usage of `except` is
+effectively the same:
+
+```hcl
+# builds.pkr.hcl
+build {
+  # ...
+  provisioner "shell" {
+      inline = [
+        "echo provisioning all the things",
+        "echo the value of 'foo' is '${var.foo}'",
+      ]
+      only = ["source.amazon-ebs.example"]
+  }
+}
+```
+
+The values within `only` or `except` are _build names_, not builder types.
+
+
+## Pausing Before Running
+
+With certain provisioners it is sometimes desirable to pause for some period of
+time before running it. Specifically, in cases where a provisioner reboots the
+machine, you may want to wait for some period of time before starting the next
+provisioner.
+
+Every provisioner definition in a Packer template can take a special
+configuration `pause_before` that is the amount of time to pause before running
+that provisioner. By default, there is no pause. An example is shown below:
+
+```hcl
+# builds.pkr.hcl
+build {
+  # ...
+  provisioner "shell" {
+      inline = [
+        "echo provisioning all the things",
+        "echo the value of 'foo' is '${var.foo}'",
+      ]
+      pause_before = "10s"
+  }
+}
+```
+
+For the above provisioner, Packer will wait 10 seconds before uploading and
+executing the shell script.
+
+## Retry on error
+
+With certain provisioners it is sometimes desirable to retry when it fails.
+Specifically, in cases where the provisioner depends on external processes that are not done yet.
+
+
+Every provisioner definition in a Packer template can take a special
+configuration `max_retries` that is the maximum number of times a provisioner will retry on error.
+By default, there `max_retries` is zero and there is no retry on error. An example is shown below:
+
+```hcl
+# builds.pkr.hcl
+build {
+  # ...
+  provisioner "shell" {
+      inline = [
+        "echo provisioning all the things",
+        "echo the value of 'foo' is '${var.foo}'",
+      ]
+      max_retries = 5
+  }
+}
+```
+
+For the above provisioner, Packer will retry maximum five times until stops failing.
+If after five retries the provisioner still fails, then the complete build will fail.
+
+## Timeout
+
+Sometimes a command can take much more time than expected
+
+Every provisioner definition in a Packer template can take a special
+configuration `timeout` that is the amount of time to wait before
+considering that the provisioner failed. By default, there is no timeout. An
+example is shown below:
+
+```hcl
+# builds.pkr.hcl
+build {
+  # ...
+  provisioner "shell" {
+      inline = [
+        "echo provisioning all the things",
+        "echo the value of 'foo' is '${var.foo}'",
+      ]
+      timeout = "5m"
+  }
+}
+```
+
+For the above provisioner, Packer will cancel the script if it takes more than
+5 minutes.
+
+Timeout has no effect in debug mode.