website: Deprecation notes about "terraform push"

Also:

- In the getting started guide, the TFE content was all tailored to the older
  run-locally workflow. I've replaced it with some brief explanation and a link
  to the dedicated TFE getting started guide.
- Fixed a sidebar link glitch in the configuration section. (Both "Terraform"
  and "Terraform Enterprise" were marked as active if you were on the TFE page.)
- Renamed the "Terraform Enterprise" page "Terraform Push." (Some people have
  gotten confused and landed on this page when trying to set up the `atlas`
  remote backend.)
This commit is contained in:
Nick Fagerlund 2018-02-27 14:48:04 -08:00 committed by Martin Atkins
parent 9a3e86104e
commit 46754c9917
4 changed files with 37 additions and 95 deletions

View File

@ -8,11 +8,13 @@ description: |-
# Command: push # Command: push
~> **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/workspaces/run-api.html) for more details.
The `terraform push` command uploads your Terraform configuration to The `terraform push` command uploads your Terraform configuration to
be managed by HashiCorp's [Terraform Enterprise](https://www.hashicorp.com/products/terraform/). be managed by HashiCorp's [Terraform Enterprise](https://www.hashicorp.com/products/terraform/).
By uploading your configuration to Terraform Enterprise, you can automatically run Terraform Enterprise can automatically run
Terraform for you, will save all state transitions, will save plans, Terraform for you, save all state transitions, save plans,
and will keep a history of all Terraform runs. and keep a history of all Terraform runs.
This makes it significantly easier to use Terraform as a team: team This makes it significantly easier to use Terraform as a team: team
members modify the Terraform configurations locally and continue to members modify the Terraform configurations locally and continue to
@ -127,6 +129,8 @@ or plan), and the `-overwrite` flag tells the push command to update Terraform E
## Remote State Requirement ## Remote State Requirement
~> **Important:** This section only refers to the legacy version of Terraform Enterprise. The current version of Terraform Enterprise always manages its own state, and does not support arbitrary remote state backends.
`terraform push` requires that `terraform push` requires that
[remote state](/docs/state/remote.html) [remote state](/docs/state/remote.html)
is enabled. The reasoning for this is simple: `terraform push` sends your is enabled. The reasoning for this is simple: `terraform push` sends your

View File

