docs: Document naming conventions for templates & backend configs (#28924)
* docs: Document naming conventions for templates & backend configs * Update website/docs/cli/config/config-file.html.md Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com> * Update website/docs/language/functions/templatefile.html.md Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com> Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com>
This commit is contained in:
parent
4daf798b21
commit
bb868606ea
|
@ -13,10 +13,10 @@ The CLI configuration file configures per-user settings for CLI behaviors,
|
|||
which apply across all Terraform working directories. This is separate from
|
||||
[your infrastructure configuration](/docs/language/index.html).
|
||||
|
||||
## Location
|
||||
## Locations
|
||||
|
||||
The configuration is placed in a single file whose location depends on the
|
||||
host operating system:
|
||||
The configuration can be placed in a single file whose location depends
|
||||
on the host operating system:
|
||||
|
||||
* On Windows, the file must be named `terraform.rc` and placed
|
||||
in the relevant user's `%APPDATA%` directory. The physical location
|
||||
|
@ -34,6 +34,7 @@ confirm the filename.
|
|||
|
||||
The location of the Terraform CLI configuration file can also be specified
|
||||
using the `TF_CLI_CONFIG_FILE` [environment variable](/docs/cli/config/environment-variables.html).
|
||||
Any such file should follow the naming pattern `*.tfrc`.
|
||||
|
||||
## Configuration File Syntax
|
||||
|
||||
|
|
|
@ -39,11 +39,16 @@ beginning of a Terraform run. Functions do not participate in the dependency
|
|||
graph, so this function cannot be used with files that are generated
|
||||
dynamically during a Terraform operation.
|
||||
|
||||
`*.tftpl` is the recommended naming pattern to use for your template files.
|
||||
Terraform will not prevent you from using other names, but following this
|
||||
convention will help your editor understand the content and likely provide
|
||||
better editing experience as a result.
|
||||
|
||||
## Examples
|
||||
|
||||
### Lists
|
||||
|
||||
Given a template file `backends.tpl` with the following content:
|
||||
Given a template file `backends.tftpl` with the following content:
|
||||
|
||||
```
|
||||
%{ for addr in ip_addrs ~}
|
||||
|
@ -54,7 +59,7 @@ backend ${addr}:${port}
|
|||
The `templatefile` function renders the template:
|
||||
|
||||
```
|
||||
> templatefile("${path.module}/backends.tpl", { port = 8080, ip_addrs = ["10.0.0.1", "10.0.0.2"] })
|
||||
> templatefile("${path.module}/backends.tftpl", { port = 8080, ip_addrs = ["10.0.0.1", "10.0.0.2"] })
|
||||
backend 10.0.0.1:8080
|
||||
backend 10.0.0.2:8080
|
||||
|
||||
|
@ -62,7 +67,7 @@ backend 10.0.0.2:8080
|
|||
|
||||
### Maps
|
||||
|
||||
Given a template file `config.tmpl` with the following content:
|
||||
Given a template file `config.tftpl` with the following content:
|
||||
|
||||
```
|
||||
%{ for config_key, config_value in config }
|
||||
|
@ -74,7 +79,7 @@ The `templatefile` function renders the template:
|
|||
|
||||
```
|
||||
> templatefile(
|
||||
"${path.module}/config.tmpl",
|
||||
"${path.module}/config.tftpl",
|
||||
{
|
||||
config = {
|
||||
"x" = "y"
|
||||
|
@ -113,7 +118,7 @@ ${yamlencode({
|
|||
})}
|
||||
```
|
||||
|
||||
Given the same input as the `backends.tmpl` example in the previous section,
|
||||
Given the same input as the `backends.tftpl` example in the previous section,
|
||||
this will produce a valid JSON or YAML representation of the given data
|
||||
structure, without the need to manually handle escaping or delimiters.
|
||||
In the latest examples above, the repetition based on elements of `ip_addrs` is
|
||||
|
|
|
@ -70,16 +70,15 @@ automatically by an automation script running Terraform. When some or all of
|
|||
the arguments are omitted, we call this a _partial configuration_.
|
||||
|
||||
With a partial configuration, the remaining configuration arguments must be
|
||||
provided as part of
|
||||
[the initialization process](/docs/cli/init/index.html).
|
||||
provided as part of [the initialization process](/docs/cli/init/index.html).
|
||||
|
||||
There are several ways to supply the remaining arguments:
|
||||
|
||||
* **File**: A configuration file may be specified via the `init` command line.
|
||||
To specify a file, use the `-backend-config=PATH` option when running
|
||||
`terraform init`. If the file contains secrets it may be kept in
|
||||
a secure data store, such as
|
||||
[Vault](https://www.vaultproject.io/), in which case it must be downloaded
|
||||
to the local disk before running Terraform.
|
||||
a secure data store, such as [Vault](https://www.vaultproject.io/),
|
||||
in which case it must be downloaded to the local disk before running Terraform.
|
||||
|
||||
* **Command-line key/value pairs**: Key/value pairs can be specified via the
|
||||
`init` command line. Note that many shells retain command-line flags in a
|
||||
|
@ -111,6 +110,8 @@ terraform {
|
|||
}
|
||||
```
|
||||
|
||||
### File
|
||||
|
||||
A backend configuration file has the contents of the `backend` block as
|
||||
top-level attributes, without the need to wrap it in another `terraform`
|
||||
or `backend` block:
|
||||
|
@ -121,6 +122,13 @@ path = "example_app/terraform_state"
|
|||
scheme = "https"
|
||||
```
|
||||
|
||||
`*.backendname.tfbackend` (e.g. `config.consul.tfbackend`) is the recommended
|
||||
naming pattern. Terraform will not prevent you from using other names but following
|
||||
this convention will help your editor understand the content and likely provide
|
||||
better editing experience as a result.
|
||||
|
||||
### Command-line key/value pairs
|
||||
|
||||
The same settings can alternatively be specified on the command line as
|
||||
follows:
|
||||
|
||||
|
|
|
@ -139,7 +139,7 @@ terraform {
|
|||
Backend configuration file:
|
||||
|
||||
```hcl
|
||||
# backend.hcl
|
||||
# config.remote.tfbackend
|
||||
workspaces { name = "workspace" }
|
||||
hostname = "app.terraform.io"
|
||||
organization = "company"
|
||||
|
@ -148,7 +148,7 @@ organization = "company"
|
|||
Running `terraform init` with the backend file:
|
||||
|
||||
```sh
|
||||
terraform init -backend-config=backend.hcl
|
||||
terraform init -backend-config=config.remote.tfbackend
|
||||
```
|
||||
|
||||
### Data Source Configuration
|
||||
|
|
Loading…
Reference in New Issue