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 initand where they come from. - Write
required_providerswith a source address and a version constraint, and read the operators=,!=,>=,~>. - Explain what
.terraform.lock.hclrecords and whenterraform init -upgradechanges it. - Configure a provider block, and use
aliasandprovidermeta-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:
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.
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 initruns Terraform reuses the locked version even if a newer one satisfies the constraint. terraform init -upgradedisregards 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.
~> 5.0allows any 5.x release, so the constraint alone does not fix a version.- Dana's machine had an older 5.x locked in her local lock file.
- Without the committed lock file the new hire's init selected the newest 5.x release, which can alter default attribute behaviour.
- 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
- Init installs providers and initialises the backend.
- Plan loads each provider, configures it with its credentials and settings, asks it to read existing objects, and compares them with the configuration.
- Apply calls the provider to create, update or destroy objects, then stores the results in state.
A provider block holds platform-wide settings:
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:
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
providersmap. - Modules receive the default provider configuration from their caller; to give a module a non-default one, pass it with the
providersargument of the module block (lesson 6). - Provider configurations belong in the root module. Child modules should declare their own provider requirements and any
configuration_aliasesthey 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.
- Without a
providermeta-argument, every AWS resource uses the default provider configuration. - The default points to
eu-west-1. - A second, aliased provider with
us-east-1must 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.tfstateto 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 statesubcommands or configuration-drivenmovedandimportblocks 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.
- Terraform reads state to find what it already manages.
- With an empty state, no resource has a recorded ID, so each block looks new.
- 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.0and~> 5.0.0are the same: the first allows 5.x, the second only 5.0.x. - Putting credentials in the provider block or committing
*.tfvarswith 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 = trueencrypts 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?" isterraform 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.
- 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. - Run
terraform initand 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. Useterraform providers lockfor the CI platform if hashes are missing. - Add an aliased provider for
ap-southeast-2and setprovider = aws.apacon the replica network resources, keeping the default provider for the primary region. - 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.)
- Add
terraform.tfstate*and.terraform/to.gitignore. - 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/typeidentifying 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 initfrom the Registry or another configured source. - I can write
required_providerswith a source and version constraint. - I can explain
~>and compare it with>=and=. - I know the lock file should be committed and that
-upgraderefreshes it. - I can use
aliasandprovider = aws.aliasfor 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
- Exam content list: https://developer.hashicorp.com/terraform/tutorials/certification-004/associate-review-004 (opens in a new tab)
- Learning path: https://developer.hashicorp.com/terraform/tutorials/certification-004/associate-study-004 (opens in a new tab)
- Terraform language documentation (providers, state): https://developer.hashicorp.com/terraform/language (opens in a new tab)
- Provider configuration and aliases: https://developer.hashicorp.com/terraform/language/block/provider (opens in a new tab)
- Dependency lock file: https://developer.hashicorp.com/terraform/language/files/dependency-lock (opens in a new tab)
- Version constraints: https://developer.hashicorp.com/terraform/language/expressions/version-constraints (opens in a new tab)
- Purpose of state: https://developer.hashicorp.com/terraform/language/state/purpose (opens in a new tab)
- Sensitive, ephemeral and write-only values: https://developer.hashicorp.com/terraform/language/manage-sensitive-data (opens in a new tab)
