website: Reorganize the "Configuration" docs section

With the additional configuration language features coming in Terraform
v0.12, our existing documentation structure is beginning to strain.

Here we reorganize the navigation slightly in order to introduce the
concepts in a more appropriate order so that we can reveal complexity
more gradually. Subsequent commits will revise the content of these
pages to better reflect the new sequencing.

The "Environment Variables" page is moved from the Configuration section
into the "Commands" section, since it is not considered a part of the
configuration language and thus more appropriate in the CLI documentation.
The old placement is reflective of the broader purpose that the
"Configuration" section had originally, but its new focus will be on
the Terraform language (.tf files) in particular, with other aspects of
customizing Terraforms behavior covered in other sections.
This commit is contained in:
Martin Atkins 2018-05-05 13:45:49 -07:00
parent b33a970b62
commit e5e3452ffa
4 changed files with 43 additions and 121 deletions

View File

@ -1,13 +1,19 @@
--- ---
layout: "docs" layout: "docs"
page_title: "Environment Variables" page_title: "Environment Variables"
sidebar_current: "docs-config-environment-variables" sidebar_current: "docs-commands-environment-variables"
description: |- description: |-
Terraform uses different environment variables that can be used to configure various aspects of how Terraform behaves. this section documents those variables, their potential values, and how to use them. Terraform uses environment variables to configure various aspects of its behavior.
--- ---
# Environment Variables # Environment Variables
Terraform refers to a number of environment variables to customize various
aspects of its behavior. None of these environment variables are required
when using Terraform, but they can be used to change some of Terraform's
default behaviors in unusual situations, or to increase output verbosity
for debugging.
## TF_LOG ## TF_LOG
If set to any value, enables detailed logs to appear on stderr which is useful for debugging. For example: If set to any value, enables detailed logs to appear on stderr which is useful for debugging. For example:
@ -104,15 +110,3 @@ The data directory is used to retain data that must persist from one command
to the next, so it's important to have this variable set consistently throughout to the next, so it's important to have this variable set consistently throughout
all of the Terraform workflow commands (starting with `terraform init`) or else all of the Terraform workflow commands (starting with `terraform init`) or else
Terraform may be unable to find providers, modules, and other artifacts. Terraform may be unable to find providers, modules, and other artifacts.
## TF_SKIP_REMOTE_TESTS
This can be set prior to running the unit tests to opt-out of any tests
requiring remote network connectivity. The unit tests make an attempt to
automatically detect when connectivity is unavailable and skip the relevant
tests, but by setting this variable you can force these tests to be skipped.
```shell
export TF_SKIP_REMOTE_TESTS=1
make test
```

View File

