Add provider block reference rewrite #557
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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! |
robin-norwood
approved these changes
Jul 11, 2025
| @@ -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
Suggested change
| 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.
Suggested change
| 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.
Suggested change
| - 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.
Suggested change
| - 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.
Suggested change
| 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.
Suggested change
| 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.
Suggested change
| 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.
Suggested change
| 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.
Comment on lines
+413
to
+417
| ```hcl | ||
| provider "random" { | ||
|
|
||
| } | ||
| ``` |
There was a problem hiding this comment.
Suggested change
| ```hcl | |
| provider "random" { | |
| } | |
| ``` | |
| ```hcl | |
| provider "random" { } |
I see this style in examples more often than the line-break style for "empty" provider configuration.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Preview the page: https://unified-docs-frontend-preview-qalhfm1yc-hashicorp.vercel.app/terraform/language/block/provider