github.com/Kevinklinger/open_terraform@v0.11.12-beta1/website/docs/backends/legacy-0-8.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Backends: Migrating From 0.8.x and Earlier"
     4  sidebar_current: "docs-backends-migrate"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Backend & Legacy Remote State
    10  
    11  Prior to Terraform 0.9.0 backends didn't exist and remote state management
    12  was done in a completely different way. This page documents how you can
    13  migrate to the new backend system and any considerations along the way.
    14  
    15  Migrating to the new backends system is extremely simple. The only complex
    16  case is if you had automation around configuring remote state. An existing
    17  environment can be configured to use the new backend system after just
    18  a few minutes of reading.
    19  
    20  For the remainder of this document, the remote state system prior to
    21  Terraform 0.9.0 will be called "legacy remote state."
    22  
    23  -> **Note:** This page is targeted at users who used remote state prior
    24  to version 0.9.0 and need to upgrade their environments. If you didn't
    25  use remote state, you can ignore this document.
    26  
    27  ## Backwards Compatibility
    28  
    29  In version 0.9.0, Terraform knows how to load and continue working with
    30  legacy remote state. A warning is shown guiding you to this page, but
    31  otherwise everything continues to work without changing any configuration.
    32  
    33  Backwards compatibility with legacy remote state environments will be
    34  removed in Terraform 0.11.0, or two major releases after 0.10.0. Starting
    35  in 0.10.0, detection will remain but users will be _required_ to update
    36  their configurations to use backends. In Terraform 0.11.0, detection and
    37  loading will be completely removed.
    38  
    39  For the short term, you may continue using Terraform with version 0.9.0
    40  as you have been. However, you should begin planning to update your configuration
    41  very soon. As you'll see, this process is very easy.
    42  
    43  ## Migrating to Backends
    44  
    45  You should begin by reading the [complete backend documentation](/docs/backends)
    46  section. This section covers in detail how you use and configure backends.
    47  
    48  Next, perform the following steps to migrate. These steps will also guide
    49  you through backing up your existing remote state just in case things don't
    50  go as planned.
    51  
    52  1. **With the older Terraform version (version 0.8.x),** run `terraform remote pull`. This
    53  will cache the latest legacy remote state data locally. We'll use this for
    54  a backup in case things go wrong.
    55  
    56  1. Backup your `.terraform/terraform.tfstate` file. This contains the
    57  cache we just pulled. Please copy this file to a location outside of your
    58  Terraform module.
    59  
    60  1. [Configure your backend](/docs/backends/config.html) in your Terraform
    61  configuration. The backend type is the same backend type as you used with
    62  your legacy remote state. The configuration should be setup to match the
    63  same configuration you used with remote state.
    64  
    65  1. [Run the init command](/docs/backends/init.html). This is an interactive
    66  process that will guide you through migrating your existing remote state
    67  to the new backend system. During this step, Terraform may ask if you want
    68  to copy your old remote state into the newly configured backend. If you
    69  configured the identical backend location, you may say no since it should
    70  already be there.
    71  
    72  1. Verify your state looks good by running `terraform plan` and seeing if
    73  it detects your infrastructure. Advanced users may run `terraform state pull`
    74  which will output the raw contents of your state file to your console. You
    75  can compare this with the file you saved. There may be slight differences in
    76  the serial number and version data, but the raw data should be almost identical.
    77  
    78  After the above steps, you're good to go! Everyone who uses the same
    79  Terraform state should copy the same steps above. The only difference is they
    80  may be able to skip the configuration step if you're sharing the configuration.
    81  
    82  At this point, **older Terraform versions will stop working.** Terraform
    83  will prevent itself from working with state written with a higher version
    84  of Terraform. This means that even other users using an older version of
    85  Terraform with the same configured remote state location will no longer
    86  be able to work with the environment. Everyone must upgrade.
    87  
    88  ## Rolling Back
    89  
    90  If the migration fails for any reason: your states look different, your
    91  plan isn't what you expect, you're getting errors, etc. then you may roll back.
    92  
    93  After rolling back, please [report an issue](https://github.com/hashicorp/terraform)
    94  so that we may resolve anything that may have gone wrong for you.
    95  
    96  To roll back, follow the steps below using Terraform 0.8.x or earlier:
    97  
    98  1. Remove the backend configuration from your Terraform configuration file.
    99  
   100  2. Remove any "terraform.tfstate" files (including backups). If you believe
   101  these may contain important data, you may back them up. Going with the assumption
   102  that you started this migration guide with working remote state, these files
   103  shouldn't contain anything of value.
   104  
   105  3. Copy the `.terraform/terraform.tfstate` file you backed up back into
   106  the same location.
   107  
   108  And you're rolled back. If your backend migration worked properly and was
   109  able to update your remote state, **then this will not work**. Terraform
   110  prevents writing state that was written with a higher Terraform version
   111  or a later serial number.
   112  
   113  **If you're absolutely certain you want to restore your state backup**,
   114  then you can use `terraform remote push -force`. This is extremely dangerous
   115  and you will lose any changes that were in the remote location.
   116  
   117  ## Configuration Automation
   118  
   119  The `terraform remote config` command has been replaced with
   120  `terraform init`. The new command is better in many ways by allowing file-based
   121  configuration, automatic state migration, and more.
   122  
   123  You should be able to very easily migrate `terraform remote config`
   124  scripting to the new `terraform init` command.
   125  
   126  The new `terraform init` command takes a `-backend-config` flag which is
   127  either an HCL file or a string in the format of `key=value`. This configuration
   128  is merged with the backend configuration in your Terraform files.
   129  This lets you keep secrets out of your actual configuration.
   130  We call this "partial configuration" and you can learn more in the
   131  docs on [configuring backends](/docs/backends/config.html).
   132  
   133  This does introduce an extra step: your automation must generate a
   134  JSON file (presumably JSON is easier to generate from a script than HCL
   135  and HCL is compatible) to pass into `-backend-config`.