From 8e44162fcb72eb390d6816cd4830d15c47c03a27 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Tue, 28 Feb 2017 19:19:57 -0800 Subject: [PATCH] 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