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