Version Constraints and Lock File

## What the block is for Terraform Core does not know how to talk to AWS, Cloudflare or Datadog. Every resource type is implemented by a **provider plugin**, a separate binary that Terraform downloads during `terraform init`. `required_providers` is how a module tells Terraform which plugins it needs and which releases of them are acceptable. It is a nested block inside the top-level `terraform` block: ```hcl terraform { required_version = ">= 1.5.0" required_providers { aws = { source = "hashicorp/aws" version = "~> 5.0" } cloudflare = { source = "cloudflare/cloudflare" version = "~> 4.0" } } } ``` ## The three parts of an entry **The local name** is the map key (`aws`, `cloudflare`). It is the name used everywhere else in *this* module: the prefix of resource and data-source types (`aws_s3_bucket`, `data.aws_ami`) and the label on a `provider "aws"` block. Local names are per-module — nothing forces two modules to use the same one, which is exactly why the source address has to be spelled out. **`source`** is the provider's global address, written `[<HOSTNAME>/]<NAMESPACE>/<TYPE>`. The hostname defaults to `registry.terraform.io`, so `hashicorp/aws` expands to `registry.terraform.io/hashicorp/aws`. The namespace is the publishing organization; the type is the provider's name. Two providers with the same type but different namespaces are entirely different plugins. **`version`** is a constraint string — one or more comma-separated conditions using `=`, `!=`, `>`, `>=`, `<`, `<=` or `~>`, all of which must hold. It expresses a *range* of acceptable releases, not a single build. ## Why `source` became mandatory Before Terraform 0.13, providers were assumed to be published by HashiCorp, and the local name was the whole identity. That made third-party providers awkward and made it impossible to state, unambiguously, which plugin a module wanted. From 0.13 onward every provider has a full source address, and any provider outside the `hashicorp` namespace **must** be declared. Omitting `source` is not an error at parse time — Terraform quietly assumes `hashicorp/<local name>` and then fails at `init` with a registry lookup error for a provider that was never published under that namespace. That is one of the most common first-day Terraform errors, and it looks like a network problem rather than a configuration mistake. ## Where the block goes Every module that declares resources should declare the providers it uses, including child modules. A child module declares `required_providers` but should **not** configure the provider — provider configuration is inherited from the root. Terraform intersects the constraints from the root module and all child modules and picks a single version that satisfies all of them; if the ranges do not overlap, `init` fails with a message naming the conflicting modules. This is why a child module that pins a provider to an exact version is antisocial: it makes the whole configuration unupgradable. ## What happens at init `terraform init` resolves all provider constraints, picks the newest release satisfying them, downloads the plugin into `.terraform/providers/`, and records the chosen version plus checksums in `.terraform.lock.hcl` in the root module directory. `.terraform/` is a local cache and is gitignored; the lock file is committed. On later runs, `init` reuses the locked version rather than re-resolving, so everyone on the team and in CI runs the same plugin build. ## Common mistakes Writing only `version = "~> 5.0"` with no `source` for a community provider; assuming the local name must match the namespace (`cloudflare/cloudflare` happens to repeat, `hashicorp/aws` does not); expecting `version` to guarantee a specific build (it is a range — the lock file is what makes it reproducible); and putting `required_providers` at the top level of the file instead of inside `terraform { }`.