Dependencies and the Resource Graph

## Terraform does not execute your files in order HCL files have no execution order. Terraform parses every `.tf` file in the root module (and every module it calls), then constructs a **directed acyclic graph** — a DAG — whose nodes are the things it can act on (managed resources, data sources, provider configurations, module boundaries, variables, outputs, local values) and whose edges mean "this must happen after that". Only once the graph exists does Terraform decide what to create, read, update or destroy, and in what order. The file a resource happens to live in, and its position within that file, are irrelevant. This matters practically: you can split resources across files however you like, and rearranging blocks never changes behaviour. What changes behaviour is the *references* between them. ## Implicit dependencies: references are the edges Any expression that names another object's address creates an edge from the referencing node to the referenced one: ```hcl resource "aws_vpc" "main" { cidr_block = "10.0.0.0/16" } resource "aws_subnet" "app" { vpc_id = aws_vpc.main.id # edge: subnet depends on vpc cidr_block = "10.0.1.0/24" } ``` Terraform now knows the VPC must be created before the subnet, and — just as importantly — *why*: the subnet needs one specific attribute of the VPC. During `terraform plan`, if `aws_vpc.main` does not exist yet, its `id` is not knowable, so the plan renders the subnet's `vpc_id` as `(known after apply)`. That unknown propagates only along the values that actually flow, so the rest of the subnet's plan stays concrete. This is the kind of dependency you should aim for. It costs nothing to maintain, it survives refactoring, and a reader can see the relationship on the line where it matters. ## Explicit dependencies: depends_on Some ordering exists in the provider's world but is never expressed as a value. The classic example is an instance whose software needs an IAM policy attached to its role before it boots. The instance references `aws_iam_instance_profile.app.name`, and the profile references the role — but nothing references the `aws_iam_role_policy`. Terraform is therefore free to create the instance in parallel with the policy, and the application fails on first boot with an access-denied error that disappears when you re-run. `depends_on` adds that missing edge by hand: ```hcl resource "aws_instance" "app" { ami = var.ami_id instance_type = "t3.micro" iam_instance_profile = aws_iam_instance_profile.app.name depends_on = [aws_iam_role_policy.app] } ``` The argument is a **static list of addresses** — `aws_iam_role_policy.app`, `data.aws_ami.base`, `module.network` — with no attribute suffix and no expressions. You cannot compute it from a variable or make it conditional; it must be resolvable before Terraform builds the graph, because the graph is what everything else depends on. Other genuine uses: a resource that only works once a service-linked role or an API activation exists; an application-level ordering constraint the provider's schema does not model; a race where two resources touch the same underlying object (two records with the same name, a bucket policy and an object written by something else). ## Where candidates go wrong The two failure modes are opposite and both common. The first is **omitting** an edge by hardcoding a value — pasting `"subnet-0a1b2c3d"` instead of referencing `aws_subnet.app.id` removes the edge entirely, and the ordering that used to work becomes a coin flip, most visibly on destroy. The second is **decorating** every block with `depends_on` "to be safe", which adds coarse edges Terraform then has to plan conservatively around, and hides which relationships are real. A good rule: reach for `depends_on` only after you have asked "is there an attribute I could reference instead?" and the honest answer is no. When you do add one, leave a comment saying what the hidden dependency is — the whole problem with an explicit edge is that the code no longer explains itself. ## The walk Once built, Terraform walks the DAG, starting every node whose predecessors have completed and running up to ten of them concurrently by default. Graph shape therefore sets the floor on wall-clock time: a chain of ten mutually dependent resources runs serially no matter how much concurrency is available, while a hundred independent resources saturate it immediately. Every unnecessary edge you add pushes the configuration toward the first shape.