core: graph command gets -verbose and -draw-cycles

When you specify `-verbose` you'll get the whole graph of operations,
which gives a better idea of the operations terraform performs and in
what order.

The DOT graph is now generated with a small internal library instead of
simple string building. This allows us to ensure the graph generation is
as consistent as possible, among other benefits.

We set `newrank = true` in the graph, which I've found does just as good
a job organizing things visually as manually attempting to rank the nodes
based on depth.

This also fixes `-module-depth`, which was broken post-AST refector.
Modules are now expanded into subgraphs with labels and borders. We
have yet to regain the plan graphing functionality, so I removed that
from the docs for now.

Finally, if `-draw-cycles` is added, extra colored edges will be drawn
to indicate the path of any cycles detected in the graph.

A notable implementation change included here is that
{Reverse,}DepthFirstWalk has been made deterministic. (Before it was
dependent on `map` ordering.) This turned out to be unnecessary to gain
determinism in the final DOT-level implementation, but it seemed
a desirable enough of a property that I left it in.

command/graph.go

@@ -17,11 +17,15 @@ type GraphCommand struct {
 
 func (c *GraphCommand) Run(args []string) int {
 	var moduleDepth int
+	var verbose bool
+	var drawCycles bool
 
 	args = c.Meta.process(args, false)
 
 	cmdFlags := flag.NewFlagSet("graph", flag.ContinueOnError)
 	cmdFlags.IntVar(&moduleDepth, "module-depth", 0, "module-depth")
+	cmdFlags.BoolVar(&verbose, "verbose", false, "verbose")
+	cmdFlags.BoolVar(&drawCycles, "draw-cycles", false, "draw-cycles")
 	cmdFlags.Usage = func() { c.Ui.Error(c.Help()) }
 	if err := cmdFlags.Parse(args); err != nil {
 		return 1
@@ -52,28 +56,38 @@ func (c *GraphCommand) Run(args []string) int {
 		return 1
 	}
 
+	// Skip validation during graph generation - we want to see the graph even if
+	// it is invalid for some reason.
 	g, err := ctx.Graph(&terraform.ContextGraphOpts{
-		Validate: true,
-		Verbose:  false,
+		Verbose:  verbose,
+		Validate: false,
 	})
 	if err != nil {
 		c.Ui.Error(fmt.Sprintf("Error creating graph: %s", err))
 		return 1
 	}
 
-	c.Ui.Output(terraform.GraphDot(g, nil))
+	graphStr, err := terraform.GraphDot(g, &terraform.GraphDotOpts{
+		DrawCycles: drawCycles,
+		MaxDepth:   moduleDepth,
+		Verbose:    verbose,
+	})
+	if err != nil {
+		c.Ui.Error(fmt.Sprintf("Error converting graph: %s", err))
+		return 1
+	}
+
+	c.Ui.Output(graphStr)
 
 	return 0
 }
 
 func (c *GraphCommand) Help() string {
 	helpText := `
-Usage: terraform graph [options] PATH
+Usage: terraform graph [options] [DIR]
 
-  Outputs the visual graph of Terraform resources. If the path given is
-  the path to a configuration, the dependency graph of the resources are
-  shown. If the path is a plan file, then the dependency graph of the
-  plan itself is shown.
+  Outputs the visual dependency graph of Terraform resources according to
+  configuration files in DIR (or the current directory if omitted).
 
   The graph is outputted in DOT format. The typical program that can
   read this format is GraphViz, but many web services are also available
@@ -81,9 +95,14 @@ Usage: terraform graph [options] PATH
 
 Options:
 
+  -draw-cycles         Highlight any cycles in the graph with colored edges.
+                       This helps when diagnosing cycle errors.
+
   -module-depth=n      The maximum depth to expand modules. By default this is
                        zero, which will not expand modules at all.
 
+  -verbose             Generate a verbose, "worst-case" graph, with all nodes
+                       for potential operations in place.
 `
 	return strings.TrimSpace(helpText)
 }

dag/dag.go

@@ -2,6 +2,7 @@ package dag
 
 import (
 	"fmt"
+	"sort"
 	"strings"
 	"sync"
 
@@ -17,17 +18,21 @@ type AcyclicGraph struct {
 // WalkFunc is the callback used for walking the graph.
 type WalkFunc func(Vertex) error
 
+// DepthWalkFunc is a walk function that also receives the current depth of the
+// walk as an argument
+type DepthWalkFunc func(Vertex, int) error
+
 // Returns a Set that includes every Vertex yielded by walking down from the
 // provided starting Vertex v.
 func (g *AcyclicGraph) Ancestors(v Vertex) (*Set, error) {
 	s := new(Set)
-	start := asVertexList(g.DownEdges(v))
-	memoFunc := func(v Vertex) error {
+	start := AsVertexList(g.DownEdges(v))
+	memoFunc := func(v Vertex, d int) error {
 		s.Add(v)
 		return nil
 	}
 
-	if err := g.depthFirstWalk(start, memoFunc); err != nil {
+	if err := g.DepthFirstWalk(start, memoFunc); err != nil {
 		return nil, err
 	}
 
@@ -38,13 +43,13 @@ func (g *AcyclicGraph) Ancestors(v Vertex) (*Set, error) {
 // provided starting Vertex v.
 func (g *AcyclicGraph) Descendents(v Vertex) (*Set, error) {
 	s := new(Set)
-	start := asVertexList(g.UpEdges(v))
-	memoFunc := func(v Vertex) error {
+	start := AsVertexList(g.UpEdges(v))
+	memoFunc := func(v Vertex, d int) error {
 		s.Add(v)
 		return nil
 	}
 
-	if err := g.reverseDepthFirstWalk(start, memoFunc); err != nil {
+	if err := g.ReverseDepthFirstWalk(start, memoFunc); err != nil {
 		return nil, err
 	}
 
@@ -92,14 +97,13 @@ func (g *AcyclicGraph) TransitiveReduction() {
 	// v such that the edge (u,v) exists (v is a direct descendant of u).
 	//
 	// For each v-prime reachable from v, remove the edge (u, v-prime).
-
 	for _, u := range g.Vertices() {
 		uTargets := g.DownEdges(u)
-		vs := asVertexList(g.DownEdges(u))
+		vs := AsVertexList(g.DownEdges(u))
 
-		g.depthFirstWalk(vs, func(v Vertex) error {
+		g.DepthFirstWalk(vs, func(v Vertex, d int) error {
 			shared := uTargets.Intersection(g.DownEdges(v))
-			for _, vPrime := range asVertexList(shared) {
+			for _, vPrime := range AsVertexList(shared) {
 				g.RemoveEdge(BasicEdge(u, vPrime))
 			}
 
@@ -117,12 +121,7 @@ func (g *AcyclicGraph) Validate() error {
 
 	// Look for cycles of more than 1 component
 	var err error
-	var cycles [][]Vertex
-	for _, cycle := range StronglyConnected(&g.Graph) {
-		if len(cycle) > 1 {
-			cycles = append(cycles, cycle)
-		}
-	}
+	cycles := g.Cycles()
 	if len(cycles) > 0 {
 		for _, cycle := range cycles {
 			cycleStr := make([]string, len(cycle))
@@ -146,6 +145,16 @@ func (g *AcyclicGraph) Validate() error {
 	return err
 }
 
+func (g *AcyclicGraph) Cycles() [][]Vertex {
+	var cycles [][]Vertex
+	for _, cycle := range StronglyConnected(&g.Graph) {
+		if len(cycle) > 1 {
+			cycles = append(cycles, cycle)
+		}
+	}
+	return cycles
+}
+
 // Walk walks the graph, calling your callback as each node is visited.
 // This will walk nodes in parallel if it can. Because the walk is done
 // in parallel, the error returned will be a multierror.
@@ -175,7 +184,7 @@ func (g *AcyclicGraph) Walk(cb WalkFunc) error {
 	for _, v := range vertices {
 		// Build our list of dependencies and the list of channels to
 		// wait on until we start executing for this vertex.
-		deps := asVertexList(g.DownEdges(v))
+		deps := AsVertexList(g.DownEdges(v))
 		depChs := make([]<-chan struct{}, len(deps))
 		for i, dep := range deps {
 			depChs[i] = vertMap[dep]
@@ -229,7 +238,7 @@ func (g *AcyclicGraph) Walk(cb WalkFunc) error {
 }
 
 // simple convenience helper for converting a dag.Set to a []Vertex
-func asVertexList(s *Set) []Vertex {
+func AsVertexList(s *Set) []Vertex {
 	rawList := s.List()
 	vertexList := make([]Vertex, len(rawList))
 	for i, raw := range rawList {
@@ -238,13 +247,23 @@ func asVertexList(s *Set) []Vertex {
 	return vertexList
 }
 
+type vertexAtDepth struct {
+	Vertex Vertex
+	Depth  int
+}
+
 // depthFirstWalk does a depth-first walk of the graph starting from
 // the vertices in start. This is not exported now but it would make sense
 // to export this publicly at some point.
-func (g *AcyclicGraph) depthFirstWalk(start []Vertex, cb WalkFunc) error {
+func (g *AcyclicGraph) DepthFirstWalk(start []Vertex, f DepthWalkFunc) error {
 	seen := make(map[Vertex]struct{})
-	frontier := make([]Vertex, len(start))
-	copy(frontier, start)
+	frontier := make([]*vertexAtDepth, len(start))
+	for i, v := range start {
+		frontier[i] = &vertexAtDepth{
+			Vertex: v,
+			Depth:  0,
+		}
+	}
 	for len(frontier) > 0 {
 		// Pop the current vertex
 		n := len(frontier)
@@ -252,20 +271,24 @@ func (g *AcyclicGraph) depthFirstWalk(start []Vertex, cb WalkFunc) error {
 		frontier = frontier[:n-1]
 
 		// Check if we've seen this already and return...
-		if _, ok := seen[current]; ok {
+		if _, ok := seen[current.Vertex]; ok {
 			continue
 		}
-		seen[current] = struct{}{}
+		seen[current.Vertex] = struct{}{}
 
 		// Visit the current node
-		if err := cb(current); err != nil {
+		if err := f(current.Vertex, current.Depth); err != nil {
 			return err
 		}
 
-		// Visit targets of this in reverse order.
-		targets := g.DownEdges(current).List()
-		for i := len(targets) - 1; i >= 0; i-- {
-			frontier = append(frontier, targets[i].(Vertex))
+		// Visit targets of this in a consistent order.
+		targets := AsVertexList(g.DownEdges(current.Vertex))
+		sort.Sort(byVertexName(targets))
+		for _, t := range targets {
+			frontier = append(frontier, &vertexAtDepth{
+				Vertex: t,
+				Depth:  current.Depth + 1,
+			})
 		}
 	}
 
@@ -274,10 +297,15 @@ func (g *AcyclicGraph) depthFirstWalk(start []Vertex, cb WalkFunc) error {
 
 // reverseDepthFirstWalk does a depth-first walk _up_ the graph starting from
 // the vertices in start.
-func (g *AcyclicGraph) reverseDepthFirstWalk(start []Vertex, cb WalkFunc) error {
+func (g *AcyclicGraph) ReverseDepthFirstWalk(start []Vertex, f DepthWalkFunc) error {
 	seen := make(map[Vertex]struct{})
-	frontier := make([]Vertex, len(start))
-	copy(frontier, start)
+	frontier := make([]*vertexAtDepth, len(start))
+	for i, v := range start {
+		frontier[i] = &vertexAtDepth{
+			Vertex: v,
+			Depth:  0,
+		}
+	}
 	for len(frontier) > 0 {
 		// Pop the current vertex
 		n := len(frontier)
@@ -285,22 +313,36 @@ func (g *AcyclicGraph) reverseDepthFirstWalk(start []Vertex, cb WalkFunc) error
 		frontier = frontier[:n-1]
 
 		// Check if we've seen this already and return...
-		if _, ok := seen[current]; ok {
+		if _, ok := seen[current.Vertex]; ok {
 			continue
 		}
-		seen[current] = struct{}{}
+		seen[current.Vertex] = struct{}{}
 
 		// Visit the current node
-		if err := cb(current); err != nil {
+		if err := f(current.Vertex, current.Depth); err != nil {
 			return err
 		}
 
-		// Visit targets of this in reverse order.
-		targets := g.UpEdges(current).List()
-		for i := len(targets) - 1; i >= 0; i-- {
-			frontier = append(frontier, targets[i].(Vertex))
+		// Visit targets of this in a consistent order.
+		targets := AsVertexList(g.UpEdges(current.Vertex))
+		sort.Sort(byVertexName(targets))
+		for _, t := range targets {
+			frontier = append(frontier, &vertexAtDepth{
+				Vertex: t,
+				Depth:  current.Depth + 1,
+			})
 		}
 	}
 
 	return nil
 }
+
+// byVertexName implements sort.Interface so a list of Vertices can be sorted
+// consistently by their VertexName
+type byVertexName []Vertex
+
+func (b byVertexName) Len() int      { return len(b) }
+func (b byVertexName) Swap(i, j int) { b[i], b[j] = b[j], b[i] }
+func (b byVertexName) Less(i, j int) bool {
+	return VertexName(b[i]) < VertexName(b[j])
+}

dot/graph.go

@@ -0,0 +1,224 @@
+// The dot package contains utilities for working with DOT graphs.
+package dot
+
+import (
+	"bytes"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// Graph is a representation of a drawable DOT graph.
+type Graph struct {
+	// Whether this is a "digraph" or just a "graph"
+	Directed bool
+
+	// Used for K/V settings in the DOT
+	Attrs map[string]string
+
+	Nodes     []*Node
+	Edges     []*Edge
+	Subgraphs []*Subgraph
+
+	nodesByName map[string]*Node
+}
+
+// Subgraph is a Graph that lives inside a Parent graph, and contains some
+// additional parameters to control how it is drawn.
+type Subgraph struct {
+	Graph
+	Name    string
+	Parent  *Graph
+	Cluster bool
+}
+
+// An Edge in a DOT graph, as expressed by recording the Name of the Node at
+// each end.
+type Edge struct {
+	// Name of source node.
+	Source string
+
+	// Name of dest node.
+	Dest string
+
+	// List of K/V attributes for this edge.
+	Attrs map[string]string
+}
+
+// A Node in a DOT graph.
+type Node struct {
+	Name  string
+	Attrs map[string]string
+}
+
+// Creates a properly initialized DOT Graph.
+func NewGraph(attrs map[string]string) *Graph {
+	return &Graph{
+		Attrs:       attrs,
+		nodesByName: make(map[string]*Node),
+	}
+}
+
+func NewEdge(src, dst string, attrs map[string]string) *Edge {
+	return &Edge{
+		Source: src,
+		Dest:   dst,
+		Attrs:  attrs,
+	}
+}
+
+func NewNode(n string, attrs map[string]string) *Node {
+	return &Node{
+		Name:  n,
+		Attrs: attrs,
+	}
+}
+
+// Initializes a Subgraph with the provided name, attaches is to this Graph,
+// and returns it.
+func (g *Graph) AddSubgraph(name string) *Subgraph {
+	subgraph := &Subgraph{
+		Graph:  *NewGraph(map[string]string{}),
+		Parent: g,
+		Name:   name,
+	}
+	g.Subgraphs = append(g.Subgraphs, subgraph)
+	return subgraph
+}
+
+func (g *Graph) AddAttr(k, v string) {
+	g.Attrs[k] = v
+}
+
+func (g *Graph) AddNode(n *Node) {
+	g.Nodes = append(g.Nodes, n)
+	g.nodesByName[n.Name] = n
+}
+
+func (g *Graph) AddEdge(e *Edge) {
+	g.Edges = append(g.Edges, e)
+}
+
+// Adds an edge between two Nodes.
+//
+// Note this does not do any verification of the existence of these nodes,
+// which means that any strings you provide that are not existing nodes will
+// result in extra auto-defined nodes in your resulting DOT.
+func (g *Graph) AddEdgeBetween(src, dst string, attrs map[string]string) error {
+	g.AddEdge(NewEdge(src, dst, attrs))
+
+	return nil
+}
+
+// Look up a node by name
+func (g *Graph) GetNode(name string) (*Node, error) {
+	node, ok := g.nodesByName[name]
+	if !ok {
+		return nil, fmt.Errorf("Could not find node: %s", name)
+	}
+	return node, nil
+}
+
+// Returns the DOT representation of this Graph.
+func (g *Graph) String() string {
+	w := newGraphWriter()
+
+	g.drawHeader(w)
+	w.Indent()
+	g.drawBody(w)
+	w.Unindent()
+	g.drawFooter(w)
+
+	return w.String()
+}
+
+func (g *Graph) drawHeader(w *graphWriter) {
+	if g.Directed {
+		w.Printf("digraph {\n")
+	} else {
+		w.Printf("graph {\n")
+	}
+}
+
+func (g *Graph) drawBody(w *graphWriter) {
+	for _, as := range attrStrings(g.Attrs) {
+		w.Printf("%s\n", as)
+	}
+
+	nodeStrings := make([]string, 0, len(g.Nodes))
+	for _, n := range g.Nodes {
+		nodeStrings = append(nodeStrings, n.String())
+	}
+	sort.Strings(nodeStrings)
+	for _, ns := range nodeStrings {
+		w.Printf(ns)
+	}
+
+	edgeStrings := make([]string, 0, len(g.Edges))
+	for _, e := range g.Edges {
+		edgeStrings = append(edgeStrings, e.String())
+	}
+	sort.Strings(edgeStrings)
+	for _, es := range edgeStrings {
+		w.Printf(es)
+	}
+
+	for _, s := range g.Subgraphs {
+		s.drawHeader(w)
+		w.Indent()
+		s.drawBody(w)
+		w.Unindent()
+		s.drawFooter(w)
+	}
+}
+
+func (g *Graph) drawFooter(w *graphWriter) {
+	w.Printf("}\n")
+}
+
+// Returns the DOT representation of this Edge.
+func (e *Edge) String() string {
+	var buf bytes.Buffer
+	buf.WriteString(
+		fmt.Sprintf(
+			"%q -> %q", e.Source, e.Dest))
+	writeAttrs(&buf, e.Attrs)
+	buf.WriteString("\n")
+
+	return buf.String()
+}
+
+func (s *Subgraph) drawHeader(w *graphWriter) {
+	name := s.Name
+	if s.Cluster {
+		name = fmt.Sprintf("cluster_%s", name)
+	}
+	w.Printf("subgraph %q {\n", name)
+}
+
+// Returns the DOT representation of this Node.
+func (n *Node) String() string {
+	var buf bytes.Buffer
+	buf.WriteString(fmt.Sprintf("%q", n.Name))
+	writeAttrs(&buf, n.Attrs)
+	buf.WriteString("\n")
+
+	return buf.String()
+}
+
+func writeAttrs(buf *bytes.Buffer, attrs map[string]string) {
+	if len(attrs) > 0 {
+		buf.WriteString(" [")
+		buf.WriteString(strings.Join(attrStrings(attrs), ", "))
+		buf.WriteString("]")
+	}
+}
+
+func attrStrings(attrs map[string]string) []string {
+	strings := make([]string, 0, len(attrs))
+	for k, v := range attrs {
+		strings = append(strings, fmt.Sprintf("%s = %q", k, v))
+	}
+	sort.Strings(strings)
+	return strings
+}

dot/graph_writer.go

@@ -0,0 +1,47 @@
+package dot
+
+import (
+	"bytes"
+	"fmt"
+)
+
+// graphWriter wraps a bytes.Buffer and tracks indent level levels.
+type graphWriter struct {
+	bytes.Buffer
+	indent    int
+	indentStr string
+}
+
+// Returns an initialized graphWriter at indent level 0.
+func newGraphWriter() *graphWriter {
+	w := &graphWriter{
+		indent: 0,
+	}
+	w.init()
+	return w
+}
+
+// Prints to the buffer at the current indent level.
+func (w *graphWriter) Printf(s string, args ...interface{}) {
+	w.WriteString(w.indentStr + fmt.Sprintf(s, args...))
+}
+
+// Increase the indent level.
+func (w *graphWriter) Indent() {
+	w.indent++
+	w.init()
+}
+
+// Decrease the indent level.
+func (w *graphWriter) Unindent() {
+	w.indent--
+	w.init()
+}
+
+func (w *graphWriter) init() {
+	indentBuf := new(bytes.Buffer)
+	for i := 0; i < w.indent; i++ {
+		indentBuf.WriteString("\t")
+	}
+	w.indentStr = indentBuf.String()
+}

terraform/graph_config_node.go

@@ -7,6 +7,7 @@ import (
 	"github.com/hashicorp/terraform/config"
 	"github.com/hashicorp/terraform/config/module"
 	"github.com/hashicorp/terraform/dag"
+	"github.com/hashicorp/terraform/dot"
 )
 
 // graphNodeConfig is an interface that all graph nodes for the
@@ -219,14 +220,16 @@ func (n *GraphNodeConfigProvider) ProviderConfig() *config.RawConfig {
 }
 
 // GraphNodeDotter impl.
-func (n *GraphNodeConfigProvider) Dot(name string) string {
-	return fmt.Sprintf(
-		"\"%s\" [\n"+
-			"\tlabel=\"%s\"\n"+
-			"\tshape=diamond\n"+
-			"];",
-		name,
-		n.Name())
+func (n *GraphNodeConfigProvider) DotNode(name string, opts *GraphDotOpts) *dot.Node {
+	return dot.NewNode(name, map[string]string{
+		"label": n.Name(),
+		"shape": "diamond",
+	})
+}
+
+// GraphNodeDotterOrigin impl.
+func (n *GraphNodeConfigProvider) DotOrigin() bool {
+	return true
 }
 
 // GraphNodeConfigResource represents a resource within the config graph.
@@ -318,18 +321,14 @@ func (n *GraphNodeConfigResource) Name() string {
 }
 
 // GraphNodeDotter impl.
-func (n *GraphNodeConfigResource) Dot(name string) string {
-	if n.DestroyMode != DestroyNone {
-		return ""
+func (n *GraphNodeConfigResource) DotNode(name string, opts *GraphDotOpts) *dot.Node {
+	if n.DestroyMode != DestroyNone && !opts.Verbose {
+		return nil
 	}
-
-	return fmt.Sprintf(
-		"\"%s\" [\n"+
-			"\tlabel=\"%s\"\n"+
-			"\tshape=box\n"+
-			"];",
-		name,
-		n.Name())
+	return dot.NewNode(name, map[string]string{
+		"label": n.Name(),
+		"shape": "box",
+	})
 }
 
 // GraphNodeDynamicExpandable impl.
@@ -635,14 +634,11 @@ func (n *graphNodeModuleExpanded) ConfigType() GraphNodeConfigType {
 }
 
 // GraphNodeDotter impl.
-func (n *graphNodeModuleExpanded) Dot(name string) string {
-	return fmt.Sprintf(
-		"\"%s\" [\n"+
-			"\tlabel=\"%s\"\n"+
-			"\tshape=component\n"+
-			"];",
-		name,
-		dag.VertexName(n.Original))
+func (n *graphNodeModuleExpanded) DotNode(name string, opts *GraphDotOpts) *dot.Node {
+	return dot.NewNode(name, map[string]string{
+		"label": dag.VertexName(n.Original),
+		"shape": "component",
+	})
 }
 
 // GraphNodeEvalable impl.

terraform/graph_dot.go

@@ -1,12 +1,10 @@
 package terraform
 
 import (
-	"bufio"
-	"bytes"
 	"fmt"
-	"strings"
 
 	"github.com/hashicorp/terraform/dag"
+	"github.com/hashicorp/terraform/dot"
 )
 
 // GraphNodeDotter can be implemented by a node to cause it to be included
@@ -14,58 +12,174 @@ import (
 // return a representation of this node.
 type GraphNodeDotter interface {
 	// Dot is called to return the dot formatting for the node.
-	// The parameter must be the title of the node.
-	Dot(string) string
+	// The first parameter is the title of the node.
+	// The second parameter includes user-specified options that affect the dot
+	// graph. See GraphDotOpts below for details.
+	DotNode(string, *GraphDotOpts) *dot.Node
+}
+
+type GraphNodeDotOrigin interface {
+	DotOrigin() bool
 }
 
 // GraphDotOpts are the options for generating a dot formatted Graph.
-type GraphDotOpts struct{}
+type GraphDotOpts struct {
+	// Allows some nodes to decide to only show themselves when the user has
+	// requested the "verbose" graph.
+	Verbose bool
+
+	// Highlight Cycles
+	DrawCycles bool
+
+	// How many levels to expand modules as we draw
+	MaxDepth int
+}
 
 // GraphDot returns the dot formatting of a visual representation of
 // the given Terraform graph.
-func GraphDot(g *Graph, opts *GraphDotOpts) string {
-	buf := new(bytes.Buffer)
+func GraphDot(g *Graph, opts *GraphDotOpts) (string, error) {
+	dg := dot.NewGraph(map[string]string{
+		"compound": "true",
+		"newrank":  "true",
+	})
+	dg.Directed = true
 
-	// Start the graph
-	buf.WriteString("digraph {\n")
-	buf.WriteString("\tcompound = true;\n")
-
-	// Go through all the vertices and draw it
-	vertices := g.Vertices()
-	dotVertices := make(map[dag.Vertex]struct{}, len(vertices))
-	for _, v := range vertices {
-		if dn, ok := v.(GraphNodeDotter); !ok {
-			continue
-		} else if dn.Dot("fake") == "" {
-			continue
-		}
-
-		dotVertices[v] = struct{}{}
+	err := graphDotSubgraph(dg, "root", g, opts, 0)
+	if err != nil {
+		return "", err
 	}
 
-	for v, _ := range dotVertices {
-		dn := v.(GraphNodeDotter)
-		scanner := bufio.NewScanner(strings.NewReader(
-			dn.Dot(dag.VertexName(v))))
-		for scanner.Scan() {
-			buf.WriteString("\t" + scanner.Text() + "\n")
+	return dg.String(), nil
+}
+
+func graphDotSubgraph(
+	dg *dot.Graph, modName string, g *Graph, opts *GraphDotOpts, modDepth int) error {
+	// Respect user-specified module depth
+	if opts.MaxDepth >= 0 && modDepth > opts.MaxDepth {
+		return nil
+	}
+
+	// Begin module subgraph
+	var sg *dot.Subgraph
+	if modDepth == 0 {
+		sg = dg.AddSubgraph(modName)
+	} else {
+		sg = dg.AddSubgraph(modName)
+		sg.Cluster = true
+		sg.AddAttr("label", modName)
+	}
+
+	origins, err := graphDotFindOrigins(g)
+	if err != nil {
+		return err
+	}
+
+	drawableVertices := make(map[dag.Vertex]struct{})
+	toDraw := make([]dag.Vertex, 0, len(g.Vertices()))
+	subgraphVertices := make(map[dag.Vertex]*Graph)
+
+	walk := func(v dag.Vertex, depth int) error {
+		// We only care about nodes that yield non-empty Dot strings.
+		if dn, ok := v.(GraphNodeDotter); !ok {
+			return nil
+		} else if dn.DotNode("fake", opts) == nil {
+			return nil
 		}
 
-		// Draw all the edges
-		for _, t := range g.DownEdges(v).List() {
+		drawableVertices[v] = struct{}{}
+		toDraw = append(toDraw, v)
+
+		if sn, ok := v.(GraphNodeSubgraph); ok {
+			subgraphVertices[v] = sn.Subgraph()
+		}
+		return nil
+	}
+
+	if err := g.ReverseDepthFirstWalk(origins, walk); err != nil {
+		return err
+	}
+
+	for _, v := range toDraw {
+		dn := v.(GraphNodeDotter)
+		nodeName := graphDotNodeName(modName, v)
+		sg.AddNode(dn.DotNode(nodeName, opts))
+
+		// Draw all the edges from this vertex to other nodes
+		targets := dag.AsVertexList(g.DownEdges(v))
+		for _, t := range targets {
 			target := t.(dag.Vertex)
-			if _, ok := dotVertices[target]; !ok {
+			// Only want edges where both sides are drawable.
+			if _, ok := drawableVertices[target]; !ok {
 				continue
 			}
 
-			buf.WriteString(fmt.Sprintf(
-				"\t\"%s\" -> \"%s\";\n",
-				dag.VertexName(v),
-				dag.VertexName(target)))
+			if err := sg.AddEdgeBetween(
+				graphDotNodeName(modName, v),
+				graphDotNodeName(modName, target),
+				map[string]string{}); err != nil {
+				return err
+			}
 		}
 	}
 
-	// End the graph
-	buf.WriteString("}\n")
-	return buf.String()
+	// Recurse into any subgraphs
+	for _, v := range toDraw {
+		subgraph, ok := subgraphVertices[v]
+		if !ok {
+			continue
+		}
+
+		err := graphDotSubgraph(dg, dag.VertexName(v), subgraph, opts, modDepth+1)
+		if err != nil {
+			return err
+		}
+	}
+
+	if opts.DrawCycles {
+		colors := []string{"red", "green", "blue"}
+		for ci, cycle := range g.Cycles() {
+			for i, c := range cycle {
+				// Catch the last wrapping edge of the cycle
+				if i+1 >= len(cycle) {
+					i = -1
+				}
+				edgeAttrs := map[string]string{
+					"color":    colors[ci%len(colors)],
+					"penwidth": "2.0",
+				}
+
+				if err := sg.AddEdgeBetween(
+					graphDotNodeName(modName, c),
+					graphDotNodeName(modName, cycle[i+1]),
+					edgeAttrs); err != nil {
+					return err
+				}
+
+			}
+		}
+	}
+
+	return nil
+}
+
+func graphDotNodeName(modName, v dag.Vertex) string {
+	return fmt.Sprintf("[%s] %s", modName, dag.VertexName(v))
+}
+
+func graphDotFindOrigins(g *Graph) ([]dag.Vertex, error) {
+	var origin []dag.Vertex
+
+	for _, v := range g.Vertices() {
+		if dr, ok := v.(GraphNodeDotOrigin); ok {
+			if dr.DotOrigin() {
+				origin = append(origin, v)
+			}
+		}
+	}
+
+	if len(origin) == 0 {
+		return nil, fmt.Errorf("No DOT origin nodes found.\nGraph: %s", g)
+	}
+
+	return origin, nil
 }

terraform/graph_dot_test.go

@@ -0,0 +1,287 @@
+package terraform
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/hashicorp/terraform/dot"
+)
+
+func TestGraphDot(t *testing.T) {
+	cases := map[string]struct {
+		Graph  testGraphFunc
+		Opts   GraphDotOpts
+		Expect string
+		Error  string
+	}{
+		"empty": {
+			Graph: func() *Graph { return &Graph{} },
+			Error: "No DOT origin nodes found",
+		},
+		"three-level": {
+			Graph: func() *Graph {
+				var g Graph
+				root := &testDrawableOrigin{"root"}
+				g.Add(root)
+
+				levelOne := []string{"foo", "bar"}
+				for _, s := range levelOne {
+					g.Add(&testDrawable{
+						VertexName:      s,
+						DependentOnMock: []string{"root"},
+					})
+				}
+
+				levelTwo := []string{"baz", "qux"}
+				for i, s := range levelTwo {
+					g.Add(&testDrawable{
+						VertexName:      s,
+						DependentOnMock: levelOne[i : i+1],
+					})
+				}
+
+				g.ConnectDependents()
+				return &g
+			},
+			Expect: `
+digraph {
+	compound = "true"
+	newrank = "true"
+	subgraph "root" {
+		"[root] bar"
+		"[root] baz"
+		"[root] foo"
+		"[root] qux"
+		"[root] root"
+		"[root] bar" -> "[root] root"
+		"[root] baz" -> "[root] foo"
+		"[root] foo" -> "[root] root"
+		"[root] qux" -> "[root] bar"
+	}
+}
+			`,
+		},
+		"cycle": {
+			Opts: GraphDotOpts{
+				DrawCycles: true,
+			},
+			Graph: func() *Graph {
+				var g Graph
+				root := &testDrawableOrigin{"root"}
+				g.Add(root)
+
+				g.Add(&testDrawable{
+					VertexName:      "A",
+					DependentOnMock: []string{"root", "C"},
+				})
+
+				g.Add(&testDrawable{
+					VertexName:      "B",
+					DependentOnMock: []string{"A"},
+				})
+
+				g.Add(&testDrawable{
+					VertexName:      "C",
+					DependentOnMock: []string{"B"},
+				})
+
+				g.ConnectDependents()
+				return &g
+			},
+			Expect: `
+digraph {
+	compound = "true"
+	newrank = "true"
+	subgraph "root" {
+		"[root] A"
+		"[root] B"
+		"[root] C"
+		"[root] root"
+		"[root] A" -> "[root] B" [color = "red", penwidth = "2.0"]
+		"[root] A" -> "[root] C"
+		"[root] A" -> "[root] root"
+		"[root] B" -> "[root] A"
+		"[root] B" -> "[root] C" [color = "red", penwidth = "2.0"]
+		"[root] C" -> "[root] A" [color = "red", penwidth = "2.0"]
+		"[root] C" -> "[root] B"
+	}
+}
+			`,
+		},
+		"subgraphs, no depth restriction": {
+			Opts: GraphDotOpts{
+				MaxDepth: -1,
+			},
+			Graph: func() *Graph {
+				var g Graph
+				root := &testDrawableOrigin{"root"}
+				g.Add(root)
+
+				var sub Graph
+				sub.Add(&testDrawableOrigin{"sub_root"})
+
+				var subsub Graph
+				subsub.Add(&testDrawableOrigin{"subsub_root"})
+				sub.Add(&testDrawableSubgraph{
+					VertexName:      "subsub",
+					SubgraphMock:    &subsub,
+					DependentOnMock: []string{"sub_root"},
+				})
+				g.Add(&testDrawableSubgraph{
+					VertexName:      "sub",
+					SubgraphMock:    &sub,
+					DependentOnMock: []string{"root"},
+				})
+
+				g.ConnectDependents()
+				sub.ConnectDependents()
+				return &g
+			},
+			Expect: `
+digraph {
+	compound = "true"
+	newrank = "true"
+	subgraph "root" {
+		"[root] root"
+		"[root] sub"
+		"[root] sub" -> "[root] root"
+	}
+	subgraph "cluster_sub" {
+		label = "sub"
+		"[sub] sub_root"
+		"[sub] subsub"
+		"[sub] subsub" -> "[sub] sub_root"
+	}
+	subgraph "cluster_subsub" {
+		label = "subsub"
+		"[subsub] subsub_root"
+	}
+}
+			`,
+		},
+		"subgraphs, with depth restriction": {
+			Opts: GraphDotOpts{
+				MaxDepth: 1,
+			},
+			Graph: func() *Graph {
+				var g Graph
+				root := &testDrawableOrigin{"root"}
+				g.Add(root)
+
+				var sub Graph
+				sub.Add(&testDrawableOrigin{"sub_root"})
+
+				var subsub Graph
+				subsub.Add(&testDrawableOrigin{"subsub_root"})
+				sub.Add(&testDrawableSubgraph{
+					VertexName:      "subsub",
+					SubgraphMock:    &subsub,
+					DependentOnMock: []string{"sub_root"},
+				})
+				g.Add(&testDrawableSubgraph{
+					VertexName:      "sub",
+					SubgraphMock:    &sub,
+					DependentOnMock: []string{"root"},
+				})
+
+				g.ConnectDependents()
+				sub.ConnectDependents()
+				return &g
+			},
+			Expect: `
+digraph {
+	compound = "true"
+	newrank = "true"
+	subgraph "root" {
+		"[root] root"
+		"[root] sub"
+		"[root] sub" -> "[root] root"
+	}
+	subgraph "cluster_sub" {
+		label = "sub"
+		"[sub] sub_root"
+		"[sub] subsub"
+		"[sub] subsub" -> "[sub] sub_root"
+	}
+}
+			`,
+		},
+	}
+
+	for tn, tc := range cases {
+		actual, err := GraphDot(tc.Graph(), &tc.Opts)
+		if (err == nil) && tc.Error != "" {
+			t.Fatalf("%s: expected err: %s, got none", tn, tc.Error)
+		}
+		if (err != nil) && (tc.Error == "") {
+			t.Fatalf("%s: unexpected err: %s", tn, err)
+		}
+		if (err != nil) && (tc.Error != "") {
+			if !strings.Contains(err.Error(), tc.Error) {
+				t.Fatalf("%s: expected err: %s\nto contain: %s", tn, err, tc.Error)
+			}
+			continue
+		}
+
+		expected := strings.TrimSpace(tc.Expect) + "\n"
+		if actual != expected {
+			t.Fatalf("%s:\n\nexpected:\n%s\n\ngot:\n%s", tn, expected, actual)
+		}
+	}
+}
+
+type testGraphFunc func() *Graph
+
+type testDrawable struct {
+	VertexName      string
+	DependentOnMock []string
+}
+
+func (node *testDrawable) Name() string {
+	return node.VertexName
+}
+func (node *testDrawable) DotNode(n string, opts *GraphDotOpts) *dot.Node {
+	return dot.NewNode(n, map[string]string{})
+}
+func (node *testDrawable) DependableName() []string {
+	return []string{node.VertexName}
+}
+func (node *testDrawable) DependentOn() []string {
+	return node.DependentOnMock
+}
+
+type testDrawableOrigin struct {
+	VertexName string
+}
+
+func (node *testDrawableOrigin) Name() string {
+	return node.VertexName
+}
+func (node *testDrawableOrigin) DotNode(n string, opts *GraphDotOpts) *dot.Node {
+	return dot.NewNode(n, map[string]string{})
+}
+func (node *testDrawableOrigin) DotOrigin() bool {
+	return true
+}
+func (node *testDrawableOrigin) DependableName() []string {
+	return []string{node.VertexName}
+}
+
+type testDrawableSubgraph struct {
+	VertexName      string
+	SubgraphMock    *Graph
+	DependentOnMock []string
+}
+
+func (node *testDrawableSubgraph) Name() string {
+	return node.VertexName
+}
+func (node *testDrawableSubgraph) Subgraph() *Graph {
+	return node.SubgraphMock
+}
+func (node *testDrawableSubgraph) DotNode(n string, opts *GraphDotOpts) *dot.Node {
+	return dot.NewNode(n, map[string]string{})
+}
+func (node *testDrawableSubgraph) DependentOn() []string {
+	return node.DependentOnMock
+}

terraform/transform_provider.go

@@ -6,6 +6,7 @@ import (
 	"github.com/hashicorp/go-multierror"
 	"github.com/hashicorp/terraform/config"
 	"github.com/hashicorp/terraform/dag"
+	"github.com/hashicorp/terraform/dot"
 )
 
 // GraphNodeProvider is an interface that nodes that can be a provider
@@ -176,6 +177,19 @@ func (n *graphNodeDisabledProvider) Name() string {
 	return fmt.Sprintf("%s (disabled)", dag.VertexName(n.GraphNodeProvider))
 }
 
+// GraphNodeDotter impl.
+func (n *graphNodeDisabledProvider) DotNode(name string, opts *GraphDotOpts) *dot.Node {
+	return dot.NewNode(name, map[string]string{
+		"label": n.Name(),
+		"shape": "diamond",
+	})
+}
+
+// GraphNodeDotterOrigin impl.
+func (n *graphNodeDisabledProvider) DotOrigin() bool {
+	return true
+}
+
 type graphNodeMissingProvider struct {
 	ProviderNameValue string
 }
@@ -198,14 +212,16 @@ func (n *graphNodeMissingProvider) ProviderConfig() *config.RawConfig {
 }
 
 // GraphNodeDotter impl.
-func (n *graphNodeMissingProvider) Dot(name string) string {
-	return fmt.Sprintf(
-		"\"%s\" [\n"+
-			"\tlabel=\"%s\"\n"+
-			"\tshape=diamond\n"+
-			"];",
-		name,
-		n.Name())
+func (n *graphNodeMissingProvider) DotNode(name string, opts *GraphDotOpts) *dot.Node {
+	return dot.NewNode(name, map[string]string{
+		"label": n.Name(),
+		"shape": "diamond",
+	})
+}
+
+// GraphNodeDotterOrigin impl.
+func (n *graphNodeMissingProvider) DotOrigin() bool {
+	return true
 }
 
 func providerVertexMap(g *Graph) map[string]dag.Vertex {

terraform/transform_root.go

@@ -1,10 +1,6 @@
 package terraform
 
-import (
-	"fmt"
-
-	"github.com/hashicorp/terraform/dag"
-)
+import "github.com/hashicorp/terraform/dag"
 
 // RootTransformer is a GraphTransformer that adds a root to the graph.
 type RootTransformer struct{}
@@ -38,7 +34,3 @@ type graphNodeRoot struct{}
 func (n graphNodeRoot) Name() string {
 	return "root"
 }
-
-func (n graphNodeRoot) Dot(name string) string {
-	return fmt.Sprintf("\"%s\" [shape=circle];", name)
-}

website/source/docs/commands/graph.html.markdown

@@ -16,18 +16,26 @@ The output is in the DOT format, which can be used by
 
 ## Usage
 
-Usage: `terraform graph [options] PATH`
+Usage: `terraform graph [options] [DIR]`
 
-Outputs the visual graph of Terraform resources. If the path given is
-the path to a configuration, the dependency graph of the resources are
-shown. If the path is a plan file, then the dependency graph of the
-plan itself is shown.
+Outputs the visual dependency graph of Terraform resources according to
+configuration files in DIR (or the current directory if omitted).
+
+The graph is outputted in DOT format. The typical program that can
+read this format is GraphViz, but many web services are also available
+to read this format.
 
 Options:
 
+* `-draw-cycles`    - Highlight any cycles in the graph with colored edges.
+                      This helps when diagnosing cycle errors.
+
 * `-module-depth=n` - The maximum depth to expand modules. By default this is
                       zero, which will not expand modules at all.
 
+* `-verbose`        - Generate a verbose, "worst-case" graph, with all nodes
+                      for potential operations in place.
+
 ## Generating Images
 
 The output of `terraform graph` is in the DOT format, which can