Terraform decides the order of operations from a dependency graph. You almost never specify order directly. You write references, and the references are the order.
How the graph is built¶
Every expression that mentions another object adds an edge:
resource "azurerm_resource_group" "app" {
name = "rg-app-dev-cc"
location = "canadacentral"
}
resource "azurerm_virtual_network" "app" {
name = "vnet-app-dev-cc"
location = azurerm_resource_group.app.location # edge → resource group
resource_group_name = azurerm_resource_group.app.name # edge → resource group
address_space = ["10.10.0.0/16"]
}
resource "azurerm_subnet" "aks" {
name = "snet-aks"
resource_group_name = azurerm_resource_group.app.name
virtual_network_name = azurerm_virtual_network.app.name # edge → vnet
address_prefixes = ["10.10.0.0/22"]
}
Terraform reads this as RG → VNet → subnet:
- Create/update: dependencies first. The RG, then the VNet, then the subnet.
- Destroy: reverse order. The subnet, then the VNet, then the RG.
- No edge = may run in parallel. Two subnets that only reference the VNet are created concurrently (default
-parallelism=10).
See it for yourself:
terraform graph | dot -Tsvg > graph.svg # Graphviz
terraform graph -format=mermaid > graph.mmd # Terraform 1.16+: paste into docs/MRs
Edges come from references to resources, data sources, modules, variables, locals and outputs. A local that references a resource carries that dependency to everything that uses the local.
Implicit dependencies are the right default¶
An implicit dependency is one Terraform infers from a reference. They're better than explicit ones because:
- They're precise. Terraform knows which attribute you need. If the VNet's
nameis known at plan time, the subnet plans fully even before the VNet exists. - They carry data. The edge and the value travel together, so the dependency can't fall out of sync with the configuration.
- They maximise parallelism. Only true data dependencies serialise work.
- They survive refactoring. Move the resource into a module and the reference becomes
module.net.vnet_name; the dependency moves with it.
Prefer references to resources over hard-coded strings¶
# ❌ No edge: Terraform may create the subnet before the VNet exists
resource "azurerm_subnet" "aks" {
virtual_network_name = "vnet-app-dev-cc"
resource_group_name = "rg-app-dev-cc"
# ...
}
# ✅ Edge through the reference
resource "azurerm_subnet" "aks" {
virtual_network_name = azurerm_virtual_network.app.name
resource_group_name = azurerm_resource_group.app.name
# ...
}
Hard-coded names that happen to match are the most common source of "works on the second apply" bugs. If a value comes from another resource in the same configuration, reference it. (Across separate stacks, a data source lookup by name is fine; see passing data between stacks.)
Why to avoid depends_on¶
depends_on adds an edge without a reference:
resource "azurerm_role_assignment" "aks_network" {
scope = azurerm_subnet.aks.id
role_definition_name = "Network Contributor"
principal_id = azurerm_user_assigned_identity.aks.principal_id
}
resource "azurerm_kubernetes_cluster" "this" {
# ...
depends_on = [azurerm_role_assignment.aks_network]
}
That one is legitimate (see below). But depends_on has real costs, so it should be rare:
1. It makes values unknown, causing extra diffs¶
When a resource or data source has depends_on, Terraform has to assume anything in the dependency might change. For data sources this is the big one: a data source with depends_on is deferred to apply time whenever the dependency has any pending change, so every attribute it returns becomes (known after apply), and everything downstream shows as "will be updated" or even "must be replaced".
# ❌ Forces the lookup to apply time whenever azurerm_resource_group.app changes,
# making every downstream attribute unknown
data "azurerm_client_config" "current" {
depends_on = [azurerm_resource_group.app]
}
2. It's coarse¶
depends_on = [module.network] makes every resource in this module wait for every resource in the network module, including the ones it doesn't care about. On a big module that serialises the whole apply.
3. It hides intent¶
A reference says what is needed. depends_on says only that something is needed, and six months later nobody remembers why. Always comment it.
4. It's often a symptom¶
Most depends_on blocks in the wild work around one of these:
| Symptom | Real fix |
|---|---|
| Hard-coded name instead of a reference | Reference the resource attribute |
| Module output that doesn't depend on what it should | Fix the output (see below) |
| Data source reading something created in the same run | Use the resource's attributes directly instead of a data source |
| Eventual consistency (e.g. RBAC propagation) | depends_on plus time_sleep, or provider retry settings |
Module outputs: making dependencies flow through¶
When a caller does depends_on = [module.x], it's usually because an output of module.x returns too early. For example, the output returns a VNet ID, but callers also need the subnets and NSG associations finished.
Fix it inside the module so the output itself carries the dependency:
# modules/network/outputs.tf
output "vnet_id" {
description = "VNet ID. Available only after subnets and NSG associations exist."
value = azurerm_virtual_network.this.id
depends_on = [
azurerm_subnet_network_security_group_association.this,
]
}
Now module.network.vnet_id can't be read until the associations exist, and every caller gets the right ordering without a module-wide depends_on. This is one of the few places depends_on improves precision.
An alternative that needs no depends_on at all: output the thing callers actually need (subnet_ids from the association resources) so the reference itself creates the edge.
When depends_on is legitimate¶
Use it when the dependency is real but invisible to Terraform: there's no attribute you could reference.
- Permissions must exist before use. A role assignment or IAM policy that must be in place before a resource that uses the identity is created:
hcl
resource "azurerm_kubernetes_cluster" "this" {
# ...
# The cluster's kubelet identity must be able to join the subnet at create time.
# Nothing in the cluster references the role assignment.
depends_on = [azurerm_role_assignment.aks_network]
}
-
Side effects through another system. A Key Vault access policy that must exist before an App Service starts and resolves
@Microsoft.KeyVault(...)references. -
Ordering between a resource and a provisioner or action that touches it out of band.
-
Module output dependencies, as above.
Even then, keep it narrow: depend on the specific resource, not a whole module, and add a comment saying why.
Eventual consistency needs more than depends_on¶
depends_on guarantees the role assignment API call returned, not that Entra ID / IAM has propagated it. If the next resource still fails with 403 for a minute:
resource "time_sleep" "rbac_propagation" {
depends_on = [azurerm_role_assignment.aks_network]
create_duration = "60s"
}
resource "azurerm_kubernetes_cluster" "this" {
# ...
depends_on = [time_sleep.rbac_propagation]
}
It's ugly, and it's still the standard answer. Check first whether the provider has a built-in retry for that error.
Dependencies between modules¶
module "network" {
source = "../modules/network"
# ...
}
module "aks" {
source = "../modules/aks"
subnet_id = module.network.subnet_ids["aks"] # implicit, precise
}
Since Terraform 0.13, module outputs are resolved per-output: module.aks waits only for what subnet_ids["aks"] depends on, not the whole network module. That's another reason to avoid depends_on = [module.network], which throws that precision away.
Dependencies across state files¶
The graph only covers one root module. Between separately applied stacks:
| Approach | Ordering? | Notes |
|---|---|---|
| Data source by naming convention | No (you apply in the right order) | Loosest coupling, preferred |
terraform_remote_state |
No | Reads outputs; needs read access to the whole state |
Terragrunt dependency |
Yes, run --all builds a cross-stack DAG |
See Terragrunt |
| HCP Terraform run triggers / Stacks | Yes | HCP-only |
| CI pipeline stages | Yes | Explicit, simple, rigid |
More in remote state.
Debugging dependency problems¶
- Cycle errors (
Error: Cycle: a, b): two objects reference each other, often through a module output or adepends_on. Break it by splitting one resource into two (e.g. the NSG and the NSG rule as separate resources), or moving the shared value to a variable. - "Known after apply" everywhere: look for
depends_onon data sources first. - Intermittent create failures that pass on retry: a missing edge (hard-coded name) or eventual consistency.
- Visualise:
terraform graph -format=mermaid(1.16+) orterraform graph | dot -Tsvg, filtered to the resources you care about.