Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Providers and Resources

Providers and Version Constraints

Configure Terraform providers: required_providers and source addresses, version constraints like ~>, the dependency lock file, provider blocks, aliases for multi-region setups.

A provider is the plugin that lets Terraform manage one platform: AWS, Azure, Google Cloud, Cloudflare, GitHub, Kubernetes, a database, even a random-number generator. Without a provider Terraform cannot create anything. This lesson shows how to declare which providers you need, how to pin their versions so a new release does not surprise you, how to configure credentials and regions, and how to use several configurations of the same provider, for example two AWS regions.

Provider code is hcl and read-only here. The runnable stand-ins show how version constraints are resolved and how aliases select a configuration.

Declaring providers

Declare every provider your module uses inside the terraform block:

HCL
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = ">= 5.0, < 6.0"
    }
  }
}

The source address has the form [hostname/]namespace/type. hashicorp/aws is shorthand for registry.terraform.io/hashicorp/aws: namespace hashicorp (the publisher), type aws. The key on the left (aws) is the local name used in your module; resource types start with it: aws_instance belongs to the provider whose local name is aws. Providers from other publishers always need an explicit source. Partner and community providers live in the same registry; OpenTofu uses registry.opentofu.org, and mirrors can serve both.

Version constraints

Provider versions follow semantic versioning (MAJOR.MINOR.PATCH). A version constraint says which versions you accept:

Constraint Meaning
= 6.2.0 or 6.2.0 Exactly this version
!= 6.2.0 Anything except this version
>= 6.0, > 6.0, <= 6.9, < 7.0 Comparisons
~> 6.2 >= 6.2 and < 7.0 (the rightmost number may increase)
~> 6.2.1 >= 6.2.1 and < 6.3.0
>= 5.1, < 7.0 Several conditions combined with commas: all must hold

The pessimistic operator ~> is the most used. It allows new minor and patch releases (bug fixes and compatible features) but not a new major version, which may contain breaking changes. The same constraint syntax works for required_version (Terraform itself) and for module versions.

Python Resolving version constraints (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

terraform init picks the newest version that satisfies all constraints in the whole configuration (including modules), and records the choice in the lock file.

The dependency lock file

.terraform.lock.hcl pins the exact version and checksums chosen:

HCL
provider "registry.terraform.io/hashicorp/aws" {
  version     = "6.2.1"
  constraints = "~> 6.0"
  hashes = [
    "h1:AbCd...",
    "zh:0123...",
  ]
}

Commit it. Everyone on the team, and CI, then installs the identical provider, and a changed or tampered package fails the checksum. Upgrade deliberately with terraform init -upgrade, review the lock file diff, and commit it. If your team works on several platforms (macOS laptops, Linux CI) run terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 -platform=windows_amd64 so the lock file has hashes for all of them.

Provider configuration

A provider block sets arguments for the provider: region, credentials, endpoints, default tags.

HCL
provider "aws" {
  region = var.region

  default_tags {
    tags = {
      Project   = "shop"
      ManagedBy = "terraform"
    }
  }
}

Never write secrets in a provider block. Providers read standard environment variables (AWS_ACCESS_KEY_ID, AWS_PROFILE, GOOGLE_APPLICATION_CREDENTIALS, ARM_CLIENT_ID, GITHUB_TOKEN, ...), shared credential files, or workload identity (an IAM role on the CI runner). Environment-based credentials keep keys out of Git and out of state. The provider documentation lists the options in order of priority.

Some providers need no configuration at all (random, local, null). A provider block may use variables and data from other places in the same module, but it cannot depend on resources it manages itself in ways that create a loop.

Multiple configurations with alias

You often need two configurations of one provider: another region, another account, or another Kubernetes cluster. Give the extra one an alias:

HCL
provider "aws" {
  region = "eu-central-1"          # default configuration
}

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

resource "aws_s3_bucket" "eu" {
  bucket = "example-eu-data"
}

resource "aws_s3_bucket" "us" {
  provider = aws.us_east
  bucket   = "example-us-data"
}

A resource without a provider argument uses the default (unaliased) configuration. A resource that sets provider = aws.us_east uses the alias. A classic reason: CloudFront needs ACM certificates in us-east-1 no matter where the rest lives.

Python Which provider configuration does a resource use? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Providers and modules

Child modules inherit the default provider configuration of the caller. To pass an alias, use the providers argument:

HCL
module "cdn" {
  source = "./modules/cdn"
  providers = {
    aws = aws.us_east
  }
}

A reusable module should not contain provider blocks with settings; it declares only required_providers (and configuration_aliases if it needs several), and the root module configures them. More in Modules.

Special providers

A few providers need no cloud and are very useful in practice:

Provider Use
random Random IDs, passwords, pet names that stay stable until replaced
local Write and read files on the machine running Terraform
null / terraform_data Triggers and provisioners without a real resource
time Stable timestamps, delays (time_sleep)
tls Keys and certificates (state will hold private keys)
http, external Call an API or a script as a data source

Troubleshooting provider problems

  • "Failed to query available provider packages": no network access to the registry, a wrong source, or no version matches your constraint.
  • "Inconsistent dependency lock file": you changed a constraint; run terraform init -upgrade.
  • "Provider configuration not present": a resource in state references a provider alias you removed.
  • Slow plans: many resources make many API calls; -parallelism and -refresh=false help in emergencies.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What versions does ~> 6.2 allow?

    With two parts, ~> lets the minor version grow but not the major: >= 6.2 and < 7.0. ~> 6.2.1 would be < 6.3.0.
  2. 2. Why commit .terraform.lock.hcl?

    The lock file pins exact provider versions and checksums, so teammates and CI install identical plugins.
  3. 3. How does a resource use a non-default provider configuration?

    Set the provider meta-argument to <local name>.<alias>.
  4. 4. Where should provider credentials come from?

    Keep secrets out of code. Providers read them from the environment or the platform's identity mechanism.

Summary

  • Declare providers in required_providers with a source and a version constraint.
  • ~> allows new minor/patch versions but blocks the next major.
  • The lock file pins exact versions and checksums; commit it and upgrade with init -upgrade.
  • Configure providers with provider blocks and environment credentials, never hard-coded secrets.
  • alias gives several configurations of one provider; resources pick one with provider = type.alias.
  • Modules inherit the default provider and receive aliases through providers = { ... }.

Next: Resources and References