README
¶
TerraGraph
[!WARNING] terragraph is under active development and is not yet production-ready. Use it at your own risk. Breaking changes may occur frequently until the first stable release.
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. That gap gets closed one of three ways. By hand: apply, copy a value, paste it into the next module's tfvars, repeat. With terraform_remote_state, which trades the copying for a dependency written into the consumer's code: it names the producer's backend and needs read access to its entire state file, so the module no longer stands on its own. Or by giving up the isolation and merging everything back into one giant workspace.
terragraph closes that gap without any of the three tradeoffs. Every root module stays completely standalone, with its own backend, providers, and resources, and no reference to any other module. 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, with no generated code and no shared state.
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 with port metadata, definition navigation, and validation for Terragraph .hcl files opened as HCL, whatever their filenames. 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 is a flat list of node and edge facts. Save this example as blueprint.hcl in your working directory:
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. See examples/basic for this exact setup running end to end.
By default, commands merge the .hcl files directly in the current directory, excluding .terraform.lock.hcl. Filenames are flexible: --blueprint topology.hcl reads that file alone, while --blueprint path/to/config selects another directory. To keep the previous single-file behavior, pass --blueprint blueprint.hcl; sibling .hcl files are now included unless a file is explicitly selected. A group's group.hcl filename is also a convention; groups are selected by their block names. See file loading and a split blueprint example and group source directories.
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, skipping unchanged nodes).examples/reuse: the same module instantiated twice, proving the local state default isolates each node.examples/group: a group instantiated twice viause, proving expansion, export wiring, and per-instance state isolation.examples/contracts: producer and consumer declarations checked against an edge and the modules' schemas.examples/vendored: a node sourced from a remote git address, showing the vendor workflow.
Development
make check # fmt-check + lint + docs-check + build + test + vscode-check, 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. |
|
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. |
|
graphlock
Package graphlock serializes terragraph plan/apply/destroy across machines with a remote lock object.
|
Package graphlock serializes terragraph plan/apply/destroy across machines with a remote lock object. |
|
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 selected configuration files, without running `terraform init`.
|
Package module reads the declared variables and outputs of a Terraform/OpenTofu root module directly from its selected configuration files, without running `terraform init`. |
|
pathidentity
Package pathidentity compares existing and prospective filesystem paths without writing files or choosing where callers store their data.
|
Package pathidentity compares existing and prospective filesystem paths without writing files or choosing where callers store their data. |
|
runlock
Package runlock serializes terragraph processes that mutate a blueprint's working state.
|
Package runlock serializes terragraph processes that mutate a blueprint's working state. |
|
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). |