From 8e44162fcb72eb390d6816cd4830d15c47c03a27 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 28 Feb 2017 19:19:57 -0800 Subject: [PATCH 1/3] website: backend upgrade guide --- .../source/docs/backends/legacy-0-8.html.md | 132 ++++++++++++++++++ .../source/upgrade-guides/0-9.html.markdown | 13 +- 2 files changed, 138 insertions(+), 7 deletions(-) create mode 100644 website/source/docs/backends/legacy-0-8.html.md diff --git a/website/source/docs/backends/legacy-0-8.html.md b/website/source/docs/backends/legacy-0-8.html.md new file mode 100644 index 000000000..596cda0e4 --- /dev/null +++ b/website/source/docs/backends/legacy-0-8.html.md @@ -0,0 +1,132 @@ +--- +layout: "docs" +page_title: "Backends: Migrating From 0.8.x and Earlier" +sidebar_current: "docs-backends-migrate" +description: |- + A "backend" in Terraform determines how state is loaded and how an operation such as `apply` is executed. This abstraction enables non-local file state storage, remote execution, etc. +--- + +# Backend & Legacy Remote State + +Prior to Terraform 0.9.0 backends didn't exist and remote state management +was done in a completely different way. This page documents how you can +migrate to the new backend system and any considerations along the way. + +Migrating to the new backends system is extremely simple. The only complex +case is if you had automation around configuring remote state. An existing +environment can be configured to use the new backend system after just +a few minutes of reading. + +For the remainder of this document, the remote state system prior to +Terraform 0.9.0 will be called "legacy remote state." + +-> **Note:** This page is targeted at users who used remote state prior +to version 0.9.0 and need to upgrade their environments. If you didn't +use remote state, you can ignore this document. + +## Backwards Compatibility + +In version 0.9.0, Terraform knows how to load and continue working with +legacy remote state. A warning is shown guiding you to this page, but +otherwise everything continues to work without changing any configuration. + +Backwards compatibility with legacy remote state environments will be +removed in Terraform 0.11.0, or two major releases after 0.10.0. Starting +in 0.10.0, detection will remain but users will be _required_ to update +their configurations to use backends. In Terraform 0.11.0, detection and +loading will be completely removed. + +For the short term, you may continue using Terraform with version 0.9.0 +as you have been. However, you should begin planning to update your configuration +very soon. As you'll see, this process is very easy. + +## Migrating to Backends + +You should begin by reading the [complete backend documentation](/docs/backends) +section. This section covers in detail how you use and configure backends. + +Next, perform the following steps to migrate. These steps will also guide +you through backing up your existing remote state just in case things don't +go as planned. + +1. **With the older Terraform version (version 0.8.x),** run `terraform remote pull`. This +will cache the latest legacy remote state data locally. We'll use this for +a backup in case things go wrong. + +1. Backup your `.terraform/terraform.tfstate` file. This contains the +cache we just pulled. Please copy this file to a location outside of your +Terraform module. + +1. [Configure your backend](/docs/backends/config.html) in your Terraform +configuration. The backend type is the same backend type as you used with +your legacy remote state. The configuration should be setup to match the +same configuration you used with remote state. + +1. [Run the init command](/docs/backends/init.html). This is an interactive +process that will guide you through migrating your existing remote state +to the new backend system. During this step, Terraform may ask if you want +to copy your old remote state into the newly configured backend. If you +configured the identical backend location, you may say no since it should +already be there. + +1. Verify your state looks good by running `terraform plan` and seeing if +it detects your infrastructure. Advanced users may run `terraform state pull` +which will output the raw contents of your state file to your console. You +can compare this with the file you saved. There may be slight differences in +the serial number and version data, but the raw data should be almost identical. + +After the above steps, you're good to go! Everyone who uses the same +Terraform state should copy the same steps above. The only difference is they +may be able to skip the configuration step if you're sharing the configuration. + +At this point, **older Terraform versions will stop working.** Terraform +will prevent itself from working with state written with a higher version +of Terraform. This means that even other users using an older version of +Terraform with the same configured remote state location will no longer +be able to work with the environment. Everyone must upgrade. + +## Rolling Back + +If the migration fails for any reason: your states look different, your +plan isn't what you expect, you're getting errors, etc. then you may roll back. + +After rolling back, please [report an issue](https://github.com/hashicorp/terraform) +so that we may resolve anything that may have gone wrong for you. + +To roll back, follow the steps below using Terraform 0.8.x or earlier: + +1. Remove the backend configuration from your Terraform configuration file. + +2. Remove any "terraform.tfstate" files (including backups). If you believe +these may contain important data, you may back them up. Going with the assumption +that you started this migration guide with working remote state, these files +shouldn't contain anything of value. + +3. Copy the `.terraform/terraform.tfstate` file you backed up back into +the same location. + +And you're rolled back. If your backend migration worked properly and was +able to update your remote state, **then this will not work**. Terraform +prevents writing state that was written with a higher Terraform version +or a later serial number. + +**If you're absolutely certain you want to restore your state backup**, +then you can use `terraform remote push -force`. This is extremely dangerous +and you will lose any changes that were in the remote location. + +## Configuration Automation + +The `terraform remote config` command has been replaced with +`terraform init`. The new command is better in many ways by allowing file-based +configuration, automatic state migration, and more. However, the new +command doesn't support configuration via command-line flags. + +The new `terraform init` command takes a `-backend-config` flag which is +an HCL file that is merged with the backend configuration in your Terraform +files. This lets you keep secrets out of your actual configuration. +We call this "partial configuration" and you can learn more in the +docs on [configuring backends](/docs/backends/config.html). + +This does introduce an extra step: your automation must generate a +JSON file (presumably JSON is easier to generate from a script than HCL +and HCL is compatible) to pass into `-backend-config`. diff --git a/website/source/upgrade-guides/0-9.html.markdown b/website/source/upgrade-guides/0-9.html.markdown index 8c5c53d4d..45f2979bd 100644 --- a/website/source/upgrade-guides/0-9.html.markdown +++ b/website/source/upgrade-guides/0-9.html.markdown @@ -25,10 +25,9 @@ Remote state has been overhauled to be easier and safer to configure and use. **The new changes are backwards compatible** with existing remote state and you'll be prompted to migrate to the new remote backend system. -For extra safety when upgrading, you may backup your existing remote state -by running `terraform remote pull` with 0.8.x and saving your -`.terraform/terraform.tfstate` file somewhere safe. You must do this prior -to upgrading to Terraform 0.9. +An in-depth guide for migrating to the new backend system +[is available here](/docs/backends/legacy-0-8.html). This includes +backing up your existing remote state and also rolling back if necessary. The only non-backwards compatible change is in the CLI: the existing `terraform remote config` command is now gone. Remote state is now configured @@ -46,9 +45,9 @@ terraform { } ``` -**Action:** Run `terraform init` to migrate your existing remote state. -Update any scripts or guides that may have used `terraform remote config` -to use the new file-based configuration. +**Action:** Nothing immediately, everything will continue working +except scripts using `terraform remote config`. +As soon as possible, [upgrade to backends](/docs/backends/legacy-0-8.html). ## State Locking From 6ea0dc0964160ef41ed40b0494d956d1ca42ac0c Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 28 Feb 2017 19:29:05 -0800 Subject: [PATCH 2/3] backend/consul: make address have a default to prevent input --- backend/remote-state/consul/backend.go | 1 + 1 file changed, 1 insertion(+) diff --git a/backend/remote-state/consul/backend.go b/backend/remote-state/consul/backend.go index a1f75eb85..1a5a93c64 100644 --- a/backend/remote-state/consul/backend.go +++ b/backend/remote-state/consul/backend.go @@ -36,6 +36,7 @@ func New() backend.Backend { Type: schema.TypeString, Optional: true, Description: "Address to the Consul Cluster", + Default: "", // To prevent input }, "scheme": &schema.Schema{ From 2c19aa69d9f4d4da43b1cedd17c5484c121fcc18 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 28 Feb 2017 19:29:19 -0800 Subject: [PATCH 3/3] command: legacy remote state should load from backendinit --- command/meta_backend.go | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/command/meta_backend.go b/command/meta_backend.go index 86d7aaf7b..55ceba2dc 100644 --- a/command/meta_backend.go +++ b/command/meta_backend.go @@ -737,8 +737,12 @@ func (m *Meta) backend_c_R_s( } config := terraform.NewResourceConfig(rawC) - // Initialize the legacy remote backend - b := &backendlegacy.Backend{Type: s.Remote.Type} + // Get the backend + f := backendinit.Backend(s.Remote.Type) + if f == nil { + return nil, fmt.Errorf(strings.TrimSpace(errBackendLegacyUnknown), s.Remote.Type) + } + b := f() // Configure if err := b.Configure(config); err != nil { @@ -1432,6 +1436,17 @@ The error(s) configuring the legacy remote state: %s ` +const errBackendLegacyUnknown = ` +The legacy remote state type %q could not be found. + +Terraform 0.9.0 shipped with backwards compatible for all built-in +legacy remote state types. This error may mean that you were using a +custom Terraform build that perhaps supported a different type of +remote state. + +Please check with the creator of the remote state above and try again. +` + const errBackendLocalRead = ` Error reading local state: %s @@ -1711,4 +1726,8 @@ Remote state changed significantly in Terraform 0.9. Please update your remote state configuration to use the new 'backend' settings. For now, Terraform will continue to use your existing settings. Legacy remote state support will be removed in Terraform 0.11. + +You can find a guide for upgrading here: + +https://www.terraform.io/docs/backends/legacy-0-8.html `