website: document user variables

website/source/docs/templates/configuration-templates.html.markdown

@@ -1,5 +1,6 @@
 ---
 layout: "docs"
+page_title: "Configuration Templates"
 ---
 
 # Configuration Templates

website/source/docs/templates/user-variables.html.markdown

@@ -0,0 +1,115 @@
+---
+layout: "docs"
+page_title: "User Variables in Templates"
+---
+
+# User Variables
+
+User variables allow your templates to be further configured with variables
+from the command-line, environmental variables, or files. This lets you
+parameterize your templates so that you can keep secret tokens,
+environment-specific data, and other types of information out of your
+templates. This maximizes the portablility and shareability of the template.
+
+Using user variables expects you know how
+[configuration templates](/docs/templates/configuration-templates.html) work.
+If you don't know how configuration templates work yet, please read that
+page first.
+
+## Usage
+
+User variables must first be defined in a `variables` section within your
+template. Even if you want a variable to default to an empty string, it
+must be defined. This explicitivity makes it easy for newcomers to your
+template to understand what can be modified using variables in your template.
+
+The `variables` section is a simple key/value mapping of the variable
+name to a default value. A default value can be the empty string. An
+example is shown below:
+
+<pre class="prettyprint">
+{
+  "variables": {
+    "aws_access_key": "",
+    "aws_secret_key": ""
+  },
+
+  "builders": [{
+    "type": "amazon-ebs",
+    "access_key": "{{user `aws_access_key`}}",
+    "secret_key": "{{user `aws_secret_key`}}",
+    ...
+  }]
+}
+</pre>
+
+In the above example, the template defines two variables: `aws_access_key` and
+`aws_secret_key`. They default to empty values.
+Later, the variables are used within the builder we defined in order to
+configure the actual keys for the Amazon builder.
+
+Using the variables is extremely easy. Variables are used by calling
+the user function in the form of <code>{{user &#96;variable&#96;}}</code>.
+This function can be used in _any string_ within the template, in
+builders, provisioners, _anything_. The user variable is available globally
+within the template.
+
+## Setting Variables
+
+Now that we covered how to define and use variables within a template,
+the next important point is how to actually set these variables. Packer
+exposes two methods for setting variables: from the command line or
+from a file.
+
+### From the Command Line
+
+To set variables from the command line, the `-var` flag is used as
+a parameter to `packer build` (and some other commands). Continuing our example
+above, we could build our template using the command below. The command
+is split across multiple lines for readability, but can of course be a single
+line.
+
+```
+$ packer build \
+    -var 'aws_access_key=foo' \
+    -var 'aws_secret_key=bar' \
+    template.json
+```
+
+As you can see, the `-var` flag can be specified multiple times in order
+to set multiple variables. Also, variables set later on the command-line
+override earlier set variables if it has already been set.
+
+Finally, variables set from the command-line override all other methods
+of setting variables. So if you specify a variable in a file (the next
+method shown), you can override it using the command-line.
+
+### From a File
+
+Variables can also be set from an external JSON file. The `-var-file`
+flag reads a file containing a basic key/value mapping of variables to
+values and sets those variables. The JSON file is simple:
+
+<pre class="prettyprint">
+{
+  "aws_access_key": "foo",
+  "aws_secret_key": "bar"
+}
+</pre>
+
+It is a single JSON object where the keys are variables and the values are
+the variable values. Assuming this file is in `variables.json`, we can
+build our template using the following command:
+
+```
+$ packer build -var-file=variables.json template.json
+```
+
+The `-var-file` flag can be specified multiple times and variables from
+multiple files will be read and applied. As you'd expect, variables read
+from files specified later override a variable set earlier if it has
+already been set.
+
+And as mentioned above, no matter where a `-var-file` is specified, a
+`-var` flag on the command line will always override any variables from
+a file.

website/source/layouts/docs.erb

@@ -22,6 +22,7 @@
 			<li><a href="/docs/templates/provisioners.html">Provisioners</a></li>
 			<li><a href="/docs/templates/post-processors.html">Post-Processors</a></li>
 			<li><a href="/docs/templates/configuration-templates.html">Configuration Templates</a></li>
+			<li><a href="/docs/templates/user-variables.html">User Variables</a></li>
 			<li><a href="/docs/templates/veewee-to-packer.html">Veewee-to-Packer</a></li>
 		</ul>
 

website/source/stylesheets/_components.scss

@@ -244,6 +244,7 @@ header .header {
         h3 {
             margin-top: $baseline;
             text-transform: capitalize;
+            font-size: 26px;
         }
     }
 }