From bb868606eafecce960cc027efb860b5f864d8bcf Mon Sep 17 00:00:00 2001 From: Radek Simko Date: Fri, 18 Jun 2021 17:20:00 +0100 Subject: [PATCH] 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 * Update website/docs/language/functions/templatefile.html.md Co-authored-by: Alisdair McDiarmid Co-authored-by: Alisdair McDiarmid --- website/docs/cli/config/config-file.html.md | 7 ++++--- .../language/functions/templatefile.html.md | 15 ++++++++++----- .../settings/backends/configuration.html.md | 18 +++++++++++++----- .../language/settings/backends/remote.html.md | 4 ++-- 4 files changed, 29 insertions(+), 15 deletions(-) diff --git a/website/docs/cli/config/config-file.html.md b/website/docs/cli/config/config-file.html.md index 3c8838e9b..cc4a1763a 100644 --- a/website/docs/cli/config/config-file.html.md +++ b/website/docs/cli/config/config-file.html.md @@ -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 diff --git a/website/docs/language/functions/templatefile.html.md b/website/docs/language/functions/templatefile.html.md index 95bc2b04f..22c23f3a4 100644 --- a/website/docs/language/functions/templatefile.html.md +++ b/website/docs/language/functions/templatefile.html.md @@ -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 diff --git a/website/docs/language/settings/backends/configuration.html.md b/website/docs/language/settings/backends/configuration.html.md index 23bd91b0c..886413e7e 100644 --- a/website/docs/language/settings/backends/configuration.html.md +++ b/website/docs/language/settings/backends/configuration.html.md @@ -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: diff --git a/website/docs/language/settings/backends/remote.html.md b/website/docs/language/settings/backends/remote.html.md index a4d2463a3..1c26169b8 100644 --- a/website/docs/language/settings/backends/remote.html.md +++ b/website/docs/language/settings/backends/remote.html.md @@ -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