Skip to content

Commit

Permalink
Document templatefile escaping for Blueprints
Browse files Browse the repository at this point in the history
Added documentation about using escape sequences when trying to generate Blueprint template bodies using the Terraform `templatefile` function. This can cause issues because both Blueprints and `templatefile` use similar template delimeters.
  • Loading branch information
adamconnelly committed Sep 27, 2023
1 parent 06d68b6 commit ca2f742
Showing 1 changed file with 82 additions and 0 deletions.
82 changes: 82 additions & 0 deletions docs/concepts/blueprint/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,88 @@ stack:
name: 'yes-my-stack'
```

### Interaction with Terraform `templatefile`

When using the Terraform [`templatefile`](https://developer.hashicorp.com/terraform/language/functions/templatefile) function to generate a Blueprint template body, you can run into issues because the Blueprint template engine and `templatefile` both use `$` as template delimeters. This can result in error messages like the following:

{% raw %}

```shell
│ Error: Error in function call
│ on main.tf line 2, in output "content":
│ 2: value = templatefile("${path.module}/test.tftpl", {
│ 3: SPACE = "root"
│ 4: })
│ ├────────────────
│ │ path.module is "."
│ Call to function "templatefile" failed: ./test.tftpl:5,31-32: Missing key/value separator; Expected an equals
│ sign ("=") to mark the beginning of the attribute value.
```

{% endraw %}

To solve this you can use `$${}` to indicate that `templatefile` should not attempt to replace a certain piece of text.

In the following example, `$${{ inputs.stack_name }}` is escaped, whereas `${SPACE}` is not:

{% raw %}

```yaml
inputs:
- id: stack_name
name: Stack name
stack:
name: $${{ inputs.stack_name }}
space: ${SPACE}
vcs:
branch: main
repository: my-repository
provider: GITHUB
vendor:
terraform:
manage_state: true
version: "1.3.0"
```

{% endraw %}

We can then use a call to `templatefile` like the following to render this template:

{% raw %}

```terraform
templatefile("${path.module}/test.tftpl", {
SPACE = "root"
})
```

{% endraw %}

This results in the following output when the template is rendered:

{% raw %}

```yaml
inputs:
- id: stack_name
name: Stack name
stack:
name: ${{ inputs.stack_name }}
space: root
vcs:
branch: main
repository: my-repository
provider: GITHUB
vendor:
terraform:
manage_state: true
version: "1.3.0"
```

{% endraw %}

## Variables

Since you probably don't want to create stacks with the exact same name and configuration, you'll use variables.
Expand Down

0 comments on commit ca2f742

Please sign in to comment.