website: Add new "glue"/overview pages for CLI and language docs

The new nav structure demanded a few new pages that give context about a feature
or workflow. In a few cases, they take text from an existing page.

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
Co-authored-by: Judith Malnick <judith.patudith@gmail.com>
This commit is contained in:
Nick Fagerlund 2020-10-26 18:15:36 -07:00
parent d01faf1cb2
commit 2c02233a16
26 changed files with 1005 additions and 170 deletions

View File

@ -1,43 +1,20 @@
--- ---
layout: "docs" layout: "docs"
page_title: "Documentation" page_title: "Terraform CLI Documentation"
sidebar_current: "docs-home" sidebar_current: "docs-home"
description: |- description: |-
Documentation for Terraform's core open source features, including the Documentation for Terraform's CLI-based workflows.
configuration language, the commands, and the main Terraform providers.
--- ---
# Terraform CLI Documentation # Terraform CLI Documentation
Welcome to the Terraform CLI documentation! > **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
## What's in This Section of the Docs? This is the documentation for Terraform CLI. It is relevant to anyone working
with Terraform's CLI-based workflows; this includes people who use Terraform CLI
by itself, as well as those who use Terraform CLI in conjunction with Terraform
Cloud or Terraform Enterprise.
This section contains reference documentation for Terraform's core open source Notably, this documentation does not cover the syntax and usage of the Terraform
features, including the language. For that, see the
[configuration language](/docs/configuration/index.html), the [Terraform Language Documentation](/docs/configuration/index.html).
[command-line tools](/docs/commands/index.html), and the main
[Terraform providers](/docs/providers/index.html). Use the navigation sidebar
to browse the various subsections.
## Who is This For?
The Terraform CLI docs are relevant to _all Terraform users,_ including open
source users and Terraform Cloud users.
Since these docs are reference material, they are mainly written for
_intermediate and advanced users,_ who need to find complete and detailed
information quickly.
- **New user?** Try the
[Get Started collection](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
at HashiCorp Learn, then return
here once you've used Terraform to manage some simple resources.
- **Curious about Terraform?** See [Introduction to Terraform](/intro/index.html)
for a broad overview of what Terraform is and why people use it.
## What's Elsewhere?
This is not the only section of the Terraform docs! You can find out more at the
[Terraform docs home page](/docs/index.html), or you can jump between sections
using the "Other Docs" area of the navigation sidebar.

View File

@ -0,0 +1,29 @@
---
layout: "docs"
page_title: "Authentication - Terraform CLI"
---
# CLI Authentication
> **Hands-on:** Try the [Authenticate the CLI with Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-login?in=terraform/cloud&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
[Terraform Cloud](/docs/cloud/index.html) and
[Terraform Enterprise](/docs/enterprise/index.html) are platforms that perform
Terraform runs to provision infrastructure, offering a collaboration-focused
environment that makes it easier for teams to use Terraform together. (For
expediency, the content below refers to both products as "Terraform Cloud.")
Terraform CLI integrates with Terraform Cloud in several ways — it can be a
front-end for [CLI-driven runs](/docs/cloud/run/cli.html) in Terraform Cloud,
and can also use Terraform Cloud as a state backend and a private module
registry. All of these integrations require you to authenticate Terraform CLI
with your Terraform Cloud account.
The best way to handle CLI authentication is with the `login` and `logout`
commands, which help automate the process of getting an API token for your
Terraform Cloud user account.
For details, see:
- [The `terraform login` command](/docs/commands/login.html)
- [The `terraform logout` command](/docs/commands/logout.html)

View File

@ -0,0 +1,43 @@
---
layout: "docs"
page_title: "Writing and Modifying Code - Terraform CLI"
---
# Writing and Modifying Terraform Code
The [Terraform language](/docs/configuration/index.html) is Terraform's primary
user interface, and all of Terraform's workflows rely on configurations written
in the Terraform language.
Terraform CLI includes several commands to make Terraform code more convenient
to work with. Integrating these commands into your editing workflow can
potentially save you time and effort.
- [The `terraform console` command](/docs/commands/console.html) starts an
interactive shell for evaluating Terraform
[expressions](/docs/configuration/expressions.html), which can be a faster way
to verify that a particular resource argument results in the value you expect.
- [The `terraform fmt` command](/docs/commands/fmt.html) rewrites Terraform
configuration files to a canonical format and style, so you don't have to
waste time making minor adjustments for readability and consistency. It works
well as a pre-commit hook in your version control system.
- [The `terraform validate` command](/docs/commands/validate.html) validates the
syntax and arguments of the Terraform configuration files in a directory,
including argument and attribute names and types for resources and modules.
The `plan` and `apply` commands automatically validate a configuration before
performing any other work, so `validate` isn't a crucial part of the core
workflow, but it can be very useful as a pre-commit hook or as part of a
continuous integration pipeline.
- [The `0.13upgrade` command](/docs/commands/0.13upgrade.html) and
[the `0.12upgrade` command](/docs/commands/0.12upgrade.html) can automatically
modify the configuration files in a Terraform module to help deal with major
syntax changes that occurred in the 0.13 and 0.12 releases of Terraform. Both
of these commands are only available in the Terraform version they are
associated with, and you are expected to upgrade older code to be compatible
with 0.12 before attempting to make it compatible with 0.13. For more detailed
information about updating code for new Terraform versions, see the [upgrade
guides](/upgrade-guides/index.html) in the Terraform language docs.

View File

@ -0,0 +1,22 @@
---
layout: "docs"
page_title: "CLI Configuration - Terraform CLI"
---
# CLI Configuration
Terraform CLI can be configured with some global settings, which are separate
from any Terraform configuration and which apply across all working directories.
We've designed Terraform such that an average user running Terraform CLI
interactively will not need to interact with any of these settings. As a result,
most of the global settings relate to advanced or automated workflows, or
unusual environmental conditions like running Terraform on an airgapped
instance.
- The [CLI config file](/docs/commands/cli-config.html) configures provider
installation and security features.
- Several [environment variables](/docs/commands/environment-variables.html) can
configure Terraform's inputs and outputs; this includes some alternate ways to
provide information that is usually passed on the command line or read from
the state of the shell.

View File

@ -0,0 +1,71 @@
---
layout: "docs"
page_title: "Initializing Working Directories - Terraform CLI"
---
# Initializing Working Directories
Terraform expects to be invoked from a working directory that contains
configuration files written in
[the Terraform language](/docs/configuration/index.html). Terraform uses
configuration content from this directory, and also uses the directory to store
settings, cached plugins and modules, and sometimes state data.
A working directory must be initialized before Terraform can perform any
operations in it (like provisioning infrastructure or modifying state).
## Working Directory Contents
A Terraform working directory typically contains:
- A Terraform configuration describing resources Terraform should manage. This
configuration is expected to change over time.
- A hidden `.terraform` directory, which Terraform uses to manage cached
provider plugins and modules, record which
[workspace](/docs/cli/workspaces/index.html) is currently active, and
record the last known backend configuration in case it needs to migrate state
on the next run. This directory is automatically managed by Terraform, and is
created during initialization.
- State data, if the configuration uses the default `local` backend. This is
managed by Terraform in a `terraform.tfstate` file (if the directory only uses
the default workspace) or a `terraform.tfstate.d` directory (if the directory
uses multiple workspaces).
## Initialization
Run the `terraform init` command to initialize a working directory that contains
a Terraform configuration. After initialization, you will be able to perform
other commands, like `terraform plan` and `terraform apply`.
If you try to run a command that relies on initialization without first
initializing, the command will fail with an error and explain that you need to
run init.
Initialization performs several tasks to prepare a directory, including
accessing state in the configured backend, downloading and installing provider
plugins, and downloading modules. Under some conditions (usually when changing
from one backend to another), it might ask the user for guidance or
confirmation.
For details, see [the `terraform init` command](/docs/commands/init.html).
## Reinitialization
Certain types of changes to a Terraform configuration can require
reinitialization before normal operations can continue. This includes changes to
provider requirements, module sources or version constraints, and backend
configurations.
You can reinitialize a directory by running `terraform init` again. In fact, you
can reinitialize at any time; the init command is idempotent, and will have no
effect if no changes are required.
If reinitialization is required, any commands that rely on initialization will
fail with an error and tell you so.
## Reinitializing Only Modules
The `terraform get` command will download modules referenced in the
configuration, but will not perform the other required initialization tasks.
This command is only useful for niche workflows, and most Terraform users can
ignore it in favor of `terraform init`.

View File

@ -0,0 +1,33 @@
---
layout: "docs"
page_title: "Inspecting Infrastructure - Terraform CLI"
---
# Inspecting Infrastructure
Terraform configurations and state data include some highly structured
information about the resources they manage; this includes dependency
information, outputs (which are pieces of generated or discovered data that the
configuration's author considers important enough to surface to users), and
more.
Terraform CLI includes some commands for inspecting or transforming this data.
You can use these to integrate other tools with Terraform's infrastructure data,
or just to gain a deeper or more holistic understanding of your infrastructure.
- [The `terraform graph` command](/docs/commands/graph.html) creates a visual
representation of a configuration or a set of planned changes.
- [The `terraform output` command](/docs/commands/output.html) can get the
values for the top-level [output values](/docs/configuration/outputs.html) of
a configuration, which are often helpful when making use of the infrastructure
Terraform has provisioned.
- [The `terraform show` command](/docs/commands/show.html) can generate
human-readable versions of a state file or plan file, or generate
machine-readable versions that can be integrated with other tools.
- [The `terraform state list` command](/docs/commands/state/list.html) can list
the resources being managed by the current working directory and workspace,
providing a complete or filtered list.
- [The `terraform state show` command](/docs/commands/state/show.html) can print
all of the attributes of a given resource being managed by the current working
directory and workspace, including generated read-only attributes like the
unique ID assigned by the cloud provider.

View File

@ -0,0 +1,54 @@
---
layout: "docs"
page_title: "Managing Plugins - Terraform CLI"
---
# Managing Plugins
Terraform relies on plugins called "providers" in order to manage various types
of resources. (For more information about providers, see
[Providers](/docs/configuration/blocks/providers/index.html) in the Terraform
language docs.)
-> **Note:** Providers are currently the only plugin type most Terraform users
will interact with. Terraform also supports third-party provisioner plugins, but
we discourage their use.
Terraform downloads and/or installs any providers
[required](/docs/configuration/provider-requirements.html) by a configuration
when [initializing](/docs/cli/init/index.html) a working directory. By default,
this works without any additional interaction but requires network access to
download providers from their source registry.
You can configure Terraform's provider installation behavior to limit or skip
network access, and to enable use of providers that aren't available via a
networked source. Terraform also includes some commands to show information
about providers and to reduce the effort of installing providers in airgapped
environments.
## Configuring Plugin Installation
Terraform's configuration file includes options for caching downloaded plugins,
or explicitly specifying a local or HTTPS mirror to install plugins from. For
more information, see [CLI Config File](/docs/commands/cli-config.html).
## Getting Plugin Information
Use the [`terraform providers`](/docs/commands/providers.html) command to get information
about the providers required by the current working directory's configuration.
Use the [`terraform providers schema`](/docs/commands/providers/schema.html) command to
get machine-readable information about the resources and configuration options
offered by each provider.
## Managing Plugin Installation
Use the [`terraform providers mirror`](/docs/commands/providers/mirror.html) command to
download local copies of every provider required by the current working
directory's configuration. This directory will use the nested directory layout
that Terraform expects when installing plugins from a local source, so you can
transfer it directly to an airgapped system that runs Terraform.
Use the [`terraform providers lock`](/docs/commands/providers/lock.html) command
to update the lock file that Terraform uses to ensure predictable runs when
using ambiguous provider version constraints.

View File

@ -0,0 +1,71 @@
---
layout: "docs"
page_title: "Provisioning Infrastructure - Terraform CLI"
---
# Provisioning Infrastructure with Terraform
Terraform's primary function is to create, modify, and destroy infrastructure
resources to match the desired state described in a
[Terraform configuration](/docs/configuration/index.html).
When people refer to "running Terraform," they generally mean performing these
provisioning actions in order to affect real infrastructure objects. The
Terraform binary has many other subcommands for a wide variety of administrative
actions, but these basic provisioning tasks are the core of Terraform.
Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and
`destroy`. All of these commands require an
[initialized](/docs/cli/init/index.html) working directory, and all of them act
only upon the currently selected [workspace](/docs/cli/workspaces/index.html).
## Planning
The `terraform plan` command evaluates a Terraform configuration to determine
the desired state of all the resources it declares, then compares that desired
state to the real infrastructure objects being managed with the current working
directory and workspace. It uses state data to determine which real objects
correspond to which declared resources, and checks the current state of each
resource using the relevant infrastructure provider's API.
Once it has determined the difference between the current state and the desired
state, `terraform plan` presents a description of the changes necessary to
achieve the desired state. It _does not_ perform any actual changes to real
world infrastructure objects; it only presents a plan for making changes.
Plans are usually run to validate configuration changes and confirm that the
resulting actions are as expected. However, `terraform plan` can also save its
plan as a runnable artifact, which `terraform apply` can use to carry out those
exact changes.
For details, see [the `terraform plan` command](/docs/commands/plan.html).
## Applying
The `terraform apply` command performs a plan just like `terraform plan` does,
but then actually carries out the planned changes to each resource using the
relevant infrastructure provider's API. It asks for confirmation from the user
before making any changes, unless it was explicitly told to skip approval.
By default, `terraform apply` performs a fresh plan right before applying
changes, and displays the plan to the user when asking for confirmation.
However, it can also accept a plan file produced by `terraform plan` in lieu of
running a new plan. You can use this to reliably perform an exact set of
pre-approved changes, even if the configuration or the state of the real
infrastructure has changed in the minutes since the original plan was created.
For details, see [the `terraform apply` command](/docs/commands/apply.html).
## Destroying
The `terraform destroy` command destroys all of the resources being managed by
the current working directory and workspace, using state data to determine which
real world objects correspond to managed resources. Like `terraform apply`, it
asks for confirmation before proceeding.
A destroy behaves exactly like deleting every resource from the configuration
and then running an apply, except that it doesn't require editing the
configuration. This is more convenient if you intend to provision similar
resources at a later date.
For details, see [the `terraform destroy` command](/docs/commands/destroy.html).

View File

@ -0,0 +1,30 @@
---
layout: "docs"
page_title: "Manipulating State - Terraform CLI"
---
# Manipulating Terraform State
Terraform uses [state data](/docs/state/index.html) to remember which
real-world object corresponds to each resource in the configuration;
this allows it to modify an existing object when its resource declaration
changes.
Terraform updates state automatically during plans and applies. However, it's
sometimes necessary to make deliberate adjustments to Terraform's state data,
usually to compensate for changes to the configuration or the real managed
infrastructure.
Terraform CLI supports several workflows for interacting with state:
- [Inspecting State](/docs/cli/state/inspect.html)
- [Forcing Re-creation (Tainting)](/docs/cli/state/taint.html)
- [Moving Resources](/docs/cli/state/move.html)
- Importing Pre-existing Resources (documented in the
[Importing Infrastructure](/docs/import/index.html) section)
- [Disaster Recovery](/docs/cli/state/recover.html)
~> **Important:** Modifying state data outside a normal plan or apply can cause
Terraform to lose track of managed resources, which might waste money, annoy
your colleagues, or even compromise the security of your operations. Make sure
to keep backups of your state data when modifying state out-of-band.

View File

@ -0,0 +1,21 @@
---
layout: "docs"
page_title: "Inspecting State - Terraform CLI"
---
# Inspecting State
Terraform includes some commands for reading and updating state without taking
any other actions.
- [The `terraform state list` command](/docs/commands/state/list.html)
shows the resource addresses for every resource Terraform knows about in a
configuration, optionally filtered by partial resource address.
- [The `terraform state show` command](/docs/commands/state/show.html)
displays detailed state data about one resource.
- [The `terraform refresh` command](/docs/commands/refresh.html) updates
state data to match the real-world condition of the managed resources. This is
done automatically during plans and applies, but not when interacting with
state directly.

View File

@ -0,0 +1,35 @@
---
layout: "docs"
page_title: "Moving Resources - Terraform CLI"
---
# Moving Resources
Terraform's state associates each real-world object with a configured resource
at a specific [resource address](/docs/internals/resource-addressing.html). This
is seamless when changing a resource's attributes, but Terraform will lose track
of a resource if you change its name, move it to a different module, or change
its provider.
Usually that's fine: Terraform will destroy the old resource, replace it with a
new one (using the new resource address), and update any resources that rely on
its attributes.
In cases where it's important to preserve an existing infrastructure object, you
can explicitly tell Terraform to associate it with a different configured
resource.
- [The `terraform state mv` command](/docs/commands/state/mv.html) changes
which resource address in your configuration is associated with a particular
real-world object. Use this to preserve an object when renaming a resource, or
when moving a resource into or out of a child module.
- [The `terraform state rm` command](/docs/commands/state/rm.html) tells
Terraform to stop managing a resource as part of the current working directory
and workspace, _without_ destroying the corresponding real-world object. (You
can later use `terraform import` to start managing that resource in a
different workspace or a different Terraform configuration.)
- [The `terraform state replace-provider` command](/docs/commands/state/replace-provider.html)
transfers existing resources to a new provider without requiring them to be
re-created.

View File

@ -0,0 +1,24 @@
---
layout: "docs"
page_title: "Recovering from State Disasters - Terraform CLI"
---
# Recovering from State Disasters
If something has gone horribly wrong (possibly due to accidents when performing
other state manipulation actions), you might need to take drastic actions with
your state data.
- [The `terraform force-unlock` command](/docs/commands/force-unlock.html) can
override the protections Terraform uses to prevent two processes from
modifying state at the same time. You might need this if a Terraform process
(like a normal apply) is unexpectedly terminated (like by the complete
destruction of the VM it's running in) before it can release its lock on the
state backend. Do not run this until you are completely certain what happened
to the process that caused the lock to get stuck.
- [The `terraform state pull` command](/docs/commands/state/pull.html) and
[the `terraform state push` command](/docs/commands/state/push.html) can
directly read and write entire state files from and to the configured backend.
You might need this for obtaining or restoring a state backup.

View File

@ -0,0 +1,25 @@
---
layout: "docs"
page_title: "Forcing Re-creation of Resources (Tainting) - Terraform CLI"
---
# Forcing Re-creation of Resources (Tainting)
When a resource declaration is modified, Terraform usually attempts to update
the existing resource in place (although some changes can require destruction
and re-creation, usually due to upstream API limitations).
In some cases, you might want a resource to be destroyed and re-created even
when Terraform doesn't think it's necessary. This is usually for objects that
aren't fully described by their resource arguments due to side-effects that
happen during creation; for example, a virtual machine that configures itself
with `cloud-init` on startup might no longer meet your needs if the cloud-init
configuration changes.
- [The `terraform taint` command](/docs/commands/taint.html) tells Terraform to
destroy and re-create a particular resource during the next apply, regardless
of whether its resource arguments would normally require that.
- [The `terraform untaint` command](/docs/commands/untaint.html) undoes a
previous taint, or can preserve a resource that was automatically tainted due
to failed [provisioners](/docs/provisioners/index.html).

View File

@ -0,0 +1,78 @@
---
layout: "docs"
page_title: "Managing Workspaces - Terraform CLI"
---
# Managing Workspaces
In Terraform CLI, _workspaces_ are separate instances of
[state data](/docs/state/index.html) that can be used from the same working
directory. You can use workspaces to manage multiple non-overlapping groups of
resources with the same configuration.
- Every [initialized working directory](/docs/cli/init/index.html) has at least
one workspace. (If you haven't created other workspaces, it is a workspace
named `default`.)
- For a given working directory, only one workspace can be _selected_ at a time.
- Most Terraform commands (including [provisioning](/docs/cli/run/index.html)
and [state manipulation](/docs/cli/state/index.html) commands) only interact
with the currently selected workspace.
- Use [the `terraform workspace select` command](/docs/commands/workspace/select.html)
to change the currently selected workspace.
- Use the [`terraform workspace list`](/docs/commands/workspace/list.html),
[`terraform workspace new`](/docs/commands/workspace/new.html), and
[`terraform workspace delete`](/docs/commands/workspace/delete.html) commands
to manage the available workspaces in the current working directory.
-> **Note:** Terraform Cloud and Terraform CLI both have features called
"workspaces," but they're slightly different. Terraform Cloud's workspaces
behave more like completely separate working directories.
## The Purpose of Workspaces
Since most of the resources you can manage with Terraform don't include a unique
name as part of their configuration, it's common to use the same Terraform
configuration to provision multiple groups of similar resources.
Terraform relies on [state](/docs/state/index.html) to associate resources with
real-world objects, so if you run the same configuration multiple times with
completely separate state data, Terraform can manage many non-overlapping groups
of resources. In some cases you'll want to change
[variable values](/docs/configuration/variables.html) for these different
resource collections (like when specifying differences between staging and
production deployments), and in other cases you might just want many instances
of a particular infrastructure pattern.
The simplest way to maintain multiple instances of a configuration with
completely separate state data is to use multiple
[working directories](/docs/cli/init/index.html) (with different
[backend](/docs/configuration/backend.html) configurations per directory, if you
aren't using the default `local` backend).
However, this isn't always the most _convenient_ way to handle separate states.
Terraform installs a separate cache of plugins and modules for each working
directory, so maintaining multiple directories can waste bandwidth and disk
space. You must also update your configuration code from version control
separately for each directory, reinitialize each directory separately when
changing the configuration, etc.
Workspaces allow you to use the same working copy of your configuration and the
same plugin and module caches, while still keeping separate states for each
collection of resources you manage.
## Interactions with Terraform Cloud Workspaces
Terraform Cloud organizes infrastructure using workspaces, but its workspaces
act more like completely separate working directories; each Terraform Cloud
workspace has its own Terraform configuration, set of variable values, state
data, run history, and settings.
These two kinds of workspaces are different, but related. When using Terraform
CLI as a frontend for Terraform Cloud, you associate the current working
directory with one or more remote workspaces by configuring
[the `remote` backend](/docs/backends/types/remote.html). If you associate the
directory with multiple workspaces (using a name prefix), you can use the
`terraform workspace` commands to select which remote workspace to use.
For more information about using Terraform CLI with Terraform Cloud, see
[CLI-driven Runs](/docs/cloud/run/cli.html) in the Terraform Cloud docs.

View File

@ -1,12 +1,12 @@
--- ---
layout: "docs" layout: "docs"
page_title: "Commands" page_title: "Basic CLI Features"
sidebar_current: "docs-commands" sidebar_current: "docs-commands"
description: |- description: |-
Main usage information for the Terraform CLI tool. Main usage information for the Terraform CLI tool.
--- ---
# Terraform Commands (CLI) # Basic CLI Features
> **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn. > **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.

View File

@ -0,0 +1,100 @@
---
layout: "language"
page_title: "Backend Overview - Configuration Language"
---
# Backends
Each Terraform configuration can specify a backend, which defines where
and how operations are performed, where [state](/docs/state/index.html)
snapshots are stored, etc.
The rest of this page introduces the concept of backends; the other pages in
this section document how to configure and use backends.
- [Backend Configuration](/docs/configuration/backend.html) documents the form
of a `backend` block, which selects and configures a backend for a
Terraform configuration.
- This section also includes a page for each of Terraform's built-in backends,
documenting its behavior and available settings. See the navigation sidebar
for a complete list.
## Recommended Backends
- If you are still learning how to use Terraform, we recommend using the default
`local` backend, which requires no configuration.
- If you and your team are using Terraform to manage meaningful infrastructure,
we recommend using the `remote` backend with [Terraform Cloud](/docs/cloud/index.html)
or [Terraform Enterprise](/docs/enterprise/index.html).
## Where Backends are Used
Backend configuration is only used by [Terraform CLI](/docs/cli-index.html).
Terraform Cloud and Terraform Enterprise always use their own state storage when
performing Terraform runs, so they ignore any backend block in the
configuration.
But since it's common to
[use Terraform CLI alongside Terraform Cloud](/docs/cloud/run/cli.html)
(and since certain state operations, like [tainting](/docs/commands/taint.html),
can only be performed on the CLI), we recommend that Terraform Cloud users
include a backend block in their configurations and configure the `remote`
backend to use the relevant Terraform Cloud workspace(s).
## Where Backends Come From
Terraform includes a built-in selection of backends; this selection has changed
over time, but does not change very often.
The built-in backends are the only backends. You cannot load additional backends
as plugins.
## What Backends Do
There are two areas of Terraform's behavior that are determined by the backend:
- Where state is stored.
- Where operations are performed.
### State
Terraform uses persistent [state](/docs/state/index.html) data to keep track of
the resources it manages. Since it needs the state in order to know which
real-world infrastructure objects correspond to the resources in a
configuration, everyone working with a given collection of infrastructure
resources must be able to access the same state data.
The `local` backend stores state as a local file on disk, but every other
backend stores state in a remote service of some kind, which allows multiple
people to access it. Accessing state in a remote service generally requires some
kind of access credentials, since state date contains extremely sensitive
information.
Some backends act like plain "remote disks" for state files; others support
_locking_ the state while operations are being performed, which helps prevent
conflicts and inconsistencies.
### Operations
"Operations" refers to performing API requests against infrastructure services
in order to create, read, update, or destroy resources. Not every `terraform`
subcommand performs API operations; many of them only operate on state data.
Only two backends actually perform operations: `local` and `remote`.
The `local` backend performs API operations directly from the machine where the
`terraform` command is run. Whenever you use a backend other than `local` or
`remote`, Terraform uses the `local` backend for operations; it only uses the
configured backend for state storage.
The `remote` backend can perform API operations remotely, using Terraform Cloud
or Terraform Enterprise. When running remote operations, the local `terraform`
command displays the output of the remote actions as though they were being
performed locally, but only the remote system requires cloud credentials or
network access to the resources being managed.
Remote operations are optional for the `remote` backend; the settings for the
target Terraform Cloud workspace determine whether operations run remotely or
locally. If local operations are configured, Terraform uses the `remote` backend
for state and the `local` backend for operations, like with the other state
backends.

View File

@ -0,0 +1,60 @@
---
layout: "language"
page_title: "Modules Overview - Configuration Language"
---
# Modules
> **Hands-on:** Try the [Reuse Configuration with Modules](https://learn.hashicorp.com/collections/terraform/modules?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
_Modules_ are containers for multiple resources that are used together. A module
consists of a collection of `.tf` and/or `.tf.json` files kept together in a
directory.
Modules are the main way to package and reuse resource configurations with
Terraform.
## The Root Module
Every Terraform configuration has at least one module, known as its
_root module_, which consists of the resources defined in the `.tf` files in
the main working directory.
## Child Modules
A Terraform module (usually the root module of a configuration) can _call_ other
modules to include their resources into the configuration. A module that has
been called by another module is often referred to as a _child module._
Child modules can be called multiple times within the same configuration, and
multiple configurations can use the same child module.
## Published Modules
In addition to modules from the local filesystem, Terraform can load modules
from a public or private registry. This makes it possible to publish modules for
others to use, and to use modules that others have published.
The [Terraform Registry](https://registry.terraform.io/browse/modules) hosts a
broad collection of publicly available Terraform modules for configuring many
kinds of common infrastructure. These modules are free to use, and Terraform can
download them automatically if you specify the appropriate source and version in
a module call block.
Also, members of your organization might produce modules specifically crafted
for your own infrastructure needs. [Terraform Cloud](/docs/cloud/index.html) and
[Terraform Enterprise](/docs/enterprise/index.html) both include a private
module registry for sharing modules internally within your organization.
## Using Modules
- [Module Blocks](/docs/configuration/modules.html) documents the syntax for
calling a child module from a parent module, including meta-arguments like
`for_each`.
- [Module Sources](/docs/modules/sources.html) documents what kinds of paths,
addresses, and URIs can be used in the `source` argument of a module block.
## Developing Modules
For information about developing reusable modules, see
[Module Development](/docs/modules/index.html).

View File

@ -0,0 +1,120 @@
---
layout: "language"
page_title: "Providers - Configuration Language"
---
# Providers
Terraform relies on plugins called "providers" to interact with remote systems.
Terraform configurations must declare which providers they require so that
Terraform can install and use them. Additionally, some providers require
configuration (like endpoint URLs or cloud regions) before they can be used.
## What Providers Do
Each provider adds a set of [resource types](/docs/configuration/resources.html)
and/or [data sources](/docs/configuration/data-sources.html) that Terraform can
manage.
Every resource type is implemented by a provider; without providers, Terraform
can't manage any kind of infrastructure.
Most providers configure a specific infrastructure platform (either cloud or
self-hosted). Providers can also offer local utilities for tasks like
generating random numbers for unique resource names.
## Where Providers Come From
Providers are distributed separately from Terraform itself, and each provider
has its own release cadence and version numbers.
The [Terraform Registry](https://registry.terraform.io/browse/providers)
is the main directory of publicly available Terraform providers, and hosts
providers for most major infrastructure platforms.
## How to Use Providers
To use resources from a given provider, you need to include some information
about it in your configuration. See the following pages for details:
- [Provider Requirements](/docs/configuration/provider-requirements.html)
documents how to declare providers so Terraform can install them.
- [Provider Configuration](/docs/configuration/providers.html)
documents how to configure settings for providers.
- [Dependency Lock File](/docs/configuration/dependency-lock.html)
documents an additional HCL file that can be included with a configuration,
which tells Terraform to always use a specific set of provider versions.
## Provider Installation
- Terraform Cloud and Terraform Enterprise install providers as part of every run.
- Terraform CLI finds and installs providers when
[initializing a working directory](/docs/cli/init/index.html). It can
automatically download providers from a Terraform registry, or load them from
a local mirror or cache. If you are using a persistent working directory, you
must reinitialize whenever you change a configuration's providers.
To save time and bandwidth, Terraform CLI supports an optional plugin
cache. You can enable the cache using the `plugin_cache_dir` setting in
[the CLI configuration file](/docs/commands/cli-config.html).
To ensure Terraform always installs the same provider versions for a given
configuration, you can use Terraform CLI to create a
[dependency lock file](/docs/configuration/dependency-lock.html)
and commit it to version control along with your configuration. If a lock file
is present, Terraform Cloud, CLI, and Enterprise will all obey it when
installing providers.
## How to Find Providers
To find providers for the infrastructure platforms you use, browse
[the providers section of the Terraform Registry](https://registry.terraform.io/browse/providers).
Some providers on the Registry are developed and published by HashiCorp, some
are published by platform maintainers, and some are published by users and
volunteers. The provider listings use the following badges to indicate who
develops and maintains a given provider.
<table border="0" style="border-collapse: collapse; width: 100%;">
<tbody>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><strong>Tier</strong></td>
<td style="width: 55.7271%; height: 21px;"><strong>Description</strong></td>
<td style="width: 31.7889%; height: 21px;"><strong>Namespace</strong></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/official-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;"><i><span style="font-weight: 400;">Official providers are owned and maintained by HashiCorp </span></i></td>
<td style="width: 31.7889%; height: 21px;"><code><span style="font-weight: 400;">hashicorp</span></code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/verified-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;"><i><span style="font-weight: 400;">Verified providers are owned and maintained by third-party technology partners. Providers in this tier indicate HashiCorp has verified the authenticity of the Provider&rsquo;s publisher, and that the partner is a member of the </span></i><a href="https://www.hashicorp.com/ecosystem/become-a-partner/"><i><span style="font-weight: 400;">HashiCorp Technology Partner Program</span></i></a><i><span style="font-weight: 400;">.</span></i></td>
<td style="width: 31.7889%; height: 21px;"><span style="font-weight: 400;">Third-party organization, e.g. </span><code><span style="font-weight: 400;">mongodb/mongodbatlas</span></code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/community-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;">Community providers are published to the Terraform Registry by individual maintainers, groups of maintainers, or other members of the Terraform community.</td>
<td style="width: 31.7889%; height: 21px;"><br />Maintainer&rsquo;s individual or organization account, e.g. <code>DeviaVir/gsuite</code></td>
</tr>
<tr style="height: 21px;">
<td style="width: 12.4839%; height: 21px;"><img src="/docs/registry/providers/images/archived-tier.png" alt="" /></td>
<td style="width: 55.7271%; height: 21px;">Archived Providers are Official or Verified Providers that are no longer maintained by HashiCorp or the community. This may occur if an API is deprecated or interest was low.</td>
<td style="width: 31.7889%; height: 21px;"><code>hashicorp</code> or third-party</td>
</tr>
</tbody>
</table>
## How to Develop Providers
Providers are written in Go, using the Terraform Plugin SDK. For more
information on developing providers, see:
- The [Extending Terraform](/docs/extend/index.html) documentation
- The [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
collection on HashiCorp Learn

View File

@ -0,0 +1,21 @@
---
layout: "language"
page_title: "Resources Overview - Configuration Language"
---
# Resources
> **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
_Resources_ are the most important element in the Terraform language.
Each resource block describes one or more infrastructure objects, such
as virtual networks, compute instances, or higher-level components such
as DNS records.
- [Resource Blocks](/docs/configuration/resources.html) documents how to declare
resources, including information about meta-arguments like `for_each`.
- [Provisioners](/docs/configuration/blocks/resources/provisioners/index.html)
documents configuring post-creation actions for a resource using the
`provisioner` and `connection` blocks. Since provisioners are non-declarative
and potentially unpredictable, we strongly recommend that you treat them as a
last resort.

View File

@ -0,0 +1,11 @@
---
layout: "language"
page_title: "Provisioners Overview - Configuration Language"
---
# Provisioners
Provisioners can be used to model specific actions on the local machine or on a
remote machine in order to prepare servers or other infrastructure objects for
service.

View File

@ -0,0 +1,18 @@
---
layout: "language"
page_title: "Variables and Outputs"
---
# Variables and Outputs
The Terraform language includes a few kinds of blocks for requesting or
publishing named values.
- [Input Variables](/docs/configuration/variables.html) serve as parameters for
a Terraform module, so users can customize behavior without editing the source.
- [Output Values](/docs/configuration/outputs.html) are like return values for a
Terraform module.
- [Local Values](/docs/configuration/locals.html) are a convenience feature for
assigning a short name to an expression.

View File

@ -0,0 +1,25 @@
---
layout: "language"
page_title: "Expressions - Configuration Language"
---
# Expressions
_Expressions_ are used to refer to or compute values within a configuration.
The simplest expressions are just literal values, like `"hello"` or `5`,
but the Terraform language also allows more complex expressions such as
references to data exported by resources, arithmetic, conditional evaluation,
and a number of built-in functions.
Expressions can be used in a number of places in the Terraform language,
but some contexts limit which expression constructs are allowed,
such as requiring a literal value of a particular type or forbidding
[references to resource attributes](/docs/configuration/expressions/references.html#references-to-resource-attributes).
Each language feature's documentation describes any restrictions it places on expressions.
You can experiment with the behavior of Terraform's expressions from
the Terraform expression console, by running
[the `terraform console` command](/docs/commands/console.html).
The other pages in this section describe the features of Terraform's
expression syntax.

View File

@ -0,0 +1,57 @@
---
layout: "language"
page_title: "Files and Directories - Configuration Language"
---
# Files and Directories
## File Extension
Code in the Terraform language is stored in plain text files with the `.tf` file
extension. There is also
[a JSON-based variant of the language](./syntax-json.html) that is named with
the `.tf.json` file extension.
Files containing Terraform code are often called _configuration files._
## Text Encoding
Configuration files must always use UTF-8 encoding, and by convention
usually use Unix-style line endings (LF) rather than Windows-style
line endings (CRLF), though both are accepted.
## Directories and Modules
A _module_ is a collection of `.tf` and/or `.tf.json` files kept together in a
directory.
A Terraform module only consists of the top-level configuration files in a
directory; nested directories are treated as completely separate modules, and
are not automatically included in the configuration.
Terraform evaluates all of the configuration files in a module, effectively
treating the entire module as a single document. Separating various blocks into
different files is purely for the convenience of readers and maintainers, and
has no effect on the module's behavior.
A Terraform module can use [module calls](/docs/configuration/modules.html) to
explicitly include other modules into the configuration. These child modules can
come from local directories (nested in the parent module's directory, or
anywhere else on disk), or from external sources like the
[Terraform Registry](https://registry.terraform.io).
## The Root Module
Terraform always runs in the context of a single _root module._ A complete
_Terraform configuration_ consists of a root module and the tree of child
modules (which includes the modules called by the root module, any modules
called by those modules, etc.).
- In Terraform CLI, the root module is the working directory where Terraform is
invoked. (You can use command line options to specify a root module outside
the working directory, but in practice this is rare. )
- In Terraform Cloud and Terraform Enterprise, the root module for a workspace
defaults to the top level of the configuration directory (supplied via version
control repository or direct upload), but the workspace settings can specify a
subdirectory to use instead.

View File

@ -1,41 +1,31 @@
--- ---
layout: "language" layout: "language"
page_title: "Configuration Language" page_title: "Overview - Configuration Language"
sidebar_current: "docs-config-index"
description: |-
Terraform uses text files to describe infrastructure and to set variables.
These text files are called Terraform _configurations_ and are
written in the Terraform language.
--- ---
# Configuration Language # Terraform Language Documentation
-> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and This is the documentation for Terraform's configuration language. It is relevant
earlier, see to users of [Terraform CLI](/docs/cli-index.html),
[0.11 Configuration Language](../configuration-0-11/index.html). [Terraform Cloud](/docs/cloud/index.html), and
[Terraform Enterprise](/docs/enterprise/index.html).
> **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn. > **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
Terraform uses its own configuration language, designed to allow concise _The Terraform language is Terraform's primary user interface._ In every edition
descriptions of infrastructure. The Terraform language is declarative, of Terraform, a configuration written in the Terraform language is always at the
describing an intended goal rather than the steps to reach that goal. heart of the workflow.
## Resources and Modules ## About the Terraform Language
The main purpose of the Terraform language is declaring [resources](./resources.html). The main purpose of the Terraform language is declaring
All other language features exist only to make the definition of resources [resources](./resources.html), which represent infrastructure objects. All other
more flexible and convenient. language features exist only to make the definition of resources more flexible
and convenient.
A group of resources can be gathered into a [module](./modules.html), A _Terraform configuration_ is a complete document in the Terraform language
which creates a larger unit of configuration. A resource describes a single that tells Terraform how to manage a given collection of infrastructure. A
infrastructure object, while a module might describe a set of objects and the configuration can consist of multiple files and directories.
necessary relationships between them in order to create a higher-level system.
A _Terraform configuration_ consists of a _root module_, where evaluation
begins, along with a tree of child modules created when one module calls
another.
## Arguments, Blocks, and Expressions
The syntax of the Terraform language consists of only a few basic elements: The syntax of the Terraform language consists of only a few basic elements:
@ -60,66 +50,15 @@ resource "aws_vpc" "main" {
combining other values. They appear as values for arguments, or within other combining other values. They appear as values for arguments, or within other
expressions. expressions.
For full details about Terraform's syntax, see: The Terraform language is declarative, describing an intended goal rather than
the steps to reach that goal. The ordering of blocks and the files they are
organized into are generally not significant; Terraform only considers implicit
and explicit relationships between resources when determining an order of
operations.
- [Configuration Syntax](./syntax.html) ### Example
- [Expressions](./expressions.html)
## Code Organization The following example describes a simple network topology for Amazon Web
The Terraform language uses configuration files that are named with the `.tf`
file extension. There is also [a JSON-based variant of the language](./syntax-json.html)
that is named with the `.tf.json` file extension.
Configuration files must always use UTF-8 encoding, and by convention are
usually maintained with Unix-style line endings (LF) rather than Windows-style
line endings (CRLF), though both are accepted.
A _module_ is a collection of `.tf` or `.tf.json` files kept together in a
directory. The root module is built from the configuration files in the
current working directory when Terraform is run, and this module may reference
child modules in other directories, which can in turn reference other modules,
etc.
The simplest Terraform configuration is a single root module containing only
a single `.tf` file. A configuration can grow gradually as more resources
are added, either by creating new configuration files within the root module
or by organizing sets of resources into child modules.
## Configuration Ordering
Because Terraform's configuration language is declarative, the ordering of
blocks is generally not significant. (The order of `provisioner` blocks within a
resource is the only major feature where block order matters.)
Terraform automatically processes resources in the correct order based on
relationships defined between them in configuration, and so you can organize
resources into source files in whatever way makes sense for your infrastructure.
## Terraform CLI vs. Providers
The Terraform command line interface (CLI) is a general engine for evaluating
and applying Terraform configurations. It defines the Terraform language syntax
and overall structure, and coordinates sequences of changes that must be made to
make remote infrastructure match the given configuration.
This general engine has no knowledge about specific types of infrastructure
objects. Instead, Terraform uses plugins called
[providers](./providers.html) that each define and manage a
set of resource types. Most providers are associated with a particular cloud or
on-premises infrastructure service, allowing Terraform to manage infrastructure
objects within that service.
Terraform doesn't have a concept of platform-independent resource types
 resources are always tied to a provider, since the features of similar
resources can vary greatly from provider to provider. But Terraform CLI's shared
configuration engine ensures that the same language constructs and syntax are
available across all services and allows resource types from different services
to be combined as needed.
## Example
The following simple example describes a simple network topology for Amazon Web
Services, just to give a sense of the overall structure and syntax of the Services, just to give a sense of the overall structure and syntax of the
Terraform language. Similar configurations can be created for other virtual Terraform language. Similar configurations can be created for other virtual
network services, using resource types defined by other providers, and a network services, using resource types defined by other providers, and a
@ -177,6 +116,3 @@ resource "aws_subnet" "az" {
} }
``` ```
For more information on the configuration elements shown here, use the
site navigation to explore the Terraform language documentation sub-sections.
To start, see [_Resource Configuration_](./resources.html).

View File

@ -21,53 +21,6 @@ configuration (like endpoint URLs or cloud regions) before they can be used.
- The [Provider Configuration](./providers.html) page documents how to configure - The [Provider Configuration](./providers.html) page documents how to configure
settings for providers. settings for providers.
## About Providers
Providers are plugins. They are released on a separate rhythm from Terraform
itself, and each provider has its own series of version numbers.
Each provider plugin offers a set of
[resource types](resources.html#resource-types-and-arguments), and defines for
each resource type which arguments it accepts, which attributes it exports, and
how changes to resources of that type are actually applied to remote APIs.
Most providers configure a specific infrastructure platform (either cloud or
self-hosted). Providers can also offer local utilities for tasks like
generating random numbers for unique resource names.
The [Terraform Registry](https://registry.terraform.io/browse/providers)
is the main directory of publicly available Terraform providers, and hosts
providers for most major infrastructure platforms. You can also write and
distribute your own Terraform providers, for public or private use.
> **Hands-on:** If you're interested in developing your own Terraform providers, try the [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
### Provider Installation
Terraform finds and installs providers when
[initializing a working directory](/docs/commands/init.html). It can
automatically download providers from a Terraform registry, or load them from a
local mirror or cache.
When you add a new provider to a configuration, Terraform must install the
provider in order to use it. If you are using a persistent working directory,
you can run `terraform init` again to install new providers.
Providers downloaded by `terraform init` are only installed for the current
working directory; other working directories can have their own installed
provider plugins. To help ensure that each working directory will use the same
selected versions, `terraform init` records its version selections in
your configuration's [dependency lock file](dependency-lock.html), named
`.terraform.lock.hcl` and will always make those same selections unless
you run `terraform init -upgrade` to update them.
To save time and bandwidth, Terraform supports an optional plugin cache. You can
enable the cache using the `plugin_cache_dir` setting in
[the CLI configuration file](/docs/commands/cli-config.html).
For more information about provider installation, see
[the `terraform init` command](/docs/commands/init.html).
## Requiring Providers ## Requiring Providers
Each Terraform module must declare which providers it requires, so that Each Terraform module must declare which providers it requires, so that

View File

@ -0,0 +1,21 @@
---
layout: "language"
page_title: "Syntax Overview - Configuration Language"
---
# Syntax
The majority of the Terraform language documentation focuses on the practical
uses of the language and the specific constructs it uses. The pages in this
section offer a more abstract view of the Terraform language.
- [Configuration Syntax](/docs/configuration/syntax.html) describes the native
grammar of the Terraform language.
- [JSON Configuration Syntax](/docs/configuration/syntax-json.html) documents
how to represent Terraform language constructs in the pure JSON variant of the
Terraform language. Terraform's JSON syntax is unfriendly to humans, but can
be very useful when generating infrastructure as code with other systems that
don't have a readily available HCL library.
- [Style Conventions](/docs/configuration/style.html) documents some commonly
accepted formatting guidelines for Terraform code. These conventions can be
enforced automatically with [`terraform fmt`](/docs/commands/fmt.html).