website: document escaping template vars [GH-9897]

This commit is contained in:
Mitchell Hashimoto 2016-11-07 08:42:46 -08:00
parent 7dec4acfca
commit 7d6b3b80b9
No known key found for this signature in database
GPG Key ID: 744E147AA52F5B0A
3 changed files with 102 additions and 4 deletions

View File

@ -299,7 +299,7 @@ A template data source looks like:
```
data "template_file" "example" {
template = "${hello} ${world}!"
template = "$${hello} $${world}!"
vars {
hello = "goodnight"
world = "moon"
@ -313,7 +313,9 @@ output "rendered" {
Then the rendered value would be `goodnight moon!`.
You may use any of the built-in functions in your template.
You may use any of the built-in functions in your template. For more
details on template usage, please see the
[template_file documentation](/docs/providers/template/d/file.html).
### Using Templates with Count

View File

@ -12,6 +12,8 @@ Renders a template from a file.
## Example Usage
From a file:
```
data "template_file" "init" {
template = "${file("${path.module}/init.tpl")}"
@ -20,7 +22,18 @@ data "template_file" "init" {
consul_address = "${aws_instance.consul.private_ip}"
}
}
```
Inline:
```
data "template_file" "init" {
template = "$${consul_address}:1234"
vars {
consul_address = "${aws_instance.consul.private_ip}"
}
}
```
## Argument Reference
@ -50,6 +63,65 @@ The following attributes are exported:
* `vars` - See Argument Reference above.
* `rendered` - The final rendered template.
## Template files syntax
## Template Syntax
The syntax of the template files is [documented here](/docs/configuration/interpolation.html), under the "Templates" section.
The syntax of the template files is the same as
[standard interpolation syntax](/docs/configuration/interpolation.html),
but you only have access to the variables defined in the `vars` section.
To access interpolations that are normally available to Terraform
configuration (such as other variables, resource attributes, module
outputs, etc.) you'll have to expose them via `vars` as shown below:
```
data "template_file" "init" {
# ...
vars {
foo = "${var.foo}"
attr = "${aws_instance.foo.private_ip}"
}
}
```
## Inline Templates
Inline templates allow you to specify the template string inline without
loading a file. An example is shown below:
```
data "template_file" "init" {
template = "$${consul_address}:1234"
vars {
consul_address = "${aws_instance.consul.private_ip}"
}
}
```
-> **Important:** Template variables in an inline template (such as
`consul_address` above) must be escaped with a double-`$`. Unescaped
interpolations will be processed by Terraform normally prior to executing
the template.
An example of mixing escaped and non-escaped interpolations in a template:
```
variable "port" { default = 80 }
data "template_file" "init" {
template = "$${foo}:${var.port}"
vars {
foo = "${count.index}"
}
}
```
In the above example, the template is processed by Terraform first to
turn it into: `$${foo}:80`. After that, the template is processed as a
template to interpolate `foo`.
In general, you should use template variables in the `vars` block and try
not to mix interpolations. This keeps it understandable and has the benefit
that you don't have to change anything to switch your template to a file.

View File

@ -32,3 +32,27 @@ resource "aws_instance" "web" {
user_data = "${data.template_file.init.rendered}"
}
```
Or using an inline template:
```
# Template for initial configuration bash script
data "template_file" "init" {
template = "$${consul_address}:1234"
vars {
consul_address = "${aws_instance.consul.private_ip}"
}
}
# Create a web server
resource "aws_instance" "web" {
# ...
user_data = "${data.template_file.init.rendered}"
}
```
-> **Note:** Inline templates must escape their interpolations (as seen
by the double `$` above). Unescaped interpolations will be processed
_before_ the template.