Skip to content

Terraform Providers and State Fundamentals

Step 3 of 18

Terraform Providers and State: Versions, Aliases and Lock Files

Introduction

This Terraform providers and state lesson covers the Terraform fundamentals area of the Terraform Associate (004) exam, objectives 2a to 2d. The four objectives are provider installation/versioning (2a), provider operation (2b), multiple providers (2c) and state (2d). Their count does not establish an official question weighting. The exam lasts one hour, tests Terraform 1.12, and mixes true/false, multiple-choice and multiple-answer questions.

Providers and state are the two ideas that make Terraform work. Providers give Terraform knowledge of a platform. State gives Terraform memory of what it has built. Almost every operational question later in the exam (plan output, drift, imports, backends, HCP Terraform) depends on understanding these two.

After this lesson you will be able to install and version providers, write a required_providers block, explain the dependency lock file, configure several providers or several configurations of the same provider with aliases, and explain how Terraform uses state.

Learning objectives

  • Explain how Terraform installs providers during terraform init and where they come from.
  • Write required_providers with a source address and a version constraint, and read the operators =, !=, >=, ~>.
  • Explain what .terraform.lock.hcl records and when terraform init -upgrade changes it.
  • Configure a provider block, and use alias and provider meta-arguments for multiple regions or accounts.
  • Describe the purpose of state, what it contains, and why it must be protected.

2a. How Terraform installs and versions providers

Terraform core knows nothing about AWS, Azure or GitHub. It loads provider plugins, separate executables that Terraform starts and talks to over RPC. A provider offers resource types (things it can manage, such as aws_s3_bucket), data sources (things it can read) and sometimes functions.

Providers are downloaded when you run terraform init. By default Terraform fetches them from the public Terraform Registry (registry.terraform.io), but a private registry, a network or filesystem mirror, or a local plugin directory can be configured for restricted networks. Providers are stored in the .terraform/providers directory of the working directory.

Source addresses

A provider is identified by a source address of the form [hostname/]namespace/type. The hostname defaults to registry.terraform.io.

Source Meaning
hashicorp/aws The AWS provider published by HashiCorp on the public registry
integrations/github The GitHub provider published by the integrations namespace
registry.example.com/acme/internal A provider on a private registry

The local name you give a provider inside required_providers (for example aws) is the prefix used by its resources (aws_instance). Because the local name and source are separate, a provider from a third-party namespace can still use an intuitive name.

The required_providers block

Declare every provider your configuration needs, with a source and a version constraint, inside the terraform block:

HCL
terraform {
  required_version = "~> 1.12.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.60"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.5, < 4.0"
    }
  }
}

required_version constrains the Terraform CLI; the version argument inside each provider constrains that plugin. Both are independent of the version of your own configuration. The CLI constraint here deliberately selects the 1.12.x line tested by exam 004; the provider v5 range illustrates version semantics and is not a latest-version recommendation.

Version constraints

Operator Example Allows
= (or none) = 5.60.0 Exactly that version
!= != 5.61.0 Anything except that version
>, >=, <, <= >= 5.0 Ranges
~> (pessimistic) ~> 5.60 >= 5.60 and < 6.0; the rightmost number may increase
~> with patch ~> 5.60.1 >= 5.60.1 and < 5.61.0

Pessimistic constraints are the typical choice: they accept bug fixes and minor releases but block a major version that may contain breaking changes. If you omit version, Terraform may install the newest release, which makes runs less predictable, so production code should always constrain it.

The dependency lock file

When terraform init selects provider versions, it records the choice in .terraform.lock.hcl. The file stores the selected version, the constraints and checksums (hashes) used to verify provider packages. Signed registry checksums can cover other platforms as well as the one currently in use.

HCL
provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.62.0"
  constraints = "~> 5.60"
  hashes = [
    "h1:examplehashvalue=",
    "zh:0123abcd...",
  ]
}

The hashes above are placeholders for illustration. Do not create a lock file by copying them; let terraform init generate real values.

Key facts for the exam:

  • The lock file should be committed to version control so everyone, including CI, uses the same provider versions.
  • On later terraform init runs Terraform reuses the locked version even if a newer one satisfies the constraint.
  • terraform init -upgrade disregards the recorded provider version selections, chooses the newest versions allowed by the constraints and updates the lock file.
  • If the lock file says 5.62.0 and you change the constraint so 5.62.0 is no longer allowed, init reports a conflict until you run it with -upgrade.
  • Checksums detect packages that differ from the trusted hashes recorded during initial installation; the first provider selection still requires a trustworthy source. To record hashes for other operating systems (for example when developers use macOS and CI uses Linux) run terraform providers lock -platform=linux_amd64 -platform=darwin_arm64.
  • The lock file covers providers, not modules. Registry module versions are constrained in the module block; use an exact version to pin one release. Other module source types have their own selection mechanisms.

Worked example: a surprise upgrade

