From 7d6b3b80b94ecbab6a6c277ad6131038bf9180c0 Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <mitchell.hashimoto@gmail.com>
Date: Mon, 7 Nov 2016 08:42:46 -0800
Subject: [PATCH] website: document escaping template vars [GH-9897]

---
 .../docs/configuration/interpolation.html.md  |  6 +-
 .../docs/providers/template/d/file.html.md    | 76 ++++++++++++++++++-
 .../providers/template/index.html.markdown    | 24 ++++++
 3 files changed, 102 insertions(+), 4 deletions(-)

diff --git a/website/source/docs/configuration/interpolation.html.md b/website/source/docs/configuration/interpolation.html.md
index a9c655317..5d791edf3 100644
--- a/website/source/docs/configuration/interpolation.html.md
+++ b/website/source/docs/configuration/interpolation.html.md
@@ -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
 
diff --git a/website/source/docs/providers/template/d/file.html.md b/website/source/docs/providers/template/d/file.html.md
index b47f7e286..90c7a61cf 100644
--- a/website/source/docs/providers/template/d/file.html.md
+++ b/website/source/docs/providers/template/d/file.html.md
@@ -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.
diff --git a/website/source/docs/providers/template/index.html.markdown b/website/source/docs/providers/template/index.html.markdown
index 9fce6da1c..9edd2a87f 100644
--- a/website/source/docs/providers/template/index.html.markdown
+++ b/website/source/docs/providers/template/index.html.markdown
@@ -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.