Terraform Guide

Terraform Cloud workspaces: one diagram of what they build, from the repository

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

HCP Terraform organizes infrastructure into workspaces instead of directories, each with its own variables, its own state, and its own run history. That is a good operational model and a poor architectural one, because the console can tell you that you have forty-one workspaces and cannot tell you what they add up to. The answer is in the repository those workspaces run.

Try it free
6 min readFor teams whose Terraform runs in HCP Terraform or Terraform Enterprise

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

134/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

A workspace is a run boundary

A workspace holds everything one Terraform run needs: a configuration, variables, credentials, and a state. Separate workspaces behave like separate working directories, which is exactly why they are useful for blast radius and exactly why they fragment the picture. Nobody designs a platform in units of state files, but that is the unit the console shows.

The Explorer helps with inventory questions. It queries four data types, workspaces, modules, providers, and Terraform versions, and ships use cases such as Drifted workspaces and workspaces with failed checks. Inventory is not architecture. Knowing that thirty workspaces use google-beta 6.x does not tell a new joiner which one owns the network everything else sits in.

The relationships between workspaces are declared in code

Workspaces talk to each other through the configuration, not through the platform. One stack publishes outputs, another reads them with a remote state data source or the tfe_outputs data source, and that declaration lives in a .tf file. Datadef parses data lookups alongside resources and resolves references the same way, so the consuming side of that relationship is part of the parsed model rather than a guess.

Stack boundaries are recovered structurally, without any API access: a directory of .tf files is a module unit, and a unit that no other unit names as a module source is a root module. That is the same rule Terraform itself applies, so it survives whatever naming convention your organization uses for workspaces. Each stack is parsed with its backend type where one is declared, its input variable count, and its output count, and the module reference table in the generated doc carries the backend on the stack row.

The practical consequence is that a repository holding twelve workspace roots yields one diagram with twelve stack zones, rather than twelve screenshots taken from twelve run pages.

What the connection needs, and what it does not

A read-only connection to the repository on GitHub, GitLab, or Azure DevOps, plus a branch or tag. No HCP Terraform API token, no team token, no organization access, no state. That matters in an enterprise setting where handing a third party an HCP token is a longer conversation than granting read on a repo.

Because the analysis never touches runs or state, it says nothing about run status, applied versions, or whether a workspace is currently drifting. Those belong to HCP Terraform, whose health assessments compare real infrastructure against the configuration on the Standard and Premium editions. The split is clean: HCP Terraform owns what happened, the parsed diagram owns what the code declares. Terraform diagrams without state unpacks why that division is the safe one.

The diagram and the architecture doc regenerate daily and on demand, and the diagram embeds as a live image in a README, a Confluence page, or an internal portal with no account needed to view it.

Variable sets are invisible to a parser

Values injected by HCP variable sets are not in the repository, so a value that only exists there cannot be resolved. Values from tfvars files and call sites are. Keep environment-shaping values in tfvars if you want them on the nodes; see multi-environment Terraform.

FAQ

Does Datadef connect to the HCP Terraform API?

No. It connects to the repository on GitHub, GitLab, or Azure DevOps with read-only access and parses the .tf and .tfvars files it finds there. No HCP Terraform token, no team or organization token, no run access, and no state are involved, which is usually a shorter approval conversation than granting a third party access to the platform itself.

How does it know where one workspace root ends and another begins?

Structurally. A directory of .tf files is a module unit, and a unit that no other unit references as a module source is a root module, which is what a VCS-driven workspace points at. Each root module becomes its own zone on the diagram, with its backend type, input count, and output count in the generated doc.

Can it show a dependency between two workspaces?

Where the dependency is declared in code it is parsed like any other declaration, since remote state and tfe_outputs data sources are ordinary data blocks in the configuration. Dependencies that exist only as run triggers configured in HCP Terraform are not in the repository and are not visible to a parser.

Does it read state stored in HCP Terraform?

No, deliberately. HashiCorp documents that state and plan files carry resource attributes and metadata which can include sensitive values such as initial database passwords or API tokens. The analysis reads only the configuration source, so none of that is ever requested, which is what makes it usable on repositories under change control.

What about values injected through variable sets?

They are not in the repository, so they cannot be resolved and nothing is invented in their place. Variables bound at module call sites, declared with a default, or set in tfvars files are followed to a literal value where one exists, including per-environment tfvars. Keep the values that shape an environment in tfvars if you want them printed on the nodes.