Andrew Mercer
on this page

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:

  1. They're precise. Terraform knows which attribute you need. If the VNet's name is known at plan time, the subnet plans fully even before the VNet exists.
  2. They carry data. The edge and the value travel together, so the dependency can't fall out of sync with the configuration.
  3. They maximise parallelism. Only true data dependencies serialise work.
  4. 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.

  1. 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] }

  1. Side effects through another system. A Key Vault access policy that must exist before an App Service starts and resolves @Microsoft.KeyVault(...) references.

  2. Ordering between a resource and a provisioner or action that touches it out of band.

  3. 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 a depends_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_on on 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+) or terraform graph | dot -Tsvg, filtered to the resources you care about.