website: backend upgrade guide
This commit is contained in:
Mitchell Hashimoto
parent
cf3d234f5c
commit
8e44162fcb
|
|
@ -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`.
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue