diff --git a/website/source/docs/templates/configuration-templates.html.markdown b/website/source/docs/templates/configuration-templates.html.markdown index 2d4999a5b..36d232d05 100644 --- a/website/source/docs/templates/configuration-templates.html.markdown +++ b/website/source/docs/templates/configuration-templates.html.markdown @@ -1,5 +1,6 @@ --- layout: "docs" +page_title: "Configuration Templates" --- # Configuration Templates diff --git a/website/source/docs/templates/user-variables.html.markdown b/website/source/docs/templates/user-variables.html.markdown new file mode 100644 index 000000000..99c59d11e --- /dev/null +++ b/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: + +
+{
+ "variables": {
+ "aws_access_key": "",
+ "aws_secret_key": ""
+ },
+
+ "builders": [{
+ "type": "amazon-ebs",
+ "access_key": "{{user `aws_access_key`}}",
+ "secret_key": "{{user `aws_secret_key`}}",
+ ...
+ }]
+}
+
+
+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 {{user `variable`}}.
+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:
+
+
+{
+ "aws_access_key": "foo",
+ "aws_secret_key": "bar"
+}
+
+
+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.
diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb
index 7264385c8..8b3ef5ddd 100644
--- a/website/source/layouts/docs.erb
+++ b/website/source/layouts/docs.erb
@@ -22,6 +22,7 @@