ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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.
This commit is contained in:
Martin Atkins 2018-05-13 15:12:49 -07:00
parent d72d9fde16
commit b3239e8f1f
1 changed files with 82 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
website/docs/configuration/terraform.html.md
View File

@ -1,85 +1,119 @@
--- ---
layout: "docs" layout: "docs"
page_title: "Configuring Terraform" page_title: "Configuring Terraform Settings"
sidebar_current: "docs-config-terraform" sidebar_current: "docs-config-terraform"
description: |- 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, The special `terraform` configuration block type is used to configure some
such as requiring a minimum Terraform version to execute a configuration. behaviors of Terraform itself, such as requiring a minimum Terraform version to
apply your configuration.
This page assumes you're familiar with the ## Terraform Block Syntax
[configuration syntax](/docs/configuration/syntax.html)
already.
## Example Terraform-specific settings are gathered together into `terraform` blocks:
Terraform configuration looks like the following:
```hcl ```hcl
terraform { 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 ## Configuring a Terraform Backend
`required_version` and `backend`.
`required_version` specifies a set of version constraints The selected _backend_ for a Terraform configuration defines exactly where
that must be met to perform operations on this configuration. If the and how operations are performed, where [state](/docs/state/index.html) is
running Terraform version doesn't meet these constraints, an error stored, etc. Most non-trivial Terraform configurations will have a backend
is shown. See the section below dedicated to this option. configuration that configures a remote backend to allow collaboration within
a team.
See [backends](/docs/backends/index.html) for more detail on the `backend` A backend configuration is given in a nested `backend` block within a
configuration. `terraform` block:
**No value within the `terraform` block can use interpolations.** The ```hcl
`terraform` block is loaded very early in the execution of Terraform terraform {
and interpolations are not yet available. 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 ## Specifying a Required Terraform Version
The `required_version` setting can be used to require a specific version The `required_version` setting can be used to constrain which versions of
of Terraform. If the running version of Terraform doesn't match the Terraform Core can be used with your configuration. If the running version of
constraints specified, Terraform will show an error and exit. 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 When you use [child modules](/docs/configuration/modules.html), each module
version requirements specified by the complete module tree must be can specify its own version requirements. The requirements of all modules
satisified. This means that the `required_version` setting can be used in the tree must be satisfied.
by a module to require that all consumers of a module also use a specific
version.
The value of this configuration is a comma-separated list of constraints. Use Terraform Core version constraints in a collaborative environment to
A constraint is an operator followed by a version, such as `> 0.7.0`. ensure that everyone is using a spceific Terraform version, or using at least
Constraints support the following operations: 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 version number
- `~>`: pessimistic constraint operator. Example: for `~> 0.9`, this means * `~>`: pessimistic constraint operator, constraining both the oldest and
`>= 0.9, < 1.0`. Example: for `~> 0.8.4`, this means `>= 0.8.4, < 0.9` 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 Re-usable modules should constrain only the minimum allowed version, such
minimum version ensures that a module operates as expected, but gives as `>= 0.12.0`. This specifies the earliest version that the module is
the consumer flexibility to use newer versions. 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 { 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.