From 4569a37de414d56a2cd2a76ceaffa080068c2103 Mon Sep 17 00:00:00 2001 From: Kristin Laemmert Date: Wed, 26 Aug 2020 13:50:07 -0400 Subject: [PATCH] website/docs: provider source related clarifications --- .../provider-requirements.html.md | 10 +++- website/upgrade-guides/0-13.html.markdown | 46 ++++++++++++++++++- 2 files changed, 54 insertions(+), 2 deletions(-) diff --git a/website/docs/configuration/provider-requirements.html.md b/website/docs/configuration/provider-requirements.html.md index 0aa4aa501..cc1b5d16f 100644 --- a/website/docs/configuration/provider-requirements.html.md +++ b/website/docs/configuration/provider-requirements.html.md @@ -183,7 +183,15 @@ For example, [the official HTTP provider](https://registry.terraform.io/providers/hashicorp/http) belongs to the `hashicorp` namespace on `registry.terraform.io`, so its source address is `registry.terraform.io/hashicorp/http` or, more commonly, just -`hashicorp/http`. +`hashicorp/http`. + +The source address with all three components given explicitly is called the +provider's _fully-qualified address_. You will see fully-qualified address in +various outputs, like error messages, but in most cases a simplified display +version is used. This display version omits the source host when it is the +public registry, so you may see the shortened version `"hashicorp/random"` instead +of `"registry.terraform.io/hashicorp/random"`. + -> **Note:** If you omit the `source` argument when requiring a provider, Terraform uses an implied source address of diff --git a/website/upgrade-guides/0-13.html.markdown b/website/upgrade-guides/0-13.html.markdown index b14887936..2e306d6c1 100644 --- a/website/upgrade-guides/0-13.html.markdown +++ b/website/upgrade-guides/0-13.html.markdown @@ -45,6 +45,7 @@ Upgrade guide sections: * [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) +* [Frequently Asked Questions](#frequently-asked-questions) ## Before You Upgrade @@ -162,7 +163,7 @@ 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 +workflow (as opposed 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. @@ -436,3 +437,46 @@ disable the reading of data resources (declared with `data` blocks). ~> Updating the data associated with data resources is crucial to producing an accurate plan, and so there is no replacement mechanism in Terraform v0.13 to restore the previous behavior. + +## Frequently Asked Questions +### Why do I see `-/provider` during init? + +Provider source addresses starting with `registry.terraform.io/-/` are a special +way Terraform marks legacy addresses where the true namespace is unknown. For +providers that were automatically-installable in Terraform 0.12, Terraform 0.13 +can automatically determine the new addresses for these using a lookup table in +the public Terraform Registry. That lookup table is accessed by using the +special namespace `-`. + +When you run `init`, terraform generates a list of required providers based on +both the configuration and state. Legacy-style providers - such as providers in +a statefile written with Terraform v0.12 - don't have a namespace, so terraform +uses the placeholder namespace `-` to query the registry. That is why you may +see output like this during your first `init`: + +``` +- Finding latest version of -/null... +- Finding latest version of -/random... +- Finding latest version of hashicorp/null... +- Finding latest version of hashicorp/random... +``` + +Terraform found providers `null` and `random` in the statefile without a +namespace. Terraform *also* found `hashicorp/null` and `hashicorp/random` in the +configuration files. Providers in configuration are automatically assumed to be +default (HashiCorp) providers, while providers found in state are first looked +up in the registry. + +While this does not cause any problems for Terraform, it has been confusing. You +may circumvent this by using the `terraform state replace-provider` subcommand +to tell Terraform exactly what provider addresses are required in state. +Continuing from the example above, the following commands tell Terraform the +source address for the `null` and `random` providers: + +``` +terraform state replace-provider -- -/random registry.terraform.io/hashicorp/random +terraform state replace-provider -- -/null registry.terraform.io/hashicorp/null +``` + +If you are seeing these messages with errors, and are using in-house or +locally-installed providers, please see the section on [in-house providers](#in-house-providers).