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 # Template Engine
All strings within templates are processed by a common Packer templating 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 where variables and functions can be used to modify the value of a
parameter at runtime. 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 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 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 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 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 Here is a full list of the available functions for reference.
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.
- `build_name` - The name of the build being run. - `build_name` - The name of the build being run.
- `build_type` - The type of the builder being used currently. - `build_type` - The type of the builder being used currently.
- `isotime [FORMAT]` - UTC time, which can be - `isotime [FORMAT]` - UTC time, which can be
[formatted](https://golang.org/pkg/time/#example_Time_Format). See more [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. - `lower` - Lowercases the string.
- `pwd` - The working directory while executing Packer. - `pwd` - The working directory while executing Packer.
- `template_dir` - The directory to the template for the build. - `template_dir` - The directory to the template for the build.
- `timestamp` - The current Unix timestamp in UTC. - `timestamp` - The current Unix timestamp in UTC.
- `uuid` - Returns a random UUID. - `uuid` - Returns a random UUID.
- `upper` - Uppercases the string. - `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 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: 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. 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 ```liquid
isotime = June 7, 7:22:43pm 2014 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. -> **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 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
{ {