Terraform does not run files top to bottom: it builds a graph from references and `depends_on`, then walks it with up to 10 concurrent operations and destroys in reverse order.
The problem
A team splits infrastructure across files and assumes the order of resources in the file, or the file name, controls the order of creation. It works until a resource relies on a side effect that no expression mentions, such as a file written by a provisioner or a permission that has to exist first, and apply fails on some runs and not on others because two independent resources were started at the same moment. Terraform has no script order: every resource is a node in a graph, and only references between nodes decide what waits for what.
How it works
- The everyday loop is `terraform init` (install providers, configure the backend, fetch modules), `terraform fmt` and `terraform validate` (no API calls, no state needed), `terraform plan` (compute a diff) and `terraform apply` (execute it). `init` must be rerun after you add a provider, change the backend or add a module source.
- All `*.tf` files in the working directory form one module and are merged, so file names and the order of blocks carry no meaning. Subdirectories are not read unless a `module` block points at them. A stray `bad.tf` next to `main.tf` is planned like any other file (verified).
- Edges come from references. `content = "hello ${random_pet.name.id}"` makes `local_file.greeting` depend on `random_pet.name`, and `terraform graph` prints it as `"local_file.greeting" -> "random_pet.name"`: the arrow points from the dependent to its dependency (verified).
- `depends_on = [terraform_data.uses_name]` adds an edge without reading any attribute. Use it only for hidden dependencies, because an explicit edge also forces data sources behind it to be read at apply time instead of plan time and makes the dependent wait for the whole target rather than one attribute.
- Independent nodes run concurrently: `-parallelism=10` is the default. Three independent resources with `sleep 2` provisioners finished in 2.6 s by default and 6.6 s with `-parallelism=1` (verified). Because of this, the order of the `Creating...` lines for independent resources is not stable between runs.
- Destroy walks the same graph in reverse: dependents go first. In the verified run `terraform_data.hidden` was destroyed before `terraform_data.uses_name`, and `random_pet.name` last, mirroring the create order backwards.
- A reference loop cannot be walked, so it is rejected before any API call: `terraform validate` fails with `Error: Cycle:` followed by the addresses involved (verified with two `terraform_data` resources that reference each other).
- `terraform graph` prints Graphviz DOT, by default for the plan walk. Pipe it to `dot -Tsvg` (Graphviz, not run here) for a picture; `-type=plan-destroy` shows the destroy walk. The graph also contains providers, variables, locals and outputs, not only resources.
Examples
One real edge, three independent nodes: the graph and what -parallelism does to wall-clock time.
mkdir graph-demo && cd graph-demo
cat > main.tf <<'HCL'
resource "random_pet" "name" {
length = 2
}
resource "local_file" "greeting" {
filename = "greeting.txt"
content = "hello ${random_pet.name.id}\n"
}
resource "terraform_data" "a" {
provisioner "local-exec" {
command = "sleep 2"
}
}
resource "terraform_data" "b" {
provisioner "local-exec" {
command = "sleep 2"
}
}
resource "terraform_data" "c" {
provisioner "local-exec" {
command = "sleep 2"
}
}
HCL
terraform init
terraform fmt -check
terraform validate
# the reference random_pet.name.id is the only edge; a, b and c are independent
terraform graph | grep -- '->'
# independent nodes run concurrently (default -parallelism=10): about 2 s, not 6 s
time terraform apply -auto-approve
terraform destroy -auto-approve
time terraform apply -auto-approve -parallelism=1Implicit versus explicit edges, and destroy running the create order backwards.
mkdir order-demo && cd order-demo
cat > main.tf <<'HCL'
resource "random_pet" "name" {}
resource "terraform_data" "uses_name" {
input = random_pet.name.id # implicit edge: reads an attribute
}
resource "terraform_data" "hidden" {
depends_on = [terraform_data.uses_name] # explicit edge: no attribute is read
}
HCL
terraform init > /dev/null
terraform graph | grep -- '->'
terraform apply -auto-approve | grep -E 'Creating|Apply'
terraform destroy -auto-approve | grep -E 'Destroying|Destroy complete'In practice
- Terraform CLI — Builds the graph in the core, independent of providers; providers only implement per-resource create, read, update and delete.
- Graphviz — Renders the DOT output of `terraform graph` into SVG or PNG for reviews and onboarding diagrams.
- Terraform Registry modules — A module call is a node too; outputs referenced by other modules create cross-module edges.
- Atlantis — Runs plain `init`, `plan` and `apply` per directory and workspace, so the same graph rules apply to pull-request automation.
- Make — The comparable mental model: targets and prerequisites, not a script; unlike Make, Terraform derives most prerequisites from expressions.
Trade-offs
Pros
- Order is derived from data flow, so refactoring files or moving blocks never changes behaviour
- Independent resources are created in parallel without any extra configuration
- Cycles and unknown references are caught by `validate` before anything is touched
- `terraform graph` makes the real dependencies inspectable
Cons
- Hidden dependencies (timing, permissions, side effects) are invisible to the graph and need `depends_on` or a data flow workaround
- Parallelism can exceed API rate limits and surfaces as intermittent throttling errors
- A broad `depends_on` serialises work and defers data reads to apply time
- Apply logs are not in a stable order, which makes diffing two runs noisy