github.com/hugorut/terraform@v1.1.3/website/docs/internals/graph.mdx (about)

     1  ---
     2  page_title: Resource Graph
     3  description: >-
     4    Terraform builds a dependency graph from the Terraform configurations, and
     5    walks this graph to generate plans, refresh state, and more. This page
     6    documents the details of what are contained in this graph, what types of nodes
     7    there are, and how the edges of the graph are determined.
     8  ---
     9  
    10  # Resource Graph
    11  
    12  Terraform builds a
    13  [dependency graph](https://en.wikipedia.org/wiki/Dependency_graph)
    14  from the Terraform configurations, and walks this graph to
    15  generate plans, refresh state, and more. This page documents
    16  the details of what are contained in this graph, what types
    17  of nodes there are, and how the edges of the graph are determined.
    18  
    19  ~> **Advanced Topic!** This page covers technical details
    20  of Terraform. You don't need to understand these details to
    21  effectively use Terraform. The details are documented here for
    22  those who wish to learn about them without having to go
    23  spelunking through the source code.
    24  
    25  For some background on graph theory, and a summary of how
    26  Terraform applies it, see the HashiCorp 2016 presentation
    27  [_Applying Graph Theory to Infrastructure as Code_](https://www.youtube.com/watch?v=Ce3RNfRbdZ0).
    28  This presentation also covers some similar ideas to the following
    29  guide.
    30  
    31  ## Graph Nodes
    32  
    33  There are only a handful of node types that can exist within the
    34  graph. We'll cover these first before explaining how they're
    35  determined and built:
    36  
    37  - **Resource Node** - Represents a single resource. If you have
    38    the `count` metaparameter set, then there will be one resource
    39    node for each count. The configuration, diff, state, etc. of
    40    the resource under change is attached to this node.
    41  
    42  - **Provider Configuration Node** - Represents the time to fully
    43    configure a provider. This is when the provider configuration
    44    block is given to a provider, such as AWS security credentials.
    45  
    46  - **Resource Meta-Node** - Represents a group of resources, but
    47    does not represent any action on its own. This is done for
    48    convenience on dependencies and making a prettier graph. This
    49    node is only present for resources that have a `count`
    50    parameter greater than 1.
    51  
    52  When visualizing a configuration with `terraform graph`, you can
    53  see all of these nodes present.
    54  
    55  ## Building the Graph
    56  
    57  Building the graph is done in a series of sequential steps:
    58  
    59  1. Resources nodes are added based on the configuration. If a
    60     diff (plan) or state is present, that meta-data is attached
    61     to each resource node.
    62  
    63  1. Resources are mapped to provisioners if they have any
    64     defined. This must be done after all resource nodes are
    65     created so resources with the same provisioner type can
    66     share the provisioner implementation.
    67  
    68  1. Explicit dependencies from the `depends_on` meta-parameter
    69     are used to create edges between resources.
    70  
    71  1. If a state is present, any "orphan" resources are added to
    72     the graph. Orphan resources are any resources that are no
    73     longer present in the configuration but are present in the
    74     state file. Orphans never have any configuration associated
    75     with them, since the state file does not store configuration.
    76  
    77  1. Resources are mapped to providers. Provider configuration
    78     nodes are created for these providers, and edges are created
    79     such that the resources depend on their respective provider
    80     being configured.
    81  
    82  1. Interpolations are parsed in resource and provider configurations
    83     to determine dependencies. References to resource attributes
    84     are turned into dependencies from the resource with the interpolation
    85     to the resource being referenced.
    86  
    87  1. Create a root node. The root node points to all resources and
    88     is created so there is a single root to the dependency graph. When
    89     traversing the graph, the root node is ignored.
    90  
    91  1. If a diff is present, traverse all resource nodes and find resources
    92     that are being destroyed. These resource nodes are split into two:
    93     one node that destroys the resource and another that creates
    94     the resource (if it is being recreated). The reason the nodes must
    95     be split is because the destroy order is often different from the
    96     create order, and so they can't be represented by a single graph
    97     node.
    98  
    99  1. Validate the graph has no cycles and has a single root.
   100  
   101  ## Walking the Graph
   102  
   103  <a id="walking-the-graph"></a>
   104  
   105  To walk the graph, a standard depth-first traversal is done. Graph
   106  walking is done in parallel: a node is walked as soon as all of its
   107  dependencies are walked.
   108  
   109  The amount of parallelism is limited using a semaphore to prevent too many
   110  concurrent operations from overwhelming the resources of the machine running
   111  Terraform. By default, up to 10 nodes in the graph will be processed
   112  concurrently. This number can be set using the `-parallelism` flag on the
   113  [plan](/cli/commands/plan), [apply](/cli/commands/apply), and
   114  [destroy](/cli/commands/destroy) commands.
   115  
   116  Setting `-parallelism` is considered an advanced operation and should not be
   117  necessary for normal usage of Terraform. It may be helpful in certain special
   118  use cases or to help debug Terraform issues.
   119  
   120  Note that some providers (AWS, for example), handle API rate limiting issues at
   121  a lower level by implementing graceful backoff/retry in their respective API
   122  clients. For this reason, Terraform does not use this `parallelism` feature to
   123  address API rate limits directly.