From 66ff8f8bed40293bd8a3ba827ca0b0838666c821 Mon Sep 17 00:00:00 2001 From: Nick Fagerlund Date: Tue, 27 Feb 2018 14:48:04 -0800 Subject: [PATCH] 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.) --- website/docs/commands/push.html.markdown | 10 ++- .../terraform-enterprise.html.md | 34 ++++---- .../getting-started/remote.html.markdown | 84 +++---------------- website/layouts/docs.erb | 4 +- 4 files changed, 37 insertions(+), 95 deletions(-) diff --git a/website/docs/commands/push.html.markdown b/website/docs/commands/push.html.markdown index ee667bce5..0fa68ae2e 100644 --- a/website/docs/commands/push.html.markdown +++ b/website/docs/commands/push.html.markdown @@ -8,11 +8,13 @@ description: |- # 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 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 for you, will save all state transitions, will save plans, -and will keep a history of all Terraform runs. +Terraform Enterprise can automatically run +Terraform for you, save all state transitions, save plans, +and keep a history of all Terraform runs. This makes it significantly easier to use Terraform as a team: team 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 +~> **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 [remote state](/docs/state/remote.html) is enabled. The reasoning for this is simple: `terraform push` sends your diff --git a/website/docs/configuration/terraform-enterprise.html.md b/website/docs/configuration/terraform-enterprise.html.md index e59511f75..603ec467f 100644 --- a/website/docs/configuration/terraform-enterprise.html.md +++ b/website/docs/configuration/terraform-enterprise.html.md @@ -1,36 +1,26 @@ --- layout: "docs" -page_title: "Configuring Terraform Enterprise" -sidebar_current: "docs-config-terraform-enterprise" +page_title: "Configuring Terraform Push" +sidebar_current: "docs-config-push" 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 -[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). +~> **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. -For more information on the benefits of uploading your Terraform -configuration to Terraform Enterprise, please see the -[push command documentation](/docs/commands/push.html). +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 "" {...} }` block](/docs/backends/config.html). This page assumes you're familiar with the [configuration syntax](/docs/configuration/syntax.html) 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 -Terraform Enterprise configuration looks like the following: +Terraform push configuration looks like the following: ```hcl 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 The `atlas` block configures the settings when Terraform is diff --git a/website/intro/getting-started/remote.html.markdown b/website/intro/getting-started/remote.html.markdown index b24a04100..ea3cfe0c0 100644 --- a/website/intro/getting-started/remote.html.markdown +++ b/website/intro/getting-started/remote.html.markdown @@ -10,12 +10,14 @@ description: |- We've now seen how to build, change, and destroy infrastructure from a local machine. This is great for testing and development, -however in production environments it is more responsible to run -Terraform remotely and store a master Terraform state remotely. +but in production environments it is more responsible to share responsibility +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) -to support this. Backends are the recommended way to use Terraform in -a team environment. +Terraform supports team-based workflows with a feature known as [remote +backends](/docs/backends). Remote backends allow Terraform to use a shared +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 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 help with auditing and policy enforcement. Additional benefits to 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. ## How to Store State Remotely @@ -90,75 +92,15 @@ once again ask if you want to migrate your state back to local. ## Terraform Enterprise -HashiCorp (the makers of Terraform) also provide a commercial solution which -functions as a Terraform backend as well as enabling many other features such -as remote apply, run history, state history, state diffing, and more. +[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. -This section will guide you through a demo of Terraform Enterprise. Note that -this is commercial software. If you are not interested at this time, you may -skip this section. +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: -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 -Enterprise. To generate a token: select your username in the left side -navigation menu, click "Accounts Settings", "click "Tokens", then click -"Generate". +For a hands-on introduction to Terraform Enterprise, [follow the Terraform Enterprise getting started guide](/docs/enterprise/getting-started/index.html). -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 You now know how to create, modify, destroy, version, and diff --git a/website/layouts/docs.erb b/website/layouts/docs.erb index e68f37fd0..c8535b44d 100644 --- a/website/layouts/docs.erb +++ b/website/layouts/docs.erb @@ -52,8 +52,8 @@ Terraform - > - Terraform Enterprise + > + Terraform Push (deprecated) >