github.com/aclaygray/packer@v1.3.2/website/source/docs/templates/engine.html.md (about) 1 --- 2 description: | 3 All strings within templates are processed by a common Packer templating 4 engine, where variables and functions can be used to modify the value of a 5 configuration parameter at runtime. 6 layout: docs 7 page_title: 'Template Engine - Templates' 8 sidebar_current: 'docs-templates-engine' 9 --- 10 11 # Template Engine 12 13 All strings within templates are processed by a common Packer templating engine, 14 where variables and functions can be used to modify the value of a 15 configuration parameter at runtime. 16 17 The syntax of templates uses the following conventions: 18 19 - Anything template related happens within double-braces: `{{ }}`. 20 - Functions are specified directly within the braces, such as `{{timestamp}}`. 21 - Template variables are prefixed with a period and capitalized, such as 22 `{{.Variable}}`. 23 24 ## Functions 25 26 Functions perform operations on and within strings, for example the `{{timestamp}}` function can be used in any string to generate 27 the current timestamp. This is useful for configurations that require unique 28 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 29 need greater than one second granularity, you should use `{{uuid}}`, for 30 example when you have multiple builders in the same template. 31 32 Here is a full list of the available functions for reference. 33 34 - `build_name` - The name of the build being run. 35 - `build_type` - The type of the builder being used currently. 36 - `env` - Returns environment variables. See example in [using home variable](/docs/templates/user-variables.html#using-home-variable) 37 - `isotime [FORMAT]` - UTC time, which can be 38 [formatted](https://golang.org/pkg/time/#example_Time_Format). See more 39 examples below in [the `isotime` format reference](/docs/templates/engine.html#isotime-function-format-reference). 40 - `lower` - Lowercases the string. 41 - `pwd` - The working directory while executing Packer. 42 - `split` - Split an input string using separator and return the requested substring. 43 - `template_dir` - The directory to the template for the build. 44 - `timestamp` - The current Unix timestamp in UTC. 45 - `uuid` - Returns a random UUID. 46 - `upper` - Uppercases the string. 47 - `user` - Specifies a user variable. 48 - `packer_version` - Returns Packer version. 49 50 #### Specific to Amazon builders: 51 52 - `clean_ami_name` - AMI names can only contain certain characters. This 53 function will replace illegal characters with a '-" character. Example usage 54 since ":" is not a legal AMI name is: `{{isotime | clean_ami_name}}`. 55 56 #### Specific to Google Compute builders: 57 58 - `clean_image_name` - GCE image names can only contain certain characters and 59 the maximum length is 63. This function will convert upper cases to lower cases 60 and replace illegal characters with a "-" character. 61 Example: 62 63 `"mybuild-{{isotime | clean_image_name}}"` 64 will become 65 `mybuild-2017-10-18t02-06-30z`. 66 67 Note: Valid GCE image names must match the regex 68 `(?:[a-z](?:[-a-z0-9]{0,61}[a-z0-9])?)` 69 70 This engine does not guarantee that the final image name will match the 71 regex; it will not truncate your name if it exceeds 63 characters, and it 72 will not validate that the beginning and end of the engine's output are 73 valid. For example, 74 `"image_name": {{isotime | clean_image_name}}"` will cause your build to 75 fail because the image name will start with a number, which is why in the 76 above example we prepend the isotime with "mybuild". 77 78 #### Specific to Azure builders: 79 80 - `clean_image_name` - Azure managed image names can only contain 81 certain characters and the maximum length is 80. This function 82 will replace illegal characters with a "-" character. Example: 83 84 `"mybuild-{{isotime | clean_image_name}}"` will become 85 `mybuild-2017-10-18t02-06-30z`. 86 87 Note: Valid Azure image names must match the regex 88 `^[^_\\W][\\w-._)]{0,79}$` 89 90 This engine does not guarantee that the final image name will 91 match the regex; it will not truncate your name if it exceeds 80 92 characters, and it will not validate that the beginning and end of 93 the engine's output are valid. It will truncate invalid 94 characters from the end of the name when converting illegal 95 characters. For example, `"managed_image_name: "My-Name::"` will 96 be converted to `"managed_image_name: "My-Name"` 97 98 ## Template variables 99 100 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. 101 102 ``` liquid 103 { 104 "provisioners": [ 105 { 106 "type": "shell", 107 "execute_command": "{{.Vars}} sudo -E -S bash '{{.Path}}'", 108 "scripts": [ 109 "scripts/bootstrap.sh" 110 ] 111 } 112 ] 113 } 114 ``` 115 116 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. 117 118 -> **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. 119 120 # isotime Function Format Reference 121 122 Formatting for the function `isotime` uses the magic reference date **Mon Jan 2 123 15:04:05 -0700 MST 2006**, which breaks down to the following: 124 125 <table class="table table-bordered table-condensed"> 126 <thead> 127 <tr> 128 <th> 129 </th> 130 <th align="center"> 131 Day of Week 132 </th> 133 <th align="center"> 134 Month 135 </th> 136 <th align="center"> 137 Date 138 </th> 139 <th align="center"> 140 Hour 141 </th> 142 <th align="center"> 143 Minute 144 </th> 145 <th align="center"> 146 Second 147 </th> 148 <th align="center"> 149 Year 150 </th> 151 <th align="center"> 152 Timezone 153 </th> 154 </tr> 155 </thead> 156 <tr> 157 <th> 158 Numeric 159 </th> 160 <td align="center"> 161 - 162 </td> 163 <td align="center"> 164 01 165 </td> 166 <td align="center"> 167 02 168 </td> 169 <td align="center"> 170 03 (15) 171 </td> 172 <td align="center"> 173 04 174 </td> 175 <td align="center"> 176 05 177 </td> 178 <td align="center"> 179 06 180 </td> 181 <td align="center"> 182 -0700 183 </td> 184 </tr> 185 <tr> 186 <th> 187 Textual 188 </th> 189 <td align="center"> 190 Monday (Mon) 191 </td> 192 <td align="center"> 193 January (Jan) 194 </td> 195 <td align="center"> 196 - 197 </td> 198 <td align="center"> 199 - 200 </td> 201 <td align="center"> 202 - 203 </td> 204 <td align="center"> 205 - 206 </td> 207 <td align="center"> 208 - 209 </td> 210 <td align="center"> 211 MST 212 </td> 213 </tr> 214 </table> 215 *The values in parentheses are the abbreviated, or 24-hour clock values* 216 217 Note that "-0700" is always formatted into "+0000" because `isotime` is always UTC time. 218 219 Here are some example formatted time, using the above format options: 220 221 ``` liquid 222 isotime = June 7, 7:22:43pm 2014 223 224 {{isotime "2006-01-02"}} = 2014-06-07 225 {{isotime "Mon 1504"}} = Sat 1922 226 {{isotime "02-Jan-06 03\_04\_05"}} = 07-Jun-2014 07\_22\_43 227 {{isotime "Hour15Year200603"}} = Hour19Year201407 228 ``` 229 230 Please note that double quote characters need escaping inside of templates (in this case, on the `ami_name` value): 231 232 ``` json 233 { 234 "builders": [ 235 { 236 "type": "amazon-ebs", 237 "access_key": "...", 238 "secret_key": "...", 239 "region": "us-east-1", 240 "source_ami": "ami-fce3c696", 241 "instance_type": "t2.micro", 242 "ssh_username": "ubuntu", 243 "ami_name": "packer {{isotime \"2006-01-02\"}}" 244 } 245 ] 246 } 247 ``` 248 249 -> **Note:** See the [Amazon builder](/docs/builders/amazon.html) documentation for more information on how to correctly configure the Amazon builder in this example. 250 251 # split Function Format Reference 252 253 The function `split` takes an input string, a seperator string, and a numeric component value and returns the requested substring. 254 255 Here are some examples using the above options: 256 257 ``` liquid 258 build_name = foo-bar-provider 259 260 {{split build_name "-" 0}} = foo 261 {{split "fixed-string" "-" 1}} = string 262 ``` 263 264 Please note that double quote characters need escaping inside of templates (in this case, on the `fixed-string` value): 265 266 ``` json 267 { 268 "post-processors": [ 269 [ 270 { 271 "type": "vagrant", 272 "compression_level": 9, 273 "keep_input_artifact": false, 274 "vagrantfile_template": "tpl/{{split build_name \"-\" 1}.rb", 275 "output": "output/{{build_name}}.box", 276 "only": [ 277 "org-name-provider" 278 ] 279 } 280 ] 281 ] 282 } 283 ```