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:
Radek Simko 2021-06-18 17:20:00 +01:00 committed by GitHub
parent 4daf798b21
commit bb868606ea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 29 additions and 15 deletions

View File

@ -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 which apply across all Terraform working directories. This is separate from
[your infrastructure configuration](/docs/language/index.html). [your infrastructure configuration](/docs/language/index.html).
## Location ## Locations
The configuration is placed in a single file whose location depends on the The configuration can be placed in a single file whose location depends
host operating system: on the host operating system:
* On Windows, the file must be named `terraform.rc` and placed * On Windows, the file must be named `terraform.rc` and placed
in the relevant user's `%APPDATA%` directory. The physical location 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 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). 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 ## Configuration File Syntax

View File

@ -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 graph, so this function cannot be used with files that are generated
dynamically during a Terraform operation. 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 ## Examples
### Lists ### 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 ~} %{ for addr in ip_addrs ~}
@ -54,7 +59,7 @@ backend ${addr}:${port}
The `templatefile` function renders the template: 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.1:8080
backend 10.0.0.2:8080 backend 10.0.0.2:8080
@ -62,7 +67,7 @@ backend 10.0.0.2:8080
### Maps ### 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 } %{ for config_key, config_value in config }
@ -74,7 +79,7 @@ The `templatefile` function renders the template:
``` ```
> templatefile( > templatefile(
"${path.module}/config.tmpl", "${path.module}/config.tftpl",
{ {
config = { config = {
"x" = "y" "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 this will produce a valid JSON or YAML representation of the given data
structure, without the need to manually handle escaping or delimiters. structure, without the need to manually handle escaping or delimiters.
In the latest examples above, the repetition based on elements of `ip_addrs` is In the latest examples above, the repetition based on elements of `ip_addrs` is

View File

@ -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_. the arguments are omitted, we call this a _partial configuration_.
With a partial configuration, the remaining configuration arguments must be With a partial configuration, the remaining configuration arguments must be
provided as part of provided as part of [the initialization process](/docs/cli/init/index.html).
[the initialization process](/docs/cli/init/index.html).
There are several ways to supply the remaining arguments: There are several ways to supply the remaining arguments:
* **File**: A configuration file may be specified via the `init` command line. * **File**: A configuration file may be specified via the `init` command line.
To specify a file, use the `-backend-config=PATH` option when running To specify a file, use the `-backend-config=PATH` option when running
`terraform init`. If the file contains secrets it may be kept in `terraform init`. If the file contains secrets it may be kept in
a secure data store, such as a secure data store, such as [Vault](https://www.vaultproject.io/),
[Vault](https://www.vaultproject.io/), in which case it must be downloaded in which case it must be downloaded to the local disk before running Terraform.
to the local disk before running Terraform.
* **Command-line key/value pairs**: Key/value pairs can be specified via the * **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 `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 A backend configuration file has the contents of the `backend` block as
top-level attributes, without the need to wrap it in another `terraform` top-level attributes, without the need to wrap it in another `terraform`
or `backend` block: or `backend` block:
@ -121,6 +122,13 @@ path = "example_app/terraform_state"
scheme = "https" 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 The same settings can alternatively be specified on the command line as
follows: follows:

View File

@ -139,7 +139,7 @@ terraform {
Backend configuration file: Backend configuration file:
```hcl ```hcl
# backend.hcl # config.remote.tfbackend
workspaces { name = "workspace" } workspaces { name = "workspace" }
hostname = "app.terraform.io" hostname = "app.terraform.io"
organization = "company" organization = "company"
@ -148,7 +148,7 @@ organization = "company"
Running `terraform init` with the backend file: Running `terraform init` with the backend file:
```sh ```sh
terraform init -backend-config=backend.hcl terraform init -backend-config=config.remote.tfbackend
``` ```
### Data Source Configuration ### Data Source Configuration