website: flesh out docs for template_dir resource
This commit is contained in:
parent
eaac9fbca3
commit
da49171b06
|
@ -3,38 +3,87 @@ layout: "template"
|
||||||
page_title: "Template: template_dir"
|
page_title: "Template: template_dir"
|
||||||
sidebar_current: "docs-template-resource-dir"
|
sidebar_current: "docs-template-resource-dir"
|
||||||
description: |-
|
description: |-
|
||||||
Renders templates from a directory.
|
Renders a directory of templates.
|
||||||
---
|
---
|
||||||
|
|
||||||
# template_dir
|
# template_dir
|
||||||
|
|
||||||
Renders templates from a directory.
|
Renders a directory containing templates into a separate directory of
|
||||||
|
corresponding rendered files.
|
||||||
|
|
||||||
|
`template_dir` is similar to [`template_file`](../d/file.html) but it walks
|
||||||
|
a given source directory and treats every file it encounters as a template,
|
||||||
|
rendering it to a corresponding file in the destination directory.
|
||||||
|
|
||||||
|
~> **Note** When working with local files, Terraform will detect the resource
|
||||||
|
as having been deleted each time a configuration is applied on a new machine
|
||||||
|
where the destination dir is not present and will generate a diff to create
|
||||||
|
it. This may cause "noise" in diffs in environments where configurations are
|
||||||
|
routinely applied by many different users or within automation systems.
|
||||||
|
|
||||||
## Example Usage
|
## Example Usage
|
||||||
|
|
||||||
|
The following example shows how one might use this resource to produce a
|
||||||
|
directory of configuration files to upload to a compute instance, using
|
||||||
|
Amazon EC2 as a placeholder.
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
data "template_directory" "init" {
|
resource "template_dir" "config" {
|
||||||
source_dir = "${path.cwd}/templates"
|
source_dir = "${path.module}/instance_config_templates"
|
||||||
destination_dir = "${path.cwd}/templates.generated"
|
destination_dir = "${path.cwd}/instance_config"
|
||||||
|
|
||||||
vars {
|
vars {
|
||||||
consul_address = "${aws_instance.consul.private_ip}"
|
consul_addr = "${var.consul_addr}"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
resource "aws_instance" "server" {
|
||||||
|
ami = "${var.server_ami}"
|
||||||
|
instance_type = "t2.micro"
|
||||||
|
|
||||||
|
connection {
|
||||||
|
# ...connection configuration...
|
||||||
|
}
|
||||||
|
|
||||||
|
provisioner "file" {
|
||||||
|
# Referencing the template_dir resource ensures that it will be
|
||||||
|
# created or updated before this aws_instance resource is provisioned.
|
||||||
|
source = "${template_dir.config.destination_dir}"
|
||||||
|
destination = "/etc/myapp"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
variable "consul_addr" {}
|
||||||
|
|
||||||
|
variable "server_ami" {}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Argument Reference
|
## Argument Reference
|
||||||
|
|
||||||
The following arguments are supported:
|
The following arguments are supported:
|
||||||
|
|
||||||
* `source_path` - (Required) Path to the directory where the files to template reside.
|
* `source_dir` - (Required) Path to the directory where the files to template reside.
|
||||||
|
|
||||||
* `destination_path` - (Required) Path to the directory where the templated files will be written.
|
* `destination_dir` - (Required) Path to the directory where the templated files will be written.
|
||||||
|
|
||||||
* `vars` - (Optional) Variables for interpolation within the template. Note
|
* `vars` - (Optional) Variables for interpolation within the template. Note
|
||||||
that variables must all be primitives. Direct references to lists or maps
|
that variables must all be primitives. Direct references to lists or maps
|
||||||
will cause a validation error.
|
will cause a validation error.
|
||||||
|
|
||||||
NOTE: Any required parent directories are created automatically. Additionally, any external modification to either the files in the source or destination directories will trigger the resource to be re-created.
|
Any required parent directories of `destination_dir` will be created
|
||||||
|
automatically, and any pre-existing file or directory at that location will
|
||||||
|
be deleted before template rendering begins.
|
||||||
|
|
||||||
|
After rendering this resource remembers the content of both the source and
|
||||||
|
destination directories in the Terraform state, and will plan to recreate the
|
||||||
|
output directory if any changes are detected during the plan phase.
|
||||||
|
|
||||||
|
Note that it is _not_ safe to use the `file` interpolation function to read
|
||||||
|
files create by this resource, since that function can be evaluated before the
|
||||||
|
destination directory has been created or updated. It *is* safe to use the
|
||||||
|
generated files with resources that directly take filenames as arguments,
|
||||||
|
as long as the path is constructed using the `destination_dir` attribute
|
||||||
|
to create a dependency relationship with the `template_dir` resource.
|
||||||
|
|
||||||
## Template Syntax
|
## Template Syntax
|
||||||
|
|
||||||
|
@ -44,7 +93,7 @@ but you only have access to the variables defined in the `vars` section.
|
||||||
|
|
||||||
To access interpolations that are normally available to Terraform
|
To access interpolations that are normally available to Terraform
|
||||||
configuration (such as other variables, resource attributes, module
|
configuration (such as other variables, resource attributes, module
|
||||||
outputs, etc.) you'll have to expose them via `vars` as shown below:
|
outputs, etc.) you can expose them via `vars` as shown below:
|
||||||
|
|
||||||
```hcl
|
```hcl
|
||||||
resource "template_dir" "init" {
|
resource "template_dir" "init" {
|
||||||
|
@ -55,4 +104,13 @@ resource "template_dir" "init" {
|
||||||
attr = "${aws_instance.foo.private_ip}"
|
attr = "${aws_instance.foo.private_ip}"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Attributes
|
||||||
|
|
||||||
|
This resource exports the following attributes:
|
||||||
|
|
||||||
|
* `destination_dir` - The destination directory given in configuration.
|
||||||
|
Interpolate this attribute into other resource configurations to create
|
||||||
|
a dependency to ensure that the destination directory is populated before
|
||||||
|
another resource attempts to read it.
|
||||||
|
|
Loading…
Reference in New Issue