Scenario. Dana's team commits main.tf with version = "~> 5.0" for the AWS provider but does not commit .terraform.lock.hcl. A new hire clones the repo, runs terraform init, and the plan shows unexpected changes. The previous plan on Dana's machine was clean. Explain why and how to prevent it.

Reasoning, step by step.

  1. ~> 5.0 allows any 5.x release, so the constraint alone does not fix a version.
  2. Dana's machine had an older 5.x locked in her local lock file.
  3. Without the committed lock file the new hire's init selected the newest 5.x release, which can alter default attribute behaviour.
  4. Different provider versions can produce different plans for identical configuration.

Solution. Commit .terraform.lock.hcl and upgrade deliberately with terraform init -upgrade in a reviewed change.

Why other fixes are weaker. Deleting the lock file makes things less predictable. Removing the constraint allows even a major upgrade. Pinning in the state file is not a Terraform feature.

2b. How Terraform uses providers at run time

  1. Init installs providers and initialises the backend.
  2. Plan loads each provider, configures it with its credentials and settings, asks it to read existing objects, and compares them with the configuration.
  3. Apply calls the provider to create, update or destroy objects, then stores the results in state.

A provider block holds platform-wide settings:

HCL
provider "aws" {
  region = "eu-west-1"

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

Avoid literal credentials in provider blocks. Prefer a provider-supported credential chain, workload identity or short-lived credentials; temporary AWS credentials include a session token as well as the access key pair. Keeping credentials outside configuration reduces exposure, but does not guarantee that resource attributes, logs or saved plans contain no secrets.

Providers are not Terraform core

Terraform core and providers are released separately, and their versions are independent. A tier system exists on the Registry: official (HashiCorp), partner (a vendor in the partner programme) and community. If a question mentions a community-maintained provider, remember that HashiCorp does not support it as an official one, although you can still use it by declaring its source.

2c. Multiple providers and aliases

A configuration can use several different providers (AWS and Cloudflare, for instance). Terraform infers which provider owns a resource from the resource type prefix: aws_s3_bucket goes to the aws provider.

Sometimes you need more than one configuration of the same provider: two AWS regions, two accounts, or two Kubernetes clusters. Use alias:

HCL
provider "aws" {
  region = "eu-west-1"
}

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

resource "aws_s3_bucket" "primary" {
  bucket = "brightwave-primary-data"
}

resource "aws_s3_bucket" "replica" {
  provider = aws.dr
  bucket   = "brightwave-replica-data"
}

Rules:

  • A provider block without an alias is the default configuration. Resources use it automatically.
  • An aliased configuration can be selected explicitly by a resource or passed to a child module with its providers map.
  • Modules receive the default provider configuration from their caller; to give a module a non-default one, pass it with the providers argument of the module block (lesson 6).
  • Provider configurations belong in the root module. Child modules should declare their own provider requirements and any configuration_aliases they expect, while receiving provider configurations from their caller.

If every provider block has an alias, Terraform creates an implied empty default configuration. A resource that omits provider uses that default; missing required settings may cause an error. See Terraform modules and provider configuration.

Worked example: disaster recovery bucket

Scenario. Brightwave stores data in eu-west-1 and must keep a copy in us-east-1. An engineer writes two aws_s3_bucket resources and one provider block with region eu-west-1. Both buckets are created in Ireland. Why, and how is it fixed?

Reasoning.

  1. Without a provider meta-argument, every AWS resource uses the default provider configuration.
  2. The default points to eu-west-1.
  3. A second, aliased provider with us-east-1 must exist, and the replica bucket must reference it.

Solution. Add an AWS provider configuration with alias = "dr" and region = "us-east-1" on separate lines, as in the code above, and set provider = aws.dr on the replica. This is the code shown above. Use globally unique bucket names. Creating two buckets does not itself configure S3 cross-region replication; replication requires additional resources and permissions.

Why the alternatives are weaker. Aliases explicitly select two provider configurations within one plan. Running the same configuration with different variable values does not automatically create separate state: reusing one state can retarget existing resource addresses. Separate configurations or workspaces can be valid designs, but they require deliberate state boundaries and coordination.

2d. How Terraform uses and manages state

Terraform must connect each block in your configuration to a real object. For example, aws_instance.web is just a name; the real server has an ID like i-0a1b2c3d4e5f6a7b8. This mapping, together with attribute values and metadata, is stored in state.

By default state is a JSON file called terraform.tfstate in the working directory (the local backend). Terraform also keeps terraform.tfstate.backup as the previous version. State can instead live in a remote backend (lesson 7).

What state is used for

Purpose Explanation
Mapping Links resource addresses to real object IDs
Metadata Stores resource dependencies, provider information and schema versions, so correct ordering is possible even for resources removed from configuration
Performance Caches recorded attribute values; a normal plan still refreshes managed objects through providers by default
Synchronisation In a team, a shared remote state with locking lets everyone work from the same record

Without state, Terraform could not tell that aws_instance.web already exists, and would try to create it again. It also could not know what to destroy when you delete a block from the configuration.

Plan as a three-way comparison

During planning Terraform compares: the configuration (what you want), the state (what Terraform believes it manages) and the real infrastructure (read through the provider while refreshing). It then proposes the actions that bring reality into line with the configuration.

State contains sensitive data

State can contain resource attributes such as database passwords, generated keys and private IPs. Marking a variable sensitive hides it in CLI output but does not remove it from state; raw output and explicit inspection commands can reveal it. Terraform 1.12 also supports ephemeral values and provider-defined write-only arguments, which omit those specific values from state and plan files. They have restricted usage and provider support requirements; they do not remove the need to protect ordinary state. For that reason:

  • Never commit terraform.tfstate to Git; add it to .gitignore.
  • Prefer a remote backend with encryption at rest, access control and locking.
  • Restrict who can read state, since reading state is equivalent to reading many secrets.
  • Do not edit state by hand. Use supported terraform state subcommands or configuration-driven moved and import blocks for their intended operations. Removing an attribute manually is not a secret-management technique; rotate exposed credentials and address sensitive backups too.

Worked example: why a lost state file is painful

Scenario. A developer deletes the local terraform.tfstate by mistake, then runs terraform plan for a configuration that previously created a VPC and three instances. The plan shows four resources to create. What happened, and what is the risk?

Reasoning.

  1. Terraform reads state to find what it already manages.
  2. With an empty state, no resource has a recorded ID, so each block looks new.
  3. Applying would try to create duplicates, which may fail on name conflicts or silently create extra, costly resources, while the old ones remain unmanaged.

Solution. Restore state from a backup or remote backend history, or re-import each existing object into state. Use a remote backend with versioning to avoid the situation.

Why the other idea is wrong. Running terraform refresh cannot rebuild the mapping, because refresh only updates values for resources already in state.

For shared storage, locking and drift reconciliation, continue with Terraform state management and backends.

Comparing the key files

File or directory Created by Commit to Git? Purpose
*.tf You Yes Configuration
.terraform.lock.hcl terraform init Yes Locked provider versions and hashes
.terraform/ terraform init No Downloaded providers and modules, backend settings
terraform.tfstate terraform apply No Local state
terraform.tfstate.backup terraform apply No Previous state
*.tfvars with secrets You No Variable values

Common pitfalls

  • Forgetting to commit the lock file, producing different provider versions across machines.
  • Thinking ~> 5.0 and ~> 5.0.0 are the same: the first allows 5.x, the second only 5.0.x.
  • Putting credentials in the provider block or committing *.tfvars with secrets.
  • Creating an aliased provider and forgetting to reference it from a resource; it will be unused.
  • Treating state as harmless: it contains secrets and must be protected.
  • Editing the state file manually instead of using supported commands.
  • Believing sensitive = true encrypts state; it only hides values in CLI output.

Exam tip. "Which command downloads providers?" is terraform init. "Which file pins provider versions?" is .terraform.lock.hcl. "Which command ignores the lock and takes newer versions?" is terraform init -upgrade. These three facts appear in many variations.

Mini case study: two regions, one reviewer

Situation. Northfield Analytics has a configuration that creates a primary database subnet in eu-central-1 and must create a read replica network in ap-southeast-2. The repository has no lock file, the AWS provider is declared without a version, and a teammate's laptop and the CI runner produced different plans last week. The state is a local file kept on the lead engineer's laptop.

Question. List the changes you would make and explain each.

Commented solution.

  1. Add a version constraint, for instance version = "~> 5.60", so a surprise major release cannot slip in. The pessimistic operator accepts fixes and minors only.
  2. Run terraform init and commit .terraform.lock.hcl. CI and every developer now select the same provider version, eliminating that source of plan variation; credentials, variables and remote drift can still differ. Use terraform providers lock for the CI platform if hashes are missing.
  3. Add an aliased provider for ap-southeast-2 and set provider = aws.apac on the replica network resources, keeping the default provider for the primary region.
  4. Move state to a remote backend with locking and encryption, because state on one laptop is a single point of failure and a secret-leak risk. (Details in lesson 7.)
  5. Add terraform.tfstate* and .terraform/ to .gitignore.
  6. Keep credentials out of the provider blocks, using environment variables or federated identity in CI.

Key terms

  • Provider: plugin that implements resource types and data sources for a platform.
  • Source address: hostname/namespace/type identifying a provider.
  • Version constraint: rule limiting acceptable versions.
  • Dependency lock file: .terraform.lock.hcl, recording selected provider versions and checksums.
  • Alias: a name for an additional configuration of the same provider.
  • State: Terraform's record mapping configuration to real objects.
  • Backend: where state is stored and how operations run.
  • Refresh: reading real objects to update state.

Summary checklist

  • I know providers are installed by terraform init from the Registry or another configured source.
  • I can write required_providers with a source and version constraint.
  • I can explain ~> and compare it with >= and =.
  • I know the lock file should be committed and that -upgrade refreshes it.
  • I can use alias and provider = aws.alias for a second region or account.
  • I can explain what state stores and why Terraform needs it.
  • I know state may contain secrets and must not be committed or hand-edited.

Official sources