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
parent
b33a970b62
commit
e5e3452ffa
|
|
@ -1,13 +1,19 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Environment Variables"
|
||||
sidebar_current: "docs-config-environment-variables"
|
||||
sidebar_current: "docs-commands-environment-variables"
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
all of the Terraform workflow commands (starting with `terraform init`) or else
|
||||
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
|
||||
```
|
||||
|
|
@ -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.
|
||||
|
|
@ -8,53 +8,21 @@ description: |-
|
|||
|
||||
# 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.
|
||||
|
||||
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:
|
||||
These features relied on a special configuration block named `atlas`:
|
||||
|
||||
```hcl
|
||||
atlas {
|
||||
name = "mitchellh/production-example"
|
||||
name = "acme-corp/production"
|
||||
}
|
||||
```
|
||||
|
||||
~> **Why is this called "atlas"?** Atlas was previously a commercial offering
|
||||
from HashiCorp that included a full suite of enterprise products. The products
|
||||
have since been broken apart into their individual products, like **Terraform
|
||||
Enterprise**. While this transition is in progress, you may see references to
|
||||
"atlas" in the documentation. We apologize for the inconvenience.
|
||||
These features are no longer available on Terraform Enterprise and so the
|
||||
corresponding configuration elements and commands have been removed in
|
||||
Terraform v0.12.
|
||||
|
||||
## Description
|
||||
|
||||
The `atlas` block configures the settings when Terraform is
|
||||
[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
|
||||
}
|
||||
```
|
||||
To migrate to the current version of Terraform Enterprise, refer to
|
||||
[the upgrade guide](/docs/enterprise/upgrade/index.html). After upgrading,
|
||||
any `atlas` blocks in your configuration can be safely removed.
|
||||
|
|
|
|||
|
|
@ -4,40 +4,20 @@
|
|||
<li<%= sidebar_current("docs-config") %>>
|
||||
<a href="/docs/configuration/index.html">Configuration</a>
|
||||
<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") %>>
|
||||
<a href="/docs/configuration/resources.html">Resources</a>
|
||||
</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") %>>
|
||||
<a href="/docs/configuration/providers.html">Providers</a>
|
||||
</li>
|
||||
|
||||
<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<%= sidebar_current("docs-config-outputs") %>>
|
||||
<a href="/docs/configuration/outputs.html">Outputs</a>
|
||||
<a href="/docs/configuration/outputs.html">Output Values</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-config-locals") %>>
|
||||
|
|
@ -48,16 +28,28 @@
|
|||
<a href="/docs/configuration/modules.html">Modules</a>
|
||||
</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") %>>
|
||||
<a href="/docs/configuration/terraform.html">Terraform</a>
|
||||
<a href="/docs/configuration/terraform.html">Terraform Settings</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-config-push") %>>
|
||||
<a href="/docs/configuration/terraform-enterprise.html">Terraform Push (deprecated)</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-config-environment-variables") %>>
|
||||
<a href="/docs/configuration/environment-variables.html">Environment Variables</a>
|
||||
<li<%= sidebar_current("docs-config-override") %>>
|
||||
<a href="/docs/configuration/override.html">Override Files</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -152,6 +144,10 @@
|
|||
<li<%= sidebar_current("docs-commands-cli-config") %>>
|
||||
<a href="/docs/commands/cli-config.html">CLI Config File</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-environment-variables") %>>
|
||||
<a href="/docs/commands/environment-variables.html">Environment Variables</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue