github.com/armen/terraform@v0.5.2-0.20150529052519-caa8117a08f1/website/source/docs/internals/graph.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Resource Graph"
     4  sidebar_current: "docs-internals-graph"
     5  description: |-
     6    Terraform builds a dependency graph from the Terraform configurations, and walks this graph to generate plans, refresh state, and more. This page documents the details of what are contained in this graph, what types of nodes there are, and how the edges of the graph are determined.
     7  ---
     8  
     9  # Resource Graph
    10  
    11  Terraform builds a
    12  [dependency graph](http://en.wikipedia.org/wiki/Dependency_graph)
    13  from the Terraform configurations, and walks this graph to
    14  generate plans, refresh state, and more. This page documents
    15  the details of what are contained in this graph, what types
    16  of nodes there are, and how the edges of the graph are determined.
    17  
    18  ~> **Advanced Topic!** This page covers technical details
    19  of Terraform. You don't need to understand these details to
    20  effectively use Terraform. The details are documented here for
    21  those who wish to learn about them without having to go
    22  spelunking through the source code.
    23  
    24  ## Graph Nodes
    25  
    26  There are only a handful of node types that can exist within the
    27  graph. We'll cover these first before explaining how they're
    28  determined and built:
    29  
    30    * **Resource Node** - Represents a single resource. If you have
    31      the `count` metaparameter set, then there will be one resource
    32      node for each count. The configuration, diff, state, etc. of
    33      the resource under change is attached to this node.
    34  
    35    * **Provider Configuration Node** - Represents the time to fully
    36      configure a provider. This is when the provider configuration
    37      block is given to a provider, such as AWS security credentials.
    38  
    39    * **Resource Meta-Node** - Represents a group of resources, but
    40      does not represent any action on its own. This is done for
    41      convenience on dependencies and making a prettier graph. This
    42      node is only present for resources that have a `count`
    43      parameter greater than 1.
    44  
    45  When visualizing a configuration with `terraform graph`, you can
    46  see all of these nodes present.
    47  
    48  ## Building the Graph
    49  
    50  Building the graph is done in a series of sequential steps:
    51  
    52    1. Resources nodes are added based on the configuration. If a
    53       diff (plan) or state is present, that meta-data is attached
    54       to each resource node.
    55  
    56    1. Resources are mapped to provisioners if they have any
    57       defined. This must be done after all resource nodes are
    58       created so resources with the same provisioner type can
    59       share the provisioner implementation.
    60  
    61    1. Explicit dependencies from the `depends_on` meta-parameter
    62       are used to create edges between resources.
    63  
    64    1. If a state is present, any "orphan" resources are added to
    65       the graph. Orphan resources are any resources that are no
    66       longer present in the configuration but are present in the
    67       state file. Orphans never have any configuration associated
    68       with them, since the state file does not store configuration.
    69  
    70    1. Resources are mapped to providers. Provider configuration
    71       nodes are created for these providers, and edges are created
    72       such that the resources depend on their respective provider
    73       being configured.
    74  
    75    1. Interpolations are parsed in resource and provider configurations
    76       to determine dependencies. References to resource attributes
    77       are turned into dependencies from the resource with the interpolation
    78       to the resource being referenced.
    79  
    80    1. Create a root node. The root node points to all resources and
    81       is created so there is a single root to the dependency graph. When
    82       traversing the graph, the root node is ignored.
    83  
    84    1. If a diff is present, traverse all resource nodes and find resources
    85       that are being destroyed. These resource nodes are split into two:
    86       one node that destroys the resource and another that creates
    87       the resource (if it is being recreated). The reason the nodes must
    88       be split is because the destroy order is often different from the
    89       create order, and so they can't be represented by a single graph
    90       node.
    91  
    92    1. Validate the graph has no cycles and has a single root.
    93  
    94  ## Walking the Graph
    95  
    96  To walk the graph, a standard depth-first traversal is done. Graph
    97  walking is done with as much parallelism as possible: a node is walked
    98  as soon as all of its dependencies are walked.