provider block reference

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 tutorial.

Background

The provider block configures a named provider, which is a plugin that lets Terraform interact with cloud providers, SaaS providers, and other APIs.

HashiCorp's public Terraform registry distributes providers separately from Terraform itself, and each provider has its own release cadence, documentation, and versions. If you are using HCP Terraform, you can use the private registry to share providers within an organization.

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.

Define provider configurations in the root module of your Terraform configuration. Child modules receive their provider configurations from their parent modules, so we strongly recommend against defining provider blocks in child modules. To learn how to declare providers in your configuration, refer to Provider requirements.

Configuration model

The provider block supports the following arguments:

provider "<PROVIDER_NAME>" block
- <PROVIDER_ARGUMENTS> various
- alias string
- version string (Deprecated)

Complete configuration

All available arguments are defined in the following provider block. The alias and version arguments are optional, and you cannot use both in the same block.

provider "<PROVIDER_NAME>" {
  <PROVIDER_ARGUMENTS>
  alias   = "<ALIAS_NAME>"
  version = "<VERSION_CONSTRAINT>"  # Deprecated
}

Specification

A provider block supports the following configuration.

`provider "<PROVIDER_NAME>"`

You must specify the name of the provider that you want to configure as an inline argument. Refer to Local names for more information.

You can specify the following arguments in a provider block:

Argument	Description	Type	Required?
Provider-specific arguments	Configuration arguments that the provider developer defined.	Various	Varies by provider
`alias`	A unique identifier for a specific provider configuration, letting you use multiple configurations for the same provider.	String	Optional
`version`	A version constraint for the provider. This argument is deprecated.	String	Optional

Provider-specific arguments

The body of the provider block contains configuration arguments for the provider, which are defined by the provider itself.

provider "<PROVIDER_NAME>" {
  <PROVIDER_ARGUMENTS>
}

A provider's documentation lists which configuration arguments it expects. For providers distributed on the Terraform registry, versioned documentation is available on each provider's page.

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 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 cannot reference 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 configuration. Refer to a provider's documentation to learn more about the assignment methods each argument supports.

Summary

Data type: Various, depending on the provider
Default: None, but requirements vary by provider
Required: Varies by provider
Example: Select an alternate provider configuration

`alias`

Optionally use the alias argument to define multiple configurations for the same provider. Defining multiple provider aliases lets you specify which provider configuration to use for individual resources, data sources, or modules.

To create multiple configurations for a given provider, include multiple provider blocks with the same provider name, then add the alias argument to each additional provider configuration to give it a unique identifier.

provider "exampleName" {
  region = "us-east-1"
}

provider "exampleName" {
  alias  = "west"
  region = "us-west-1"
}

To refer to a provider alias, use <PROVIDER_NAME>.<ALIAS> in the provider argument of the following blocks:

If there are multiple aliases for a provider, the provider block without an alias argument is the default configuration for that provider. Resources, data sources, and modules that don't specify the provider meta-argument use the default provider configuration that matches the resource type name.

Summary

Data type: String
Default: None
Refer to the following examples to learn more about aliasing providers:

`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 block.

Summary

Data type: String
Default: None
Deprecated

Examples

The following examples demonstrate common use cases for provider blocks.

Basic provider configuration

The following example configures the google provider with a specific project and region. In the terraform block's required_providers block you define the provider version you want to use, where to source the provider from, and the local name of the provider:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.0"
    }
  }
}

You can configure the provider with the provider block in the root module of your configuration.

provider "google" {
  project = "acme-app"
  region  = "us-central1"
}

Multiple provider configurations

In the following example, two configurations for the AWS provider support different regions. The default configuration targets the us-east-1 and the aliased configuration targets us-west-2:

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

Resources that begin with aws_ use the default aws provider configuration unless you supply the provider argument.

Select an alternate provider configuration

You can make a resource, data source, or module use an alternate provider configuration by setting the provider meta-argument to a <PROVIDER_NAME>.<ALIAS> reference.

In the following example, the aws_instance.foo resource uses the aws.west provider configuration, and aws_instance.bar uses the default aws provider configuration:

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

resource "aws_instance" "foo" {
  provider = aws.west
  # …
}

resource "aws_instance" "bar" {
   # …
}

Provider without a default configuration

If there are multiple aliases for a provider in your configuration, the provider block without an alias argument is the default configuration for that provider. If every provider block in your configuration uses an alias, Terraform creates an implied empty default configuration for that provider. Any resource that does not specify a provider meta-argument uses the empty default configuration.

In the following example, both AWS provider configurations use aliases, but the aws_s3_bucket does not specify a provider argument:

provider "aws" {
  alias  = "east"
  region = "us-east-1"
}

provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

resource "aws_s3_bucket" "default_provider" {
  bucket = "uses-implied-empty-config"
}

Terraform uses the implied empty default configuration for the aws_s3_bucket resource because the resource doesn't specify a provider argument. If a provider requires specific arguments, Terraform returns an error when resources try to use the default configuration because the default is not properly configured.

Pass provider configurations to a child module

When you define a provider in your root module, Terraform implicitly passes that provider configuration to any child modules to ensure all modules use the same configuration.

In the following example, the root module defines an AWS provider configuration and Terraform implicitly passes that configuration to a child module:

provider "aws" {
  region = "us-west-2"
}

module "vpc" {
  source = "./modules/vpc"
}

The child module uses the provider configuration passed from the root module:

terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"

  tags = {
    Name = "Main VPC"
  }
}

The aws_vpc resource inherits the same AWS provider configuration from the root module, and Terraform creates the aws_vpc resource in the us-west-2 region.

Child modules do not inherit provider source or version requirements, so you must explicitly define those within a child module. Learn more about inheriting providers in modules.

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.

In the following example, the root module passes the aws.west alias to the web-server child module:

provider "aws" {
  region = "us-east-1"
}

provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

module "web-server" {
  source = "./modules/web-server"
  providers = {
    aws.west = aws.west
  }
}

The following configuration_aliases argument declares that the child module expects to receive a provider configuration it can reference as aws.west. Without this declaration, Terraform raises an error when the module tries to reference aws.west in its resources.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
      configuration_aliases = [aws.west]
    }
  }
}

data "aws_ami" "amazon_linux" {
  provider = aws.west

  #...
}

Modules have special requirements for providers, refer to Providers within modules to learn more.

Provider configuration with expressions

In the following example, the provider configuration uses input variables and local values to set its arguments:

variable "aws_region" {
  description = "The AWS region to deploy resources in"
  type        = string
  default     = "us-west-2"
}

locals {
  common_tags = {
    Environment = "production"
    Project     = "web-app"
  }
}

provider "aws" {
  region = var.aws_region

  default_tags {
    tags = local.common_tags
  }
}

Provider configuration without arguments

In the following example, the provider block defines an empty configuration for the random provider. Terraform also assumes an empty default configuration for any provider that you do not explicitly configure with a provider block:

provider "random" { }

You can choose to omit this block entirely if you don't need to configure any provider-specific arguments.