README
¶
TerraGraph
Split infrastructure into independent Terraform modules and you lose the one thing a single workspace gives you for free: one module's outputs feeding straight into another's inputs. In practice that gap gets closed by hand: apply, copy a value, paste it into the next module's tfvars, repeat. Or it gets closed by giving up the isolation and merging everything back into one giant workspace.
terragraph closes that gap without either tradeoff. Every root module stays completely standalone (its own backend, its own providers, its own resources), and a separate file declares the wiring: which output feeds which input. terragraph reads that file, works out the dependency order, and passes the real values through automatically as it applies each module.
Install
macOS via Homebrew:
brew install --cask cloudfluent/tap/terragraph
Prebuilt binaries for Linux, macOS, and Windows (amd64/arm64) are attached to each release. Or build from source:
go install github.com/cloudfluent/terragraph/cmd/terragraph@latest
Requires Go 1.27.1+ to build, and terraform or tofu on PATH to run.
VS Code
Install Terragraph Blueprint from the VS Code Marketplace to get completion, definition navigation, hover metadata, and validation for blueprint.hcl and group.hcl. The extension contains a matching language server, so editor features do not require a separate CLI installation. See editors/vscode for source-development and override details.
Quick look
A blueprint (blueprint.hcl) is a flat list of node and edge facts:
node "vpc" { source = "./stacks/vpc" }
node "eks" { source = "./stacks/eks" }
edge {
from = node.vpc.output.vpc_id
to = node.eks.input.vpc_id
}
terragraph apply --parallelism 2 --auto-approve
terragraph resolves the graph, runs terraform/tofu for each node in dependency order, and passes vpc's real vpc_id output into eks's input at runtime, with no generated code and no shared state file. See examples/basic for this exact setup running end to end.
Documentation
See docs/ for the blueprint model, groups, vendoring, the execution model, and the full CLI reference.
Examples
Self-contained and cloud-credential-free (random/local providers only). Clone and run directly, each with its own README:
examples/basic: one node feeding two independent downstream nodes (wiring, parallel execution, incremental apply).examples/reuse: the same module instantiated twice via distinctbackend_config, proving state isolation.examples/group: a group instantiated viause, proving expansion and export wiring.examples/vendored: a node sourced from a remote git address, showing the vendor workflow.
Development
make check # fmt-check + lint + docs-check + build + test, exactly what CI runs
make fmt # reformat in place
make docs # regenerate docs/cli/*.md from the live CLI
make build # ./terragraph
make test # go test ./... -race
make help lists every target. make lint/fmt/fmt-check fetch a pinned golangci-lint into ./bin/ (gitignored) on first use.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
terragraph
command
Command terragraph runs the graph-based Terraform/OpenTofu orchestration engine: it resolves output -> input wiring between independent root modules and executes them in dependency order.
|
Command terragraph runs the graph-based Terraform/OpenTofu orchestration engine: it resolves output -> input wiring between independent root modules and executes them in dependency order. |
|
internal
|
|
|
blueprint
Package blueprint defines the terragraph blueprint data model: the set of nodes (independent Terraform/OpenTofu root modules) and edges (output -> input wiring between them) that make up a graph.
|
Package blueprint defines the terragraph blueprint data model: the set of nodes (independent Terraform/OpenTofu root modules) and edges (output -> input wiring between them) that make up a graph. |
|
cache
Package cache implements content-addressed incremental apply: a node is skipped if neither its own source files nor its resolved input values have changed since the last successful apply, a Merkle-DAG-style build cache, in the spirit of Bazel/Nix, rather than heuristic staleness tracking.
|
Package cache implements content-addressed incremental apply: a node is skipped if neither its own source files nor its resolved input values have changed since the last successful apply, a Merkle-DAG-style build cache, in the spirit of Bazel/Nix, rather than heuristic staleness tracking. |
|
cli
Package cli wires together terragraph's cobra command tree.
|
Package cli wires together terragraph's cobra command tree. |
|
engine
Package engine orchestrates blueprint parsing, graph construction, and terraform/tofu execution into the plan/apply/destroy/validate operations exposed by the CLI.
|
Package engine orchestrates blueprint parsing, graph construction, and terraform/tofu execution into the plan/apply/destroy/validate operations exposed by the CLI. |
|
exec
Package exec wraps the terraform/tofu CLI as a subprocess and writes the ephemeral variable file terragraph uses to pass values between nodes.
|
Package exec wraps the terraform/tofu CLI as a subprocess and writes the ephemeral variable file terragraph uses to pass values between nodes. |
|
graph
Package graph turns a parsed blueprint into an executable DAG: each node carries its real Terraform/OpenTofu variable/output schema, and edges are resolved into adjacency lists for validation and topological execution order.
|
Package graph turns a parsed blueprint into an executable DAG: each node carries its real Terraform/OpenTofu variable/output schema, and edges are resolved into adjacency lists for validation and topological execution order. |
|
language
Package language provides the editor-facing, tolerant view of a Blueprint workspace.
|
Package language provides the editor-facing, tolerant view of a Blueprint workspace. |
|
lsp
Package lsp adapts the editor-neutral language Workspace to the Language Server Protocol over stdio.
|
Package lsp adapts the editor-neutral language Workspace to the Language Server Protocol over stdio. |
|
module
Package module reads the declared variables and outputs of a Terraform/OpenTofu root module directly from its .tf files, without running `terraform init`.
|
Package module reads the declared variables and outputs of a Terraform/OpenTofu root module directly from its .tf files, without running `terraform init`. |
|
vendor
Package vendor fetches third-party module sources once into a local, git-committed directory instead of resolving them live during plan/apply.
|
Package vendor fetches third-party module sources once into a local, git-committed directory instead of resolving them live during plan/apply. |
|
tools
|
|
|
gendocs
command
Command gendocs regenerates docs/cli/*.md from the live cobra command tree (internal/cli.NewRootCmd).
|
Command gendocs regenerates docs/cli/*.md from the live cobra command tree (internal/cli.NewRootCmd). |