@ -1,36 +1,26 @@
--- ---
layout: "docs" layout: "docs"
page_title: "Configuring Terraform Enterprise" page_title: "Configuring Terraform Push"
sidebar_current: "docs-config-terraform-enterprise" sidebar_current: "docs-config-push"
description: |- description: |-
Terraform Enterprise is the ideal way to use Terraform in a team environment. Terraform Enterprise will run Terraform for you, safely handle parallelization across different team members, save run history along with plans, and more. Terraform's push command was a way to interact with the legacy version of Terraform Enterprise. It is not supported in the current version of Terraform Enterprise.
--- ---
# Terraform Enterprise Configuration # Terraform Push Configuration
Terraform can be configured to be able to upload to HashiCorp's ~> **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/workspaces/run-api.html) for more details.
[Terraform Enterprise](https://www.hashicorp.com/products/terraform/). This configuration doesn't change
the behavior of Terraform itself, it only configures your Terraform
configuration to support being uploaded to Terraform Enterprise via the
[push command](/docs/commands/push.html).
For more information on the benefits of uploading your Terraform 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.
configuration to Terraform Enterprise, please see the
[push command documentation](/docs/commands/push.html). 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 This page assumes you're familiar with the
[configuration syntax](/docs/configuration/syntax.html) [configuration syntax](/docs/configuration/syntax.html)
already. already.
~> **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.
## Example ## Example
Terraform Enterprise configuration looks like the following: Terraform push configuration looks like the following:
```hcl ```hcl
atlas { atlas {
@ -38,6 +28,12 @@ atlas {
} }
``` ```
~> **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.
## Description ## Description
The `atlas` block configures the settings when Terraform is The `atlas` block configures the settings when Terraform is

View File

@ -10,12 +10,14 @@ description: |-
We've now seen how to build, change, and destroy infrastructure We've now seen how to build, change, and destroy infrastructure
from a local machine. This is great for testing and development, from a local machine. This is great for testing and development,
however in production environments it is more responsible to run but in production environments it is more responsible to share responsibility
Terraform remotely and store a master Terraform state remotely. for infrastructure. The best way to do this is by running Terraform in a remote
environment with shared access to state.
Terraform supports a feature known as [remote backends](/docs/backends) Terraform supports team-based workflows with a feature known as [remote
to support this. Backends are the recommended way to use Terraform in backends](/docs/backends). Remote backends allow Terraform to use a shared
a team environment. storage space for state data, so any member of your team can use Terraform to
manage the same infrastructure.
Depending on the features you wish to use, Terraform has multiple remote Depending on the features you wish to use, Terraform has multiple remote
backend options. You could use Consul for state storage, locking, and backend options. You could use Consul for state storage, locking, and
@ -31,7 +33,7 @@ When a proposed change is accepted, the Terraform logs are stored,
resulting in a linear history of infrastructure states to resulting in a linear history of infrastructure states to
help with auditing and policy enforcement. Additional benefits to help with auditing and policy enforcement. Additional benefits to
running Terraform remotely include moving access running Terraform remotely include moving access
credentials off of developer machines and releasing local machines credentials off of developer machines and freeing local machines
from long-running Terraform processes. from long-running Terraform processes.
## How to Store State Remotely ## How to Store State Remotely
@ -90,75 +92,15 @@ once again ask if you want to migrate your state back to local.
## Terraform Enterprise ## Terraform Enterprise
HashiCorp (the makers of Terraform) also provide a commercial solution which [Terraform Enterprise](https://www.hashicorp.com/products/terraform/?utm_source=oss&utm_medium=getting-started&utm_campaign=terraform) is a commercial solution which combines a predictable and reliable shared run environment with tools to help you work together on Terraform configurations and modules.
functions as a Terraform backend as well as enabling many other features such
as remote apply, run history, state history, state diffing, and more.
This section will guide you through a demo of Terraform Enterprise. Note that Although Terraform Enterprise can act as a standard remote backend to support Terraform runs on local machines, it works even better as a remote run environment. It supports two main workflows for performing Terraform runs:
this is commercial software. If you are not interested at this time, you may
skip this section.
First, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=getting-started&utm_campaign=terraform) unless you already have one. - A VCS-driven workflow, in which it automatically queues plans whenever changes are committed to your configuration's VCS repo.
- An API-driven workflow, in which a CI pipeline or other automated tool can upload configurations directly.
Terraform uses your access token to securely communicate with Terraform For a hands-on introduction to Terraform Enterprise, [follow the Terraform Enterprise getting started guide](/docs/enterprise/getting-started/index.html).
Enterprise. To generate a token: select your username in the left side
navigation menu, click "Accounts Settings", "click "Tokens", then click
"Generate".
For the purposes of this tutorial you can use this token by exporting it to
your local shell session:
```
$ export ATLAS_TOKEN=ATLAS_ACCESS_TOKEN
```
Replace `ATLAS_ACCESS_TOKEN` with the token generated earlier. Next,
configure the Terraform Enterprise backend:
```hcl
terraform {
backend "atlas" {
name = "USERNAME/getting-started"
}
}
```
Replace `USERNAME` with your Terraform Enterprise username. Note that the
backend name is "atlas" for legacy reasons and will be renamed soon.
Remember to run `terraform init`. At this point, Terraform is using Terraform
Enterprise for everything shown before with Consul. Next, we'll show you some
additional functionality Terraform Enterprise enables.
Before you [push](/docs/commands/push.html) your Terraform configuration to
Terraform Enterprise you'll need to start a local version control system with
at least one commit. Here is an example using `git`.
```
$ git init
$ git add example.tf
$ git commit -m "init commit"
```
Next, [push](/docs/commands/push.html) your Terraform configuration:
```
$ terraform push
```
This will automatically trigger a `terraform plan`, which you can
review in the [Terraform page](https://atlas.hashicorp.com/terraform).
If the plan looks correct, hit "Confirm & Apply" to execute the
infrastructure changes.
Running Terraform in Terraform Enterprise creates a complete history of
infrastructure changes, a sort of version control
for infrastructure. Similar to application version control
systems such as Git or Subversion, this makes changes to
infrastructure an auditable, repeatable,
and collaborative process. With so much relying on the
stability of your infrastructure, version control is a
responsible choice for minimizing downtime.
## Next ## Next
You now know how to create, modify, destroy, version, and You now know how to create, modify, destroy, version, and

View File

@ -52,8 +52,8 @@
<a href="/docs/configuration/terraform.html">Terraform</a> <a href="/docs/configuration/terraform.html">Terraform</a>
</li> </li>
<li<%= sidebar_current("docs-config-terraform-enterprise") %>> <li<%= sidebar_current("docs-config-push") %>>
<a href="/docs/configuration/terraform-enterprise.html">Terraform Enterprise</a> <a href="/docs/configuration/terraform-enterprise.html">Terraform Push (deprecated)</a>
</li> </li>
<li<%= sidebar_current("docs-config-environment-variables") %>> <li<%= sidebar_current("docs-config-environment-variables") %>>