From 0449add7b7a9097a0104243c7f77e0ae7fd90ea8 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Sat, 8 Jun 2013 17:29:20 -0700
Subject: [PATCH] website: template provisioner docs

---
 .../docs/templates/provisioners.html.markdown | 86 +++++++++++++++++++
 website/source/layouts/docs.erb               |  2 +-
 2 files changed, 87 insertions(+), 1 deletion(-)
 create mode 100644 website/source/docs/templates/provisioners.html.markdown

diff --git a/website/source/docs/templates/provisioners.html.markdown b/website/source/docs/templates/provisioners.html.markdown
new file mode 100644
index 000000000..6fbb4f07c
--- /dev/null
+++ b/website/source/docs/templates/provisioners.html.markdown
@@ -0,0 +1,86 @@
+---
+layout: "docs"
+---
+
+# Templates: Provisioners
+
+Within the template, the provisioners section contains an array of all the
+provisioners that Packer should use to install and configure software within
+running machines prior to turning them into machine images.
+
+Provisioners are _optional_. If no provisioners are defined within a template,
+then no software other than the defaults will be installed within the
+resulting machine images. This is not typical, however, since much of the
+value of Packer is to produce multiple identical images
+of pre-configured software.
+
+This documentation page will cover how to configure a provisioner in a template.
+The specific configuration options available for each provisioner, however,
+must be referenced from the documentation for that specific provisioner.
+
+Within a template, a section of provisioner definitions looks like this:
+
+<pre class="prettyprint">
+{
+  "provisioners": [
+    ... one or more provisioner definitions here ...
+  ]
+}
+</pre>
+
+## Provisioner Definition
+
+A provisioner definition is a JSON object that must contain at least
+the `type` key. This key specifies the name of the provisioner to use.
+Additional keys within the object are used to configure the provisioner,
+with the exception of a handful of special keys, covered later.
+
+As an example, the "shell" provisioner requires at least the `path` key,
+which specifies a path to a shell script to execute within the machines
+being created.
+
+An example provisioner definition is shown below, configuring the shell
+provisioner to run a local script within the machines:
+
+<pre class="prettyprint">
+{
+  "type": "shell",
+  "path": "script.sh"
+}
+</pre>
+
+## Build-Specific Overrides
+
+While the goal of Packer is to produce identical machine images, it
+sometimes requires periods of time where the machines are different before
+they eventually converge to be identical. In these cases, different configurations
+for provisioners may be necessary depending on the build. This can be done
+using build-specific overrides.
+
+An example of where this might be necessary is when building both an EC2 AMI
+and a VMware machine. The source EC2 AMI may setup a user with administrative
+privileges by default, whereas the VMware machine doesn't have these privileges.
+In this case, the shell script may need to be executed differently. Of course,
+the goal is that hopefully the shell script converges these two images to be
+identical. However, they may initially need to be run differently.
+
+This example is shown below:
+
+<pre class="prettyprint">
+{
+  "type": "shell",
+  "path": "script.sh",
+
+  "override": {
+    "vmware": {
+      "execute_command": "echo 'password' | sudo -S bash {{.Path}}"
+    }
+  }
+}
+</pre>
+
+As you can see, the `override` key is used. The value of this key is another
+JSON object where the key is the name of a [builder definition](/docs/templates/builders.html).
+The value of this is in turn another JSON object. This JSON object simply
+contains the provisioner configuration as normal. This configuration is merged
+into the default provisioner configuration.
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
index f1b366698..12960193a 100644
--- a/website/source/layouts/docs.erb
+++ b/website/source/layouts/docs.erb
@@ -37,7 +37,7 @@
 							<li class="nav-header">Templates</li>
 							<li><a href="/docs/templates/introduction.html">Introduction</a></li>
 							<li><a href="/docs/templates/builders.html">Builders</a></li>
-							<li><a href="#">Provisioners</a></li>
+							<li><a href="/docs/templates/provisioners.html">Provisioners</a></li>
 
 							<li class="nav-header">Builders</li>
 							<li><a href="#">EC2 (AMI)</a></li>