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 @@
  • Provisioners
  • Post-Processors
  • Configuration Templates
  • +
  • User Variables
  • Veewee-to-Packer
  • diff --git a/website/source/stylesheets/_components.scss b/website/source/stylesheets/_components.scss index 504c6b5b7..f5e26a22e 100644 --- a/website/source/stylesheets/_components.scss +++ b/website/source/stylesheets/_components.scss @@ -244,6 +244,7 @@ header .header { h3 { margin-top: $baseline; text-transform: capitalize; + font-size: 26px; } } }