Dependency Graph

This topic explains the dependency graph Terraform builds from Terraform configurations. This is an advanced topic and not required to understand how to use Terraform.

Introduction

Terraform builds a dependency graph and uses it to perform operations, such as generate plans and refresh state.For background on graph theory and a summary of howTerraform applies it, refer the HashiCorp 2016 presentationApplying Graph Theory to Infrastructure as Code.

Graph Nodes

The following node types can exist within the graph:

• Resource Node - Represents a single resource. If you havethecount metaparameter set, then there will be one resourcenode for each count. The configuration, diff, state, etc. ofthe resource under change is attached to this node.

• Provider Configuration Node - Represents the time to fullyconfigure a provider. This is when the provider configurationblock is given to a provider, such as AWS security credentials.

• Resource Meta-Node - Represents a group of resources, butdoes not represent any action on its own. This is done forconvenience on dependencies and making a prettier graph. Thisnode is only present for resources that have acountparameter greater than 1.

When visualizing a configuration withterraform graph, you cansee all of these nodes present.

Building the Graph

Building the graph is done in a series of sequential steps:

1. Resources nodes are added based on the configuration. If adiff (plan) or state is present, that meta-data is attachedto each resource node.

2. Resources are mapped to provisioners if they have anydefined. This must be done after all resource nodes arecreated so resources with the same provisioner type canshare the provisioner implementation.

3. Explicit dependencies from thedepends_on meta-parameterare used to create edges between resources.

4. If a state is present, any "orphan" resources are added tothe graph. Orphan resources are any resources that are nolonger present in the configuration but are present in thestate file. Orphans never have any configuration associatedwith them, since the state file does not store configuration.

5. Resources are mapped to providers. Provider configurationnodes are created for these providers, and edges are createdsuch that the resources depend on their respective providerbeing configured.

6. Interpolations are parsed in resource and provider configurationsto determine dependencies. References to resource attributesare turned into dependencies from the resource with the interpolationto the resource being referenced.

7. Create a root node. The root node points to all resources andis created so there is a single root to the dependency graph. Whentraversing the graph, the root node is ignored.

8. If a diff is present, traverse all resource nodes and find resourcesthat are being destroyed. These resource nodes are split into two:one node that destroys the resource and another that createsthe resource (if it is being recreated). The reason the nodes mustbe split is because the destroy order is often different from thecreate order, and so they can't be represented by a single graphnode.

9. Validate the graph has no cycles and has a single root.

Walking the Graph

To walk the graph, a standard depth-first traversal is done. Graphwalking is done in parallel: a node is walked as soon as all of itsdependencies are walked.

The amount of parallelism is limited using a semaphore to prevent too manyconcurrent operations from overwhelming the resources of the machine runningTerraform. By default, up to 10 nodes in the graph will be processedconcurrently. This number can be set using the-parallelism flag on theplan,apply, anddestroy commands.

Setting-parallelism is considered an advanced operation and should not benecessary for normal usage of Terraform. It may be helpful in certain specialuse cases or to help debug Terraform issues.

Note that some providers (AWS, for example), handle API rate limiting issues ata lower level by implementing graceful backoff/retry in their respective APIclients. For this reason, Terraform does not use thisparallelism feature toaddress API rate limits directly.