1. Configure providers

Contents

• Provider Requirements
• Require Providers
• Dependency Lock File
  • Lock File Contents
  • Upgrading Providers
• Provider Configuration
• Provider Aliases
  • Using Aliases in Child Modules
• `terraform` Block Reference

---

Terraform relies on plugins called providers to interact with cloud providers, SaaS providers, and other APIs. Terraform configurations must declare which providers they require so that Terraform can install and use them.

Provider Requirements

Each Terraform root module should declare which providers it requires. To declare a provider in a module, perform three steps:

1. Define the provider’s source, local name, and version in the required_providers block inside your top-level terraform block.
2. Configure a top-level provider block with authentication, region, and other provider-specific arguments.
3. Install your provider.
   • Running terraform init locally installs a provider and updates the dependency lock file with the latest version matching the configured version constraint.
   • HCP Terraform and Terraform Enterprise install providers as part of every run, using the versions from the dependency lock file.

Tip

To upgrade a provider version in your lock file, change the version in required_providers and re-run terraform init.

---

Require Providers

Provider requirements are declared in a required_providers block. Each requirement consists of a local name, a source location, and a version constraint:

terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
    }
  }
}

The key determines the provider’s local name (its unique identifier within the module), and the value is an object with:

• source — the global source address for the provider, such as hashicorp/aws
• version — a version constraint specifying compatible provider versions

---

Dependency Lock File

The lock file is always named .terraform.lock.hcl and lives in the working directory alongside .terraform.

• Terraform automatically creates or updates it each time you run terraform init
• You should include this file in version control
• It uses .hcl extension (not .tf) to indicate it is not a Terraform configuration file

Lock File Contents

Field	Description
version	The exact version Terraform selected based on version constraints
constraints	All version constraints Terraform considered (informational only)
hashes	Checksums for valid packages across different platforms

Upgrading Providers

Running terraform init -upgrade makes Terraform consider newer provider versions that still match the configured constraints. This updates version, constraints, and hashes in the lock file.

---

Provider Configuration

The provider block configures a specific provider:

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

Argument	Description	Required?
Provider-specific arguments	Authentication, region, and other settings defined by the provider	Varies
alias	Unique identifier for this provider configuration	Optional
version	Version constraint (deprecated — use required_providers instead)	Optional

Note

If you do not explicitly define a provider block, Terraform creates an empty default configuration. If the provider has required arguments, this will raise an error.

---

Provider Aliases

To create multiple configurations for the same provider, add the alias argument to additional provider blocks:

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

Reference an alias using <PROVIDER_NAME>.<ALIAS> in the provider argument of:

• resource blocks
• data blocks
• module blocks

The provider block without an alias is the default configuration. Resources that don’t specify a provider meta-argument use the default. If every provider block uses an alias, Terraform creates an implied empty default.

---

Using Aliases in Child Modules

The child module must declare the alias using configuration_aliases in its required_providers block.

Root module — main.tf:

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
  }
}

Child module — modules/web-server/main.tf:

terraform {
  required_providers {
    aws = {
      source                = "hashicorp/aws"
      version               = "~> 5.0"
      configuration_aliases = [aws.west]
    }
  }
}
 
data "aws_ami" "amazon_linux" {
  provider = aws.west
  # ...
}

---

terraform Block Reference

The terraform block configures Terraform behavior, including the Terraform version, backend, integration with HCP Terraform, and required providers.

Complete Configuration

terraform {
  required_version = "<version>"
 
  required_providers {
    <PROVIDER> = {
      version = "<version-constraint>"
      source  = "<provider-address>"
    }
  }
 
  provider_meta "<LABEL>" {
    # Only used for specific cases
  }
 
  # `backend` is mutually exclusive with `cloud`
  backend "<TYPE>" {
    "<ARGUMENTS>"
  }
 
  # `cloud` is mutually exclusive with `backend`
  cloud {
    organization = "<organization-name>"
    workspaces {
      tags    = ["<tag>"]
      name    = "<workspace-name>"
      project = "<project-name>"
    }
    hostname = "app.terraform.io"
    token    = "<TOKEN>"
  }
 
  experiments = ["<feature-name>"]
}