Add provider block reference rewrite #557
Conversation
Vercel Previews Deployed
|
|
I'm not going to fix the broken links yet, because they aren't related to the provider page I'm proposing here and these are all unrelated. So we'll fix these all later! |
| @@ -0,0 +1,419 @@ | |||
| --- | |||
| page_title: Provider block reference for the Terraform configuration language | |||
| description: Use the `provider` block to declare and configure Terraform plugins, called providers. Providers let Terraform manage real-world infrastructure with provider-defined resources and data sources. | |||
There was a problem hiding this comment.
Debating adding "functions
| description: Use the `provider` block to declare and configure Terraform plugins, called providers. Providers let Terraform manage real-world infrastructure with provider-defined resources and data sources. | |
| description: Use the `provider` block to declare and configure Terraform plugins, called providers. Providers let Terraform manage real-world infrastructure with provider-defined resources, data sources, and functions. |
Counterargument: We'd want to add , and actions when they're released.
|
|
||
| Anyone can develop a Terraform provider and use it locally, or publish it to the Terraform public registry or HCP Terraform private registry. To learn more about authoring providers, refer to the [Plugin framework](/terraform/plugin/framework). | ||
|
|
||
| Each Terraform module must declare which providers it requires, so that Terraform can install and use them. To declare a provider in a module, perform the following three steps: |
There was a problem hiding this comment.
| Each Terraform module must declare which providers it requires, so that Terraform can install and use them. To declare a provider in a module, perform the following three steps: | |
| Each Terraform root module should declare which providers it requires, so that Terraform can install and use them. To declare a provider in a module, perform the following three steps: |
So root module because per our module docs:
Provider configurations, unlike most other concepts in Terraform, are global to an entire Terraform configuration and can be shared across module boundaries. Provider configurations can be defined only in a root Terraform module.
We mention this below (line 30), so maybe the last sentence can be left off here.
And should instead of must because Terraform will automagically install a matching provider based on resource name even if you don't add the required_providers or provider block...we should maybe mention this somewhere?
eg, this configuration by itself will work:
main.tf:
resource "random_pet" "foo" {
length = 2
}
output "pet_name" {
value = random_pet.foo.id
}
$ terraform init && terraform apply -auto-approve:
Initializing the backend...
Initializing provider plugins...
- Finding latest version of hashicorp/random...
- Installing hashicorp/random v3.7.2...
- Installed hashicorp/random v3.7.2 (signed by HashiCorp)
Terraform has created a lock file .terraform.lock.hcl to record the provider
## ...
random_pet.foo: Creation complete after 0s [id=capital-raptor]
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
Outputs:
pet_name = "capital-raptor"
| 1. Define the provider's source, local name, and version in the [`required_providers` block](/terraform/language/block/terraform#required_providers) inside your top-level `terraform` block. | ||
| 1. Add a top-level `provider` block to your configuration to configure a provider with authentication, a region, and other provider-specific arguments. | ||
| 1. Install your provider. | ||
| - Running `terraform init` locally installs a provider and updates the [Dependency lock file](/terraform/language/files/dependency-lock) with the version you specified in your configuration. |
There was a problem hiding this comment.
| - Running `terraform init` locally installs a provider and updates the [Dependency lock file](/terraform/language/files/dependency-lock) with the version you specified in your configuration. | |
| - Running `terraform init` locally installs a provider and updates the [Dependency lock file](/terraform/language/files/dependency-lock) with the latest version matching the version string you configured in your `required_providers` block. |
| 1. Add a top-level `provider` block to your configuration to configure a provider with authentication, a region, and other provider-specific arguments. | ||
| 1. Install your provider. | ||
| - Running `terraform init` locally installs a provider and updates the [Dependency lock file](/terraform/language/files/dependency-lock) with the version you specified in your configuration. | ||
| - HCP Terraform and Terraform Enterprise install providers as part of every run. |
There was a problem hiding this comment.
| - HCP Terraform and Terraform Enterprise install providers as part of every run. | |
| - HCP Terraform and Terraform Enterprise install providers as part of every run, using the versions provided in the dependency lock file, if it exists. |
| - Running `terraform init` locally installs a provider and updates the [Dependency lock file](/terraform/language/files/dependency-lock) with the version you specified in your configuration. | ||
| - HCP Terraform and Terraform Enterprise install providers as part of every run. | ||
|
|
||
| If you are running Terraform locally, your plan and apply operations use the provider versions specified in the dependency lock file. You can upgrade a provider version in your lock file by changing the value in your configuration and re-running `terraform init`. To learn more about declaring providers, refer to [Provider requirements](/terraform/language/providers/requirements). |
There was a problem hiding this comment.
| If you are running Terraform locally, your plan and apply operations use the provider versions specified in the dependency lock file. You can upgrade a provider version in your lock file by changing the value in your configuration and re-running `terraform init`. To learn more about declaring providers, refer to [Provider requirements](/terraform/language/providers/requirements). | |
| If you are running Terraform locally, your plan and apply operations use the provider versions specified in the dependency lock file. You can upgrade a provider version in your lock file by changing the version in the `required_providers` block and re-running `terraform init`. To learn more about declaring providers, refer to [Provider requirements](/terraform/language/providers/requirements). |
|
|
||
| You can use [expressions](/terraform/language/expressions) to configure provider arguments, but you can only reference values that Terraform knows before it applies your configuration. Meaning, you can reference input variables and arguments that you specify directly in your configuration, but not any computed resource attributes, such as `google.web.public_ip`. | ||
|
|
||
| Many providers support shell environment variables or other alternate sources for their configuration values, which helps keep credentials out of your version-controlled Terraform code. Refer to a provider's documentation to learn more about the assignment methods each argument supports. |
There was a problem hiding this comment.
| Many providers support shell environment variables or other alternate sources for their configuration values, which helps keep credentials out of your version-controlled Terraform code. Refer to a provider's documentation to learn more about the assignment methods each argument supports. | |
| Many providers support shell environment variables or other alternate sources for their configuration values, which helps keep credentials out of your version-controlled Terraform configuration. Refer to a provider's documentation to learn more about the assignment methods each argument supports. |
|
|
||
| ### `version` | ||
|
|
||
| The `version` argument in provider configurations is deprecated, and Terraform will remove it in a future version. Instead, declare provider version constraints in [the `terraform` block's `required_providers` argument](/terraform/language/providers/requirements). |
There was a problem hiding this comment.
| The `version` argument in provider configurations is deprecated, and Terraform will remove it in a future version. Instead, declare provider version constraints in [the `terraform` block's `required_providers` argument](/terraform/language/providers/requirements). | |
| The `version` argument in provider configurations is deprecated, and Terraform will remove it in a future version. Instead, declare provider version constraints in [the `terraform` block's `required_providers` block](/terraform/language/providers/requirements). |
|
|
||
| </CodeBlockConfig> | ||
|
|
||
| You can further configure a provider with the `provider` block in the root module of your configuration. |
There was a problem hiding this comment.
| You can further configure a provider with the `provider` block in the root module of your configuration. | |
| You can configure the provider with the `provider` block in the root module of your configuration. |
Maybe I'm splitting hairs, but my thinking is that the required_providers block configures terraform to use the specified provider, and the provider's configuration is in the provider block?
There was a problem hiding this comment.
Also...should we mention somewhere that the terraform { } block being in terraform.tf and the provider "google" { } block in main.tf is our recommended convention?
|
|
||
| ### Pass provider configurations to a child module | ||
|
|
||
| We recommend defining providers in root modules, and passing those provider configurations from parent modules to child modules to ensure your modules all use the same provider configurations. You can pass provider configurations from a root module to child modules using the [`providers` argument](/terraform/language/meta-arguments/module-providers). |
There was a problem hiding this comment.
This implies that we recommend explicitly passing providers to child modules rather than relying on implicit passing...I don't think we intend to do that, but I could be wrong...eg the main use modules tutorial passes the provider implicitly.
Also, I'm not sure how much is recommendation vs. requirement, eg our current docs say: Provider configurations can be defined only in a root Terraform module. - I don't think that's technically correct, but I think our intent is "Don't do this" rather than a soft recommendation.
There was a problem hiding this comment.
Also also, assuming implicitly passing providers is ok, and the default behavior is fine, then we should introduce an example of that first, before explicit example.
There was a problem hiding this comment.
Whatever the final wording is, we should add it to the main usage page and link to it from here.
| ```hcl | ||
| provider "random" { | ||
|
|
||
| } | ||
| ``` |
There was a problem hiding this comment.
| ```hcl | |
| provider "random" { | |
| } | |
| ``` | |
| ```hcl | |
| provider "random" { } | |
| ``` |
I see this style in examples more often than the line-break style for "empty" provider configuration.
|
|
||
| Use the `provider` block to declare and configure Terraform plugins, called providers. Providers let Terraform manage real-world infrastructure with provider-defined resources and data sources. | ||
|
|
||
| > **Hands-on:** Try the [Perform CRUD Operations with Providers](/terraform/tutorials/configuration-language/provider-use) tutorial. |
There was a problem hiding this comment.
| > **Hands-on:** Try the [Perform CRUD Operations with Providers](/terraform/tutorials/configuration-language/provider-use) tutorial. | |
| > **Hands-on:** Try the [Perform CRUD Operations with Providers](/terraform/tutorials/configuration-language/provider-use) tutorial. |
Links to tutorials from a reference page seem out of place to me. I would expect them to appear on overview and usage pages because they are more aligned with user learning paths. Not a dealbreaker, but just something we should align on in the future.
|
|
||
| > **Hands-on:** Try the [Perform CRUD Operations with Providers](/terraform/tutorials/configuration-language/provider-use) tutorial. | ||
|
|
||
| ## Background |
There was a problem hiding this comment.
Almost all of this information is misplaced. Workflow-related information, such as developing and distributing providers, should be in the overview page. We should also link to the init command instead of describing how to run it here.
|
|
||
| ### `provider "<PROVIDER_NAME>"` | ||
|
|
||
| The name given in the block header specifies the [local name](/terraform/language/providers/requirements#local-names) of the provider to configure. |
There was a problem hiding this comment.
| The name given in the block header specifies the [local name](/terraform/language/providers/requirements#local-names) of the provider to configure. | |
| You must specify the name of the provider that you want to configure as an inline argument. Refer to [Local names](/terraform/language/providers/requirements#local-names) for more information. |
I had a hard time parsing this sentence, but I think this is what we mean. Ignore if I'm wrong and the only one who was having trouble understanding.
|
|
||
| The name given in the block header specifies the [local name](/terraform/language/providers/requirements#local-names) of the provider to configure. | ||
|
|
||
| The following arguments are supported in a `provider` block: |
There was a problem hiding this comment.
| The following arguments are supported in a `provider` block: | |
| You can specify the following arguments in a `provider` block: |
Active voice
|
|
||
| If you do not explicitly define a `provider` block, Terraform assumes and creates an empty default configuration for that provider. However, if a provider has required arguments, Terraform raises an error because it can't create that provider without the required values. | ||
|
|
||
| You can use [expressions](/terraform/language/expressions) to configure provider arguments, but you can only reference values that Terraform knows before it applies your configuration. Meaning, you can reference input variables and arguments that you specify directly in your configuration, but not any computed resource attributes, such as `google.web.public_ip`. |
There was a problem hiding this comment.
| You can use [expressions](/terraform/language/expressions) to configure provider arguments, but you can only reference values that Terraform knows before it applies your configuration. Meaning, you can reference input variables and arguments that you specify directly in your configuration, but not any computed resource attributes, such as `google.web.public_ip`. | |
| You can use [expressions](/terraform/language/expressions) to configure provider arguments, but you can only reference values that Terraform knows before it applies your configuration. You can reference input variables and arguments that you specify directly in your configuration, but you can't reference computed resource attributes, such as `google.web.public_ip`. |
I don't love the anthropomorphic language about "Terraform knowing" things, but none of the alternatives I've tried have passed mustard. I think we should consider flagging phrases such as "in other words", "meaning", and "that is" in the style guide.
|
|
||
| ### Pass provider configurations to a child module | ||
|
|
||
| We recommend defining providers in root modules, and passing those provider configurations from parent modules to child modules to ensure your modules all use the same provider configurations. You can pass provider configurations from a root module to child modules using the [`providers` argument](/terraform/language/meta-arguments/module-providers). |
There was a problem hiding this comment.
Whatever the final wording is, we should add it to the main usage page and link to it from here.
|
|
||
| ### Using an alternate provider configuration in a child module | ||
|
|
||
| To use an aliased provider configurations in a child module, the child module must declare the alias using the `configuration_aliases` argument in the `required_providers` block. |
There was a problem hiding this comment.
| To use an aliased provider configurations in a child module, the child module must declare the alias using the `configuration_aliases` argument in the `required_providers` block. | |
| To use an aliased provider configurations in a child module, the child module must declare the alias using the `configuration_aliases` argument in the `required_providers` block. |
This is the first time I've seen the configuration_aliases argument. Is this an AWS-specific argument or part of Terraform configuration language? Do we need to add it to the terraform block reference?
| @@ -290,7 +290,7 @@ resource { | |||
|
|
|||
| By default, Terraform automatically selects a provider based on the resource type, but you can create multiple provider configurations and use a non-default configuration for specific resources. | |||
|
|
|||
| Use the `<PROVIDER>.<ALIAS>` syntax to reference a provider configuration in the `provider` argument. Refer to [Multiple Provider Configurations](/terraform/language/providers/configuration#alias-multiple-provider-configurations) for instructions on how to reference a specific provider configuration. | |||
| Use the `<PROVIDER>.<ALIAS>` syntax to reference a provider configuration in the `provider` argument. Refer to [Using an alternate provider configuration](/terraform/language/block/provider#using-an-alternate-provider-configuration) for an example of how to reference a specific provider configuration. | |||
There was a problem hiding this comment.
| Use the `<PROVIDER>.<ALIAS>` syntax to reference a provider configuration in the `provider` argument. Refer to [Using an alternate provider configuration](/terraform/language/block/provider#using-an-alternate-provider-configuration) for an example of how to reference a specific provider configuration. | |
| Use the `<PROVIDER>.<ALIAS>` syntax to reference a provider configuration in the `provider` argument. |
I think we can remove this link since there is already an example on this page
| @@ -9,7 +9,7 @@ description: >- | |||
|
|
|||
| In a [module call](/terraform/language/modules/syntax) block, the | |||
| optional `providers` meta-argument specifies which | |||
| [provider configurations](/terraform/language/providers/configuration) from the parent | |||
| [provider configurations](/terraform/language/block/provider) from the parent | |||
There was a problem hiding this comment.
| [provider configurations](/terraform/language/block/provider) from the parent | |
| [provider configurations](/terraform/language/block/provider) from the parent |
All of these meta-arguments pages are collapsing into a single concept page per https://hashicorp.atlassian.net/browse/IPE-1128, fyi
| @@ -72,7 +72,7 @@ however, specify any of the configuration settings that determine what remote | |||
| endpoints the provider will access, such as an AWS region; configuration | |||
| settings come from provider _configurations_, and a particular overall Terraform | |||
| configuration can potentially have | |||
| [several different configurations for the same provider](/terraform/language/providers/configuration#alias-multiple-provider-configurations). | |||
| [several different configurations for the same provider](/terraform/language/block/provider#using-an-alternate-provider-configuration). | |||
There was a problem hiding this comment.
| [several different configurations for the same provider](/terraform/language/block/provider#using-an-alternate-provider-configuration). | |
| [several different configurations for the same provider](/terraform/language/block/provider#select-an-alternate-provider-configuration). |
You don't have to use the heading I suggested, just something that follows the style guidance.
Preview the page: https://unified-docs-frontend-preview-qalhfm1yc-hashicorp.vercel.app/terraform/language/block/provider