@ -1,36 +0,0 @@
---
layout: "docs"
page_title: "Load Order and Semantics"
sidebar_current: "docs-config-load"
description: |-
When invoking any command that loads the Terraform configuration, Terraform loads all configuration files within the directory specified in alphabetical order.
---
# Load Order and Semantics
When invoking any command that loads the Terraform configuration,
Terraform loads all configuration files within the directory
specified in alphabetical order.
The files loaded must end in
either `.tf` or `.tf.json` to specify the format that is in use.
Otherwise, the files are ignored. Multiple file formats can
be present in the same directory; it is okay to have one Terraform
configuration file be Terraform syntax and another be JSON.
[Override](/docs/configuration/override.html)
files are the exception, as they're loaded after all non-override
files, in alphabetical order.
The configuration within the loaded files are appended to each
other. This is in contrast to being merged. This means that two
resources with the same name are not merged, and will instead
cause a validation error. This is in contrast to
[overrides](/docs/configuration/override.html),
which do merge.
The order of variables, resources, etc. defined within the
configuration doesn't matter. Terraform configurations are
[declarative](https://en.wikipedia.org/wiki/Declarative_programming),
so references to other resources and variables do not depend
on the order they're defined.

View File

@ -8,53 +8,21 @@ description: |-
# Terraform Push Configuration # Terraform Push Configuration
~> **Important:** The `terraform push` command is deprecated, and only works with [the legacy version of Terraform Enterprise](/docs/enterprise-legacy/index.html). In the current version of Terraform Enterprise, you can upload configurations using the API. See [the docs about API-driven runs](/docs/enterprise/run/api.html) for more details. Prior to v0.12, Terraform included mechanisms to interact with a legacy version
of Terraform Enterprise, formerly known as "Atlas".
The [`terraform push` command](/docs/commands/push.html) uploads a configuration to a Terraform Enterprise (legacy) environment. The name of the environment (and the organization it's in) can be specified on the command line, or as part of the Terraform configuration in an `atlas` block. These features relied on a special configuration block named `atlas`:
The `atlas` block does not configure remote state; it only configures the push command. For remote state, [use a `terraform { backend "<NAME>" {...} }` block](/docs/backends/config.html).
This page assumes you're familiar with the
[configuration syntax](/docs/configuration/syntax.html)
already.
## Example
Terraform push configuration looks like the following:
```hcl ```hcl
atlas { atlas {
name = "mitchellh/production-example" name = "acme-corp/production"
} }
``` ```
~> **Why is this called "atlas"?** Atlas was previously a commercial offering These features are no longer available on Terraform Enterprise and so the
from HashiCorp that included a full suite of enterprise products. The products corresponding configuration elements and commands have been removed in
have since been broken apart into their individual products, like **Terraform Terraform v0.12.
Enterprise**. While this transition is in progress, you may see references to
"atlas" in the documentation. We apologize for the inconvenience.
## Description To migrate to the current version of Terraform Enterprise, refer to
[the upgrade guide](/docs/enterprise/upgrade/index.html). After upgrading,
The `atlas` block configures the settings when Terraform is any `atlas` blocks in your configuration can be safely removed.
[pushed](/docs/commands/push.html) to Terraform Enterprise. Only one `atlas` block
is allowed.
Within the block (the `{ }`) is configuration for Atlas uploading.
No keys are required, but the key typically set is `name`.
**No value within the `atlas` block can use interpolations.** Due
to the nature of this configuration, interpolations are not possible.
If you want to parameterize these settings, use the Atlas block to
set defaults, then use the command-line flags of the
[push command](/docs/commands/push.html) to override.
## Syntax
The full syntax is:
```text
atlas {
name = VALUE
}
```

View File

@ -4,40 +4,20 @@
<li<%= sidebar_current("docs-config") %>> <li<%= sidebar_current("docs-config") %>>
<a href="/docs/configuration/index.html">Configuration</a> <a href="/docs/configuration/index.html">Configuration</a>
<ul class="nav"> <ul class="nav">
<li<%= sidebar_current("docs-config-load") %>>
<a href="/docs/configuration/load.html">Load Order and Semantics</a>
</li>
<li<%= sidebar_current("docs-config-syntax") %>>
<a href="/docs/configuration/syntax.html">Configuration Syntax</a>
</li>
<li<%= sidebar_current("docs-config-interpolation") %>>
<a href="/docs/configuration/interpolation.html">Interpolation Syntax</a>
</li>
<li<%= sidebar_current("docs-config-override") %>>
<a href="/docs/configuration/override.html">Overrides</a>
</li>
<li<%= sidebar_current("docs-config-resources") %>> <li<%= sidebar_current("docs-config-resources") %>>
<a href="/docs/configuration/resources.html">Resources</a> <a href="/docs/configuration/resources.html">Resources</a>
</li> </li>
<li<%= sidebar_current("docs-config-data-sources") %>>
<a href="/docs/configuration/data-sources.html">Data Sources</a>
</li>
<li<%= sidebar_current("docs-config-providers") %>> <li<%= sidebar_current("docs-config-providers") %>>
<a href="/docs/configuration/providers.html">Providers</a> <a href="/docs/configuration/providers.html">Providers</a>
</li> </li>
<li<%= sidebar_current("docs-config-variables") %>> <li<%= sidebar_current("docs-config-variables") %>>
<a href="/docs/configuration/variables.html">Variables</a> <a href="/docs/configuration/variables.html">Input Variables</a>
</li> </li>
<li<%= sidebar_current("docs-config-outputs") %>> <li<%= sidebar_current("docs-config-outputs") %>>
<a href="/docs/configuration/outputs.html">Outputs</a> <a href="/docs/configuration/outputs.html">Output Values</a>
</li> </li>
<li<%= sidebar_current("docs-config-locals") %>> <li<%= sidebar_current("docs-config-locals") %>>
@ -48,16 +28,28 @@
<a href="/docs/configuration/modules.html">Modules</a> <a href="/docs/configuration/modules.html">Modules</a>
</li> </li>
<li<%= sidebar_current("docs-config-data-sources") %>>
<a href="/docs/configuration/data-sources.html">Data Sources</a>
</li>
<li<%= sidebar_current("docs-config-syntax") %>>
<a href="/docs/configuration/syntax.html">Configuration Syntax</a>
</li>
<li<%= sidebar_current("docs-config-expressions") %>>
<a href="/docs/configuration/expressions.html">Expressions</a>
</li>
<li<%= sidebar_current("docs-config-functions") %>>
<a href="/docs/configuration/functions.html">Functions</a>
</li>
<li<%= sidebar_current("docs-config-terraform") %>> <li<%= sidebar_current("docs-config-terraform") %>>
<a href="/docs/configuration/terraform.html">Terraform</a> <a href="/docs/configuration/terraform.html">Terraform Settings</a>
</li> </li>
<li<%= sidebar_current("docs-config-push") %>> <li<%= sidebar_current("docs-config-override") %>>
<a href="/docs/configuration/terraform-enterprise.html">Terraform Push (deprecated)</a> <a href="/docs/configuration/override.html">Override Files</a>
</li>
<li<%= sidebar_current("docs-config-environment-variables") %>>
<a href="/docs/configuration/environment-variables.html">Environment Variables</a>
</li> </li>
</ul> </ul>
</li> </li>
@ -152,6 +144,10 @@
<li<%= sidebar_current("docs-commands-cli-config") %>> <li<%= sidebar_current("docs-commands-cli-config") %>>
<a href="/docs/commands/cli-config.html">CLI Config File</a> <a href="/docs/commands/cli-config.html">CLI Config File</a>
</li> </li>
<li<%= sidebar_current("docs-commands-environment-variables") %>>
<a href="/docs/commands/environment-variables.html">Environment Variables</a>
</li>
</ul> </ul>
</li> </li>