From b3239e8f1f20c7a11e2f07182171ac746a0bedcf Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Sun, 13 May 2018 15:12:49 -0700 Subject: [PATCH] website: Update the "Terraform Settings" page for new style As part of revamping the "Configuration" portion of the website for the v0.12 release, here we update the Terraform Settings page to use a similar "guide-like" writing style as the other updated pages in this section. --- website/docs/configuration/terraform.html.md | 130 ++++++++++++------- 1 file changed, 82 insertions(+), 48 deletions(-) diff --git a/website/docs/configuration/terraform.html.md b/website/docs/configuration/terraform.html.md index 1f1391c18..7141833ab 100644 --- a/website/docs/configuration/terraform.html.md +++ b/website/docs/configuration/terraform.html.md @@ -1,85 +1,119 @@ --- layout: "docs" -page_title: "Configuring Terraform" +page_title: "Configuring Terraform Settings" sidebar_current: "docs-config-terraform" description: |- - The `terraform` configuration section is used to configure Terraform itself, such as requiring a minimum Terraform version to execute a configuration. + The "terraform" configuration section is used to configure some behaviors + of Terraform itself. --- -# Terraform Configuration +# Terraform Settings -The `terraform` configuration section is used to configure Terraform itself, -such as requiring a minimum Terraform version to execute a configuration. +The special `terraform` configuration block type is used to configure some +behaviors of Terraform itself, such as requiring a minimum Terraform version to +apply your configuration. -This page assumes you're familiar with the -[configuration syntax](/docs/configuration/syntax.html) -already. +## Terraform Block Syntax -## Example - -Terraform configuration looks like the following: +Terraform-specific settings are gathered together into `terraform` blocks: ```hcl terraform { - required_version = "> 0.7.0" + # ... } ``` -## Description +Each `terraform` block can contain a number of settings related to Terraform's +behavior. Within a `terraform` block, only constant values can be used; +arguments may not refer to named objects such as resources, input variables, +etc, and may not use any of the Terraform language built-in functions. -The `terraform` block configures the behavior of Terraform itself. +The various options supported within a `terraform` block are described in the +following sections. -The currently only allowed configurations within this block are -`required_version` and `backend`. +## Configuring a Terraform Backend -`required_version` specifies a set of version constraints -that must be met to perform operations on this configuration. If the -running Terraform version doesn't meet these constraints, an error -is shown. See the section below dedicated to this option. +The selected _backend_ for a Terraform configuration defines exactly where +and how operations are performed, where [state](/docs/state/index.html) is +stored, etc. Most non-trivial Terraform configurations will have a backend +configuration that configures a remote backend to allow collaboration within +a team. -See [backends](/docs/backends/index.html) for more detail on the `backend` -configuration. +A backend configuration is given in a nested `backend` block within a +`terraform` block: -**No value within the `terraform` block can use interpolations.** The -`terraform` block is loaded very early in the execution of Terraform -and interpolations are not yet available. +```hcl +terraform { + backend "s3" { + # (backend-specific settings...) + } +} +``` + +More information on backend configuration can be found in +[the _Backends_ section](/docs/backends/index.html). ## Specifying a Required Terraform Version -The `required_version` setting can be used to require a specific version -of Terraform. If the running version of Terraform doesn't match the -constraints specified, Terraform will show an error and exit. +The `required_version` setting can be used to constrain which versions of +Terraform Core can be used with your configuration. If the running version of +Terraform doesn't match the constraints specified, Terraform will produce +an error and exit without taking any further actions. -When [modules](/docs/configuration/modules.html) are used, all Terraform -version requirements specified by the complete module tree must be -satisified. This means that the `required_version` setting can be used -by a module to require that all consumers of a module also use a specific -version. +When you use [child modules](/docs/configuration/modules.html), each module +can specify its own version requirements. The requirements of all modules +in the tree must be satisfied. -The value of this configuration is a comma-separated list of constraints. -A constraint is an operator followed by a version, such as `> 0.7.0`. -Constraints support the following operations: +Use Terraform Core version constraints in a collaborative environment to +ensure that everyone is using a spceific Terraform version, or using at least +a minimum Terraform version that has behavior expected by the configuration. -- `=` (or no operator): exact version equality +The `required_version` setting applies only to the version of Terraform Core. +Various behaviors of Terraform are actually implemented by Terraform Providers, +which are released on a cycle independent to Terraform Core and to each other. +Use [provider version constraints](/docs/configuration/providers.html#provider-versions) +to make similar constraints on which provider versions may be used. -- `!=`: version not equal +The value for `required_version` is a string containing a comma-separated +list of constraints. Each constraint is an operator followed by a version +number, such as `> 0.12.0`. The following constraint operators are allowed: -- `>`, `>=`, `<`, `<=`: version comparison, where "greater than" is a larger +* `=` (or no operator): exact version equality + +* `!=`: version not equal + +* `>`, `>=`, `<`, `<=`: version comparison, where "greater than" is a larger version number -- `~>`: pessimistic constraint operator. Example: for `~> 0.9`, this means - `>= 0.9, < 1.0`. Example: for `~> 0.8.4`, this means `>= 0.8.4, < 0.9` +* `~>`: pessimistic constraint operator, constraining both the oldest and + newest version allowed. For example, `~> 0.9` is equivalent to + `>= 0.9, < 1.0`, and `~> 0.8.4`, is equivalent to `>= 0.8.4, < 0.9` -For modules, a minimum version is recommended, such as `> 0.8.0`. This -minimum version ensures that a module operates as expected, but gives -the consumer flexibility to use newer versions. +Re-usable modules should constrain only the minimum allowed version, such +as `>= 0.12.0`. This specifies the earliest version that the module is +compatible with while leaving the user of the module flexibility to upgrade +to newer versions of Terraform without altering the module. -## Syntax +## Specifying Required Provider Versions -The full syntax is: +The `required_providers` setting is a map specifying a version constraint for +each provider required by your configuration. -```text +This is one of several ways to define +[provider version constraints](/docs/configuration/providers.html#provider-versions), +and is particularly suited to re-usable modules that expect a provider +configuration to be provided by their caller but still need to impose a +minimum version for that provider. + +```hcl terraform { - required_version = VALUE + required_providers = { + aws = ">= 1.0.0" + } } ``` + +Re-usable modules should constrain only the minimum allowed version, such +as `>= 1.0.0`. This specifies the earliest version that the module is +compatible with while leaving the user of the module flexibility to upgrade +to newer versions of the provider without altering the module.