iSharkFly-Docs
/
packer-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated the naming of variables 

Ensured template variables are described as that where references and
distinguished from user variables.
This commit is contained in:
James Turnbull 2017-05-15 15:41:27 -04:00
parent 5425b38083
commit cae2170375
2 changed files with 51 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
website/source/docs/templates/engine.html.md vendored
View File

@ -22,9 +22,11 @@ need greater than one second granularity, you should use `{{uuid}}`, for
example when you have multiple builders in the same template. example when you have multiple builders in the same template.
In addition to globally available functions like `{{timestamp}}`, some In addition to globally available functions like `{{timestamp}}`, some
configurations have special local variables that are available only for configurations have special template variables that are available only
that configuration. These are recognizable because they're prefixed by a for that configuration. Template variables are recognizable because
period, such as `{{.Name}}`. they're prefixed by a period, such as `{{.Name}}`.
-> **Note:** In addition to template variables, you can specify your own user variables. See the [user variable](/docs/templates/user-variables.html) documentation for more information on user variables.
The complete syntax is covered in the next section, followed by a reference of The complete syntax is covered in the next section, followed by a reference of
globally available functions. globally available functions.
@ -34,11 +36,12 @@ globally available functions.
The syntax of templates uses the following conventions: The syntax of templates uses the following conventions:
* Anything template related happens within double-braces: `{{ }}`. * Anything template related happens within double-braces: `{{ }}`.
* Variables are prefixed with a period and capitalized, such as `{{.Variable}}`. * Template variables are prefixed with a period and capitalized, such as
`{{.Variable}}`.
* Functions are directly within the braces, such as `{{timestamp}}`. * Functions are directly within the braces, such as `{{timestamp}}`.
Here is an example from the VMware VMX template that shows configuration Here is an example from the VMware VMX template that shows template
templates in action: variables in action:
```liquid ```liquid
.encoding = "UTF-8" .encoding = "UTF-8"
@ -46,8 +49,8 @@ displayName = "{{ .Name }}"
guestOS = "{{ .GuestOS }}" guestOS = "{{ .GuestOS }}"
``` ```
In this case, the "Name" and "GuestOS" variables will be replaced, potentially In this case, the "Name" and "GuestOS" template variables will be
resulting in a VMX that looks like this: replaced, potentially resulting in a VMX template that looks like this:
```liquid ```liquid
.encoding = "UTF-8" .encoding = "UTF-8"
@ -57,7 +60,7 @@ guestOS = "otherlinux"
## Global Functions ## Global Functions
While some configuration settings have local variables specific to only that While some configuration settings have template variables specific to only that
configuration, a set of functions are available globally for use in *any string* configuration, a set of functions are available globally for use in *any string*
in Packer templates. These are listed below for reference. in Packer templates. These are listed below for reference.

73
website/source/docs/templates/user-variables.html.md vendored
View File

@ -16,21 +16,23 @@ User variables allow your templates to be further configured with variables from
the command-line, environment variables, or files. This lets you parameterize the command-line, environment variables, or files. This lets you parameterize
your templates so that you can keep secret tokens, environment-specific data, your templates so that you can keep secret tokens, environment-specific data,
and other types of information out of your templates. This maximizes the and other types of information out of your templates. This maximizes the
portability and shareability of the template. portability of the template.
Using user variables expects you know how [configuration Using user variables expects you to know how [configuration
templates](/docs/templates/engine.html) work. If you don't know templates](/docs/templates/engine.html) work. If you don't know
how configuration templates work yet, please read that page first. how configuration templates work yet, please read that page first.
## Usage ## Usage
User variables must first be defined in a `variables` section within your User variables must first be defined in a `variables` section within
template. Even if you want a variable to default to an empty string, it must be your template. Even if you want a user variable to default to an empty
defined. This explicitness helps reduce the time it takes for newcomers to string, it must be defined. This explicitness helps reduce the time it
understand what can be modified using variables in your template. takes for newcomers to understand what can be modified using variables
in your template.
The `variables` section is a key/value mapping of the variable name to a default The `variables` section is a key/value mapping of the user variable name
value. A default value can be the empty string. An example is shown below: to a default value. A default value can be the empty string. An example
is shown below:
```json ```json
{ {
@ -48,19 +50,19 @@ value. A default value can be the empty string. An example is shown below:
} }
``` ```
In the above example, the template defines two variables: `aws_access_key` and In the above example, the template defines two user variables:
`aws_secret_key`. They default to empty values. Later, the variables are used `aws_access_key` and `aws_secret_key`. They default to empty values.
within the builder we defined in order to configure the actual keys for the Later, the variables are used within the builder we defined in order to
Amazon builder. configure the actual keys for the Amazon builder.
If the default value is `null`, then the user variable will be *required*. This If the default value is `null`, then the user variable will be
means that the user must specify a value for this variable or template *required*. This means that the user must specify a value for this
validation will fail. variable or template validation will fail.
Variables are used by calling the user function in the form of User variables are used by calling the `{{user}}` function in the form of
<code>{{user \`variable\`}}</code>. This function can be used in *any value* <code>{{user \`variable\`}}</code>. This function can be used in *any value*
within the template; in builders, provisioners, *anywhere outside the `variables` within the template; in builders, provisioners, *anywhere outside the `variables`
section*. The user variable is available globally within the rest of the template. section*. User variables are available globally within the rest of the template.
## Environment Variables ## Environment Variables
@ -78,7 +80,7 @@ An example is shown below:
``` ```
This will default "my\_secret" to be the value of the "MY\_SECRET" environment This will default "my\_secret" to be the value of the "MY\_SECRET" environment
variable (or the empty string if it does not exist). variable (or an empty string if it does not exist).
-> **Why can't I use environment variables elsewhere?** User variables are -> **Why can't I use environment variables elsewhere?** User variables are
the single source of configurable input to a template. We felt that having the single source of configurable input to a template. We felt that having
@ -89,21 +91,23 @@ single source of input to a template that a user can easily discover using
`packer inspect`. `packer inspect`.
-> **Why can't I use `~` for home variable?** `~` is an special variable -> **Why can't I use `~` for home variable?** `~` is an special variable
that is evaluated by shell during a variable expansion. As packer doesn't run that is evaluated by shell during a variable expansion. As Packer doesn't run
inside a shell, it won't expand `~`. inside a shell, it won't expand `~`.
## Setting Variables ## Setting Variables
Now that we covered how to define and use variables within a template, the next Now that we covered how to define and use user variables within a
important point is how to actually set these variables. Packer exposes two template, the next important point is how to actually set these
methods for setting variables: from the command line or from a file. variables. Packer exposes two methods for setting user variables: from
the command line or from a file.
### From the Command Line ### From the Command Line
To set variables from the command line, the `-var` flag is used as a parameter To set user variables from the command line, the `-var` flag is used as
to `packer build` (and some other commands). Continuing our example above, we a parameter to `packer build` (and some other commands). Continuing our
could build our template using the command below. The command is split across example above, we could build our template using the command below. The
multiple lines for readability, but can of course be a single line. command is split across multiple lines for readability, but can of
course be a single line.
```text ```text
$ packer build \ $ packer build \
@ -114,7 +118,7 @@ $ packer build \
As you can see, the `-var` flag can be specified multiple times in order to set 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 multiple variables. Also, variables set later on the command-line override
earlier set variables if it has already been set. any earlier set variable of the same name.
### From a File ### From a File
@ -139,11 +143,12 @@ $ packer build -var-file=variables.json template.json
The `-var-file` flag can be specified multiple times and variables from multiple 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 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. specified later override a variable set earlier.
Combining the -var and -var-file flags together also works how you'd Combining the `-var` and `-var-file` flags together also works how you'd
expect. Flags set later in the command override flags set earlier. So, for expect. Variables set later in the command override variables set
example, in the following command with the above variables.json file: earlier. So, for example, in the following command with the above
`variables.json` file:
```text ```text
$ packer build \ $ packer build \
@ -153,7 +158,7 @@ $ packer build \
template.json template.json
``` ```
results in the following variables: Results in the following variables:
| Variable | Value | | Variable | Value |
| -------- | --------- | | -------- | --------- |
@ -179,7 +184,7 @@ provisioner only run if the `do_nexpose_scan` variable is non-empty.
## Using HOME Variable ## Using HOME Variable
In order to use `$HOME` variable, you can create a `home` variable in packer: In order to use `$HOME` variable, you can create a `home` variable in Packer:
```json ```json
{ {
@ -189,7 +194,7 @@ In order to use `$HOME` variable, you can create a `home` variable in packer:
} }
``` ```
And this will be available to be used in the rest of the template, ie: And this will be available to be used in the rest of the template, i.e.:
```json ```json
{ {