From bcec7f5576d6f906e480368dd79d6a58380098c1 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Mon, 13 Jul 2020 10:31:22 -0700 Subject: [PATCH] website: v0.13 upgrade guide about "terraform apply" during upgrading Part of the upgrade process happens in the first "terraform apply" after adding explicit source addresses in the configuration. Previously we just left that implied under the assumption that everyone would run "terraform apply" shortly after anyway, but there is a specific tricky situation where the first change after upgrading is to remove a resource from the configuration, leaving Terraform unable to complete the upgrade. Because of that, we'll now explicitly direct users to run "terraform apply" after upgrading. Along with that, there's a reminder to make sure that "terraform plan" indicates no changes before upgrading, so that completing the upgrade doesn't involve also applying changes to remote objects. --- website/upgrade-guides/0-13.html.markdown | 55 +++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/website/upgrade-guides/0-13.html.markdown b/website/upgrade-guides/0-13.html.markdown index 683d63c91..b14887936 100644 --- a/website/upgrade-guides/0-13.html.markdown +++ b/website/upgrade-guides/0-13.html.markdown @@ -39,12 +39,25 @@ may be able to reproduce it and offer advice. Upgrade guide sections: +* [Before You Upgrade](#before-you-upgrade) * [Explicit Provider Source Locations](#explicit-provider-source-locations) * [New Filesystem Layout for Local Copies of Providers](#new-filesystem-layout-for-local-copies-of-providers) * [Special considerations for in-house providers](#in-house-providers) * [Destroy-time provisioners may not refer to other resources](#destroy-time-provisioners-may-not-refer-to-other-resources) * [Data resource reads can no longer be disabled by `-refresh=false`](#data-resource-reads-can-no-longer-be-disabled-by--refresh-false) +## Before You Upgrade + +When upgrading between major releases, we always recommend ensuring that you +can run `terraform plan` and see no proposed changes on the previous version +first, because otherwise pending changes can add additional unknowns into the +upgrade process. + +For this upgrade in particular, completing the upgrade will require running +`terraform apply` with Terraform 0.13 after upgrading in order to apply some +upgrades to the Terraform state, and we recommend doing that with no other +changes pending. + ## Explicit Provider Source Locations Prior versions of Terraform have supported automatic provider installation only @@ -137,6 +150,48 @@ run `terraform init` again to re-run the provider installer. -> **Action:** Either run [`terraform 0.13upgrade`](/docs/commands/0.13upgrade.html) for each of your modules, or manually update the provider declarations to use explicit source addresses. +The upgrade tool described above only updates references in your configuration. +The Terraform state also includes references to provider configurations which +need to be updated to refer to the correct providers. + +Terraform will automatically update provider configuration references in the +state the first time you run `terraform apply` after upgrading, but it relies +on information in the configuration to understand which provider any +existing resource belongs to, and so you must run `terraform apply` at least +once (and accept any changes it proposes) before removing any `resource` blocks +from your configuration after upgrading. + +If you are using Terraform Cloud or Terraform Enterprise with the VCS-driven +workflow (as oposed to CLI-driven runs), refer to +[The UI- and VCS-driven Run Workflow](/docs/cloud/run/ui.html) to learn how +to manually start a run after you select a Terraform v0.13 release for your +workspace. + +If you remove a `resource` block (or a `module` block for a module that +contains `resource` blocks) before the first `terraform apply`, you may see +a message like this reflecting that Terraform cannot determine which provider +configuration the existing object ought to be managed by: + +``` +Error: Provider configuration not present + +To work with null_resource.foo its original provider configuration at +provider["registry.terraform.io/-/aws"] is required, but it has been removed. +This occurs when a provider configuration is removed while objects created by +that provider still exist in the state. Re-add the provider configuration to +destroy aws_instance.example, after which you can remove the provider +configuration again. +``` + +In this specific upgrade situation the problem is actually the missing +`resource` block rather than the missing `provider` block: Terraform would +normally refer to the configuration to see if this resource has an explicit +`provider` argument that would override the default strategy for selecting +a provider. If you see the above after upgrading, re-add the resource mentioned +in the error message until you've completed the upgrade. + +-> **Action:** After updating all modules in your configuration to use the new provider requirements syntax, run `terraform apply` to create a new state snapshot containing the new-style provider source addresses that are now specified in your configuration. + ## New Filesystem Layout for Local Copies of Providers As part of introducing the hierarchical provider namespace discussed in the