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

Merge pull request #4890 from jamtur01/varrename 

Updated the naming of variables
This commit is contained in:
Matthew Hooker 2017-05-20 00:50:27 -07:00 committed by GitHub
parent fdfb3fa1a6 0a544082ee
commit 4d84915bf8
2 changed files with 84 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -11,70 +11,69 @@ description: |-
# Template Engine
All strings within templates are processed by a common Packer templating engine,
where variables and functions can be used to modify the value of a configuration
parameter at runtime.
where variables and functions can be used to modify the value of a
configuration parameter at runtime.
For example, the `{{timestamp}}` function can be used in any string to generate
The syntax of templates uses the following conventions:
* Anything template related happens within double-braces: `{{ }}`.
* Functions are specified directly within the braces, such as `{{timestamp}}`.
* Template variables are prefixed with a period and capitalized, such as
`{{.Variable}}`.
## Functions
Functions perform operations on and within strings, for example the `{{timestamp}}` function can be used in any string to generate
the current timestamp. This is useful for configurations that require unique
keys, such as AMI names. By setting the AMI name to something like `My Packer
AMI {{timestamp}}`, the AMI name will be unique down to the second. If you
need greater than one second granularity, you should use `{{uuid}}`, for
example when you have multiple builders in the same template.
In addition to globally available functions like `{{timestamp}}`, some
configurations have special local variables that are available only for
that configuration. These are recognizable because they're prefixed by a
period, such as `{{.Name}}`.
The complete syntax is covered in the next section, followed by a reference of
globally available functions.
## Syntax
The syntax of templates uses the following conventions:
* Anything template related happens within double-braces: `{{ }}`.
* Variables are prefixed with a period and capitalized, such as `{{.Variable}}`.
* Functions are directly within the braces, such as `{{timestamp}}`.
Here is an example from the VMware VMX template that shows configuration
templates in action:
```liquid
.encoding = "UTF-8"
displayName = "{{ .Name }}"
guestOS = "{{ .GuestOS }}"
```
In this case, the "Name" and "GuestOS" variables will be replaced, potentially
resulting in a VMX that looks like this:
```liquid
.encoding = "UTF-8"
displayName = "packer"
guestOS = "otherlinux"
```
## Global Functions
While some configuration settings have local variables specific to only that
configuration, a set of functions are available globally for use in *any string*
in Packer templates. These are listed below for reference.
Here is a full list of the available functions for reference.
- `build_name` - The name of the build being run.
- `build_type` - The type of the builder being used currently.
- `isotime [FORMAT]` - UTC time, which can be
[formatted](https://golang.org/pkg/time/#example_Time_Format). See more
examples below.
examples below in [the `isotime` format reference](/docs/templates/engine.html#isotime-function-format-reference).
- `lower` - Lowercases the string.
- `pwd` - The working directory while executing Packer.
- `template_dir` - The directory to the template for the build.
- `timestamp` - The current Unix timestamp in UTC.
- `uuid` - Returns a random UUID.
- `upper` - Uppercases the string.
- `user` - Specify a user variable.
- `user` - Specifies a user variable.
### isotime Format
#### Specific to Amazon builders:
- `clean_ami_name` - AMI names can only contain certain characters. This
function will replace illegal characters with a '-" character. Example usage
since ":" is not a legal AMI name is: `{{isotime | clean_ami_name}}`.
## Template variables
Template variables are special variables automatically set by Packer at build time. Some builders, provisioners and other components have template variables that are available only for that component. Template variables are recognizable because they're prefixed by a period, such as `{{ .Name }}`. For example, when using the [`shell`](/docs/builders/vmware-iso.html) builder template variables are available to customize the [`execute_command`](/docs/provisioners/shell.html#execute_command) parameter used to determine how Packer will run the shell command.
```liquid
{
"provisioners": [
{
"type": "shell",
"execute_command": "{{.Vars}} sudo -E -S bash '{{.Path}}'",
"scripts": [
"scripts/bootstrap.sh"
]
}
]
}
```
The `{{ .Vars }}` and `{{ .Path }}` template variables will be replaced with the list of the environment variables and the path to the script to be executed respectively.
-> **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.
# isotime Function Format Reference
Formatting for the function `isotime` uses the magic reference date **Mon Jan 2
15:04:05 -0700 MST 2006**, which breaks down to the following:
@ -174,7 +173,7 @@ Formatting for the function `isotime` uses the magic reference date **Mon Jan 2
Note that "-0700" is always formatted into "+0000" because `isotime` is always UTC time.
Here are some example formated time, using the above format options:
Here are some example formatted time, using the above format options:
```liquid
isotime = June 7, 7:22:43pm 2014
@ -205,11 +204,3 @@ Please note that double quote characters need escaping inside of templates (in t
```
-> **Note:** See the [Amazon builder](/docs/builders/amazon.html) documentation for more information on how to correctly configure the Amazon builder in this example.
## Amazon Specific Functions
Specific to Amazon builders:
- `clean_ami_name` - AMI names can only contain certain characters. This
function will replace illegal characters with a '-" character. Example usage
since ":" is not a legal AMI name is: `{{isotime | clean_ami_name}}`.

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
your templates so that you can keep secret tokens, environment-specific data,
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
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 explicitness helps reduce the time it takes for newcomers to
understand what can be modified using variables in your template.
User variables must first be defined in a `variables` section within
your template. Even if you want a user variable to default to an empty
string, it must be defined. This explicitness helps reduce the time it
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
value. A default value can be the empty string. An example is shown below:
The `variables` section is a key/value mapping of the user variable name
to a default value. A default value can be the empty string. An example
is shown below:
```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
`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.
In the above example, the template defines two user 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.
If the default value is `null`, then the user variable will be *required*. This
means that the user must specify a value for this variable or template
validation will fail.
If the default value is `null`, then the user variable will be
*required*. This means that the user must specify a value for this
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*
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
@ -78,7 +80,7 @@ An example is shown below:
```
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
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`.
-> **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 `~`.
## 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.
Now that we covered how to define and use user variables within a
template, the next important point is how to actually set these
variables. Packer exposes two methods for setting user 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.
To set user 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.
```text
$ packer build \
@ -114,7 +118,7 @@ $ packer build \
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.
any earlier set variable of the same name.
### 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
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
expect. Flags set later in the command override flags set earlier. So, for
example, in the following command with the above variables.json file:
Combining the `-var` and `-var-file` flags together also works how you'd
expect. Variables set later in the command override variables set
earlier. So, for example, in the following command with the above
`variables.json` file:
```text
$ packer build \
@ -153,7 +158,7 @@ $ packer build \
template.json
```
results in the following variables:
Results in the following variables:
| Variable | Value |
| -------- | --------- |
@ -179,7 +184,7 @@ provisioner only run if the `do_nexpose_scan` variable is non-empty.
## 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
{
@ -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
{