Skip to content
Stacks and projects

Stacks and projects

A Terraform root is a unit of state. A vect stack is a unit of composition: a folder of vect configuration that you call like a function, with inputs going in and outputs coming out. Stacks are how you keep a growing configuration readable, and projects are how stacks travel between repositories. This guide explains both: the scope rules that make a stack behave like a function, the project root that lets several root stacks share stacks, and the cross-repository story that motivated most of the design.

Why this exists

Picture two repositories. A platform team owns infra, which defines the shared pieces: queues, databases, the conventions around naming and retention. Several product teams own app repositories, each of which needs “an orders queue, built the platform way”. With plain Terraform you have a few options, and all of them hurt. You publish a module and every app repo applies it with its own state, so the platform team can’t see or order what the apps deploy. Or the apps read the platform’s state with terraform_remote_state, and now they know where the platform keeps its state. Or everything lives in one repository and every change goes through one team.

vect’s answer is that the platform repository exports stacks, and the app repository composes them. The app’s configuration says “load the stack queue from the platform project, pinned at this published bundle”. The composed stack’s nodes become ordinary nodes in the app’s graph, in the app’s workspace, with the app’s Inventory records. The platform team ships a versioned, immutable artifact; the app team decides when to move to a new one. The second half of this guide builds exactly that, and everything before it is the groundwork.

Stacks are functions

A stack block loads another directory of .hcl files and runs it as a nested scope. Here is the root of a small project (examples/topics/stacks/scope):

main.hcl
global "env" {
  type  = string
  value = "dev"
}

variable "replicas" {
  type    = number
  default = 2
}

stack "network" {
  source = "./stacks/network"
}

stack "service" {
  source   = "./stacks/service"
  subnet   = stack.network.subnet
  replicas = var.replicas
}

output "endpoint" {
  value = stack.service.endpoint
}

source is a path relative to the calling stack, and every other attribute is an input. The child declares what it accepts with variable blocks and what it offers with output blocks:

stacks/service/main.hcl
variable "subnet" {
  type = string
}

variable "replicas" {
  type = number
}

executor "terraform" "api" {
  source = "../../roots/service"
  inputs = {
    name     = "api-${env}"
    subnet   = var.subnet
    replicas = var.replicas
  }
}

output "endpoint" {
  value = terraform.api.endpoint
}

Variables and outputs use Terraform’s type-constraint syntax, optional(...) with defaults included, and an output with a type converts its value to it (LANG-STACK-3, LANG-STACK-4). You reference a child’s output as stack.<name>.<output>, and that reference is a dependency like any other: stack.service waits for stack.network. Here’s the graph, which is one flat graph that crosses the stack boundaries:

$ vect graph
var.replicas
stack.network.terraform.net
stack.network.output.subnet
stack.service.var.replicas
stack.service.var.subnet
stack.service.terraform.api
stack.service.output.endpoint
output.endpoint
Coming from Terraform: a stack is closest to a module, and vect says so if you forget: a module block is a diagnostic that suggests stack. The difference is what’s inside. A Terraform module contributes resources to its caller’s root and state. A stack contributes executors, and each terraform executor is a whole root with its own state, so a stack can compose several roots, other stacks, data sources, and tasks into one callable unit.

The scope rules

A stack is a function in the strict sense: it sees its arguments and nothing else.

  • Inputs are evaluated in the caller’s scope. In subnet = stack.network.subnet, the expression is the caller’s. The child only ever receives the resulting value.
  • A child doesn’t inherit its parent’s var or local names. If the root has a replicas variable, the child still has to declare its own and be handed a value. You never have to wonder where a name came from.
  • Children expose only declared outputs. A caller can’t reach into a child’s executors or locals.
  • Inputs are checked in both directions. Passing an input the child doesn’t declare is an error, as is a missing required input.

Each rule is enforced with a source-ranged diagnostic. These are real runs against modified copies of the example:

$ vect validate     # service called with region = "us-east-1", which it doesn't declare
Error: Unexpected stack input

  on main.hcl line 19, in stack "service":
  19:   region   = "us-east-1"

Stack "service" has no variable named "region". An input the child never declared would be silently
ignored, so it is an error here.
$ vect validate     # service uses var.replicas without declaring it
Error: Reference to undeclared input variable

  on stacks/service/main.hcl line 10, in executor "terraform" "api":
  10:     replicas = var.replicas

var.replicas is not declared.
$ vect validate     # the root reads stack.service.address, which service doesn't output
Error: Reference to undeclared stack output

  on main.hcl line 22, in output "endpoint":
  22:   value = stack.service.address

stack.service.address is not declared.

To reproduce them, edit a copy of the example: add the extra region input to the service call; delete the variable "replicas" block and the replicas = input from the service call in main.hcl while leaving var.replicas in the stack; or change the root output to stack.service.address. vect finds them before anything runs, including across stack boundaries, which is the point of declaring the interface. The rules are LANG-STACK-2 and LANG-STACK-5. A stack that leads back to a directory already on the call path is a cycle and is a diagnostic too (LANG-STACK-6).

Globals are the exception, on purpose

One thing crosses every boundary without being passed: a global. The root declares global "env", and the network and service stacks use env in their executors without a variable in between. Globals are for the few values that really are ambient, such as an environment name or a region; they’re typed, they’re declared only in the root, and a stack that tries to declare its own gets a diagnostic:

Error: Root-only block in a child stack

  on stacks/network/main.hcl line 12, in global "env":
  12: global "env" {

A global with a value block is allowed only in the root configuration, not in a child stack.

A global with a value is a composed global, computed from literals, other globals, and plan-time data. A global without a value is an input global, and the caller supplies it with --global, --global-file, or a fact file (--global and --global-file are available on validate, inspect, and bundle; plan and apply take values through --facts). Either kind can be overridden by the caller (LANG-GLOBAL-1 to LANG-GLOBAL-4). That is how one configuration becomes dev and prod. A fact file, prod.facts.hcl, replaces the "dev" default:

prod.facts.hcl
global "env" {
  value = "prod"
}
$ cd scope
$ export VECT_CONFIG=../server.vect
$ vect plan --workspace dev --facts prod.facts.hcl
…
stack.network.terraform.net |       + input  = "10.0.0.0/24 (net-prod)"
…
plan of workspace "dev": succeeded (run 01a1e7db-9a7b-70ab-9020-3bf5c0a941f0)
…

Root outputs

output blocks in the root stack are the project’s published results. After an apply that commits at least one node, vect evaluates them from Inventory and records them on the run’s deployment pointer, with sensitive marks preserved (WS-OUT-1). Reading them back is one command:

$ vect apply --workspace dev --auto-approve
…
$ vect output --workspace dev
endpoint = "api-dev x2 in 10.0.0.0/24 (net-dev)"

Other workspaces can read the same outputs with data "vect_workspace". See data "vect_workspace" in the executors reference.

The project root

By default a project is one folder: the directory you run vect in is both the root stack and the boundary of everything it may read. That boundary is what makes bundles hermetic, and vect enforces it. A source that climbs out with .. is rejected.

But real repositories have more than one root stack. A common shape is one root stack per environment or per workspace, all calling the same shared stacks. For that, the project root can sit above the root stack. vect finds it in this order (COMP-FS-4):

  1. the --project-root flag or VECT_PROJECT_ROOT variable;
  2. else the nearest parent directory holding a .vectroot file;
  3. else the root stack’s own directory.

The marker file can be empty. The example project keeps one next to the folders that share stacks:

examples/topics/stacks/
  .vectroot            <- an empty file: this is the project root
  scope/               <- stacks and roots, also runnable on its own
  env-dev/main.hcl     <- a root stack
  env-prod/main.hcl    <- another root stack

env-dev and env-prod each reach over to the shared stacks:

env-dev/main.hcl
global "env" {
  type  = string
  value = "dev"
}

stack "network" {
  source = "../scope/stacks/network"
}

stack "service" {
  source   = "../scope/stacks/service"
  subnet   = stack.network.subnet
  replicas = 1
}

output "endpoint" {
  value = stack.service.endpoint
}

env-prod is the same with "prod" and three replicas. Without the marker, the .. would be a violation; with it, both work, and the diagnostic tells you the remedy when you forget. This is what vect validate --project-root . printed from inside env-dev (the flag disagrees with the marker, so vect warns and the flag wins):

vect: warning: --project-root or VECT_PROJECT_ROOT names …/topics/stacks/env-dev but …/topics/stacks holds a .vectroot file; using …/topics/stacks/env-dev
Error: Stack source outside the project root

  on main.hcl line 7, in stack "network":
   7:   source = "../scope/stacks/network"

"../scope/stacks/network" resolves outside the project root .. A stack must live inside the project
root: put a .vectroot file in a parent directory that holds every stack it uses, or pass
--project-root.
…

Only the current project root’s .vectroot is read, and the current directory never decides where the project root is; your root stack’s location does (COMP-FS-1 to COMP-FS-6).

A default you can swap: a root stack with no .vectroot above it is its own project root, as in the tutorial. You only need the marker once a second root stack wants to share a directory tree with the first.

Changing a workspace’s root stack is a deliberate act

The bundle records which root stack it was built from, and a workspace remembers its current bundle’s root. If you apply env-dev into the dev workspace and later try to apply env-prod into the same workspace, vect refuses before anything runs, because that would reinterpret every node the workspace already owns.

For that to happen both folders must use one store. The server.vect in this folder has relative data_dir and key paths, which would give env-dev and env-prod a store each, so make the paths absolute in a copy and point VECT_CONFIG at it, then apply env-dev:

sed "s|\"store|\"$HOME/rc/store|" server.vect > ~/rc.vect
export VECT_CONFIG=$HOME/rc.vect
vect apply --chdir env-dev --workspace dev --auto-approve

Now applying env-prod into the same workspace is refused:

$ vect apply --chdir env-prod --workspace dev --auto-approve
vect: failed_precondition: the run cannot start: the run's root stack is "env-prod" but workspace "dev"'s current bundle sha256:26395eb8c3d75c9097a21774d62bc24fdd799944a5883afacd3b57e688973c72 has root stack "env-dev"; pass --allow-root-change to change it

--allow-root-change on plan and apply is the explicit opt-in (RUN-RUN-7). Moving a root stack is sometimes right, for example when you split a configuration, and the flag keeps it from happening by accident. The workspace-to-root pairing is a good fit for one root stack per workspace.

Projects: names and exports

So far a project is a directory. To let other projects use your stacks, give it a name and say which directories are public. That lives in the .vectroot file (COMP-FS-7). Here is the platform team’s infra project (examples/topics/stacks/infra):

.vectroot
project {
  name             = "platform"
  exports          = ["exported"]
  required_version = ">= 0.1.0"
}
  • name identifies the project in other projects’ configuration. It must match [a-z][a-z0-9_-]*.
  • exports lists directories, relative to the project root, whose whole trees other projects may load stacks from. Everything outside them stays private.
  • required_version is the vect version a consumer must run to compose these stacks, checked when they’re composed.

The exported stack is an ordinary stack, with two additions that make it safe to run for strangers:

exported/queue/main.hcl
global "env" {
  type = string
}

variable "name" {
  type = string
}

variable "retention_days" {
  type    = number
  default = 4
}

executor "terraform" "queue" {
  source = "../../roots/queue"
  inputs = {
    name           = "${env}-${var.name}"
    retention_days = var.retention_days
  }
}

output "queue_url" {
  type  = string
  value = terraform.queue.url
}

First, global "env" has no value. Normally global is root-only, but a stack under an export may declare one, meaning “my host provides this”. When the stack is composed, the host’s root must declare a global of that name whose type converts to the declared one (COMP-COMPOSE-7). That’s how the platform’s queue picks up the app’s environment name without any variable plumbing. Inside the platform project itself, the project’s root global fills the same slot.

Second, exported stacks can’t depend on their caller for anything that shapes the bundle. Every source and file path must be a literal, an engine must be a literal or unset, and any variable without a default must declare its type. Anything else is a diagnostic naming the expression (BNDL-UNIT-15). This is the price of a stack whose contents are fixed when it’s published: the units and Terraform roots it needs are packed into the bundle no matter who calls it later. When you validate an exported directory by itself, a typed default-less variable is a typed unknown and a declared global is an input global, so the stack checks out in isolation:

$ cd infra/exported/queue && vect validate && vect graph
Success!
  (root)  1 block
var.name
var.retention_days
terraform.queue
output.queue_url

A project with exports and no stack files at its root, like infra, bundles as an exports-only bundle: only the exported trees, and the roots and assemblies they reference, are packed (BNDL-UNIT-14, BNDL-MAN-11). It’s never run by itself, and a run or loop trigger that names it as the root bundle is refused at admission. It exists only to be composed into someone else’s workspace. The bundle’s manifest records the project’s name, exports, and required_version (BNDL-MAN-10).

Coming from Terraform: this is a published module registry, but the published thing is a whole stack including its roots, pinned by the content digest of an immutable bundle rather than by a version tag that someone can move. There’s no terraform init that goes and fetches it later; the bundle already contains everything.

Name-anchored sources

A source of the form <project>//<path> names a path relative to the root of the named project, rather than relative to the calling file. It does three jobs (LANG-STACK-1, LANG-STACK-10):

  • Inside the project that has that name, it’s an ordinary project-root-relative path: platform//exported/queue in infra’s own root stack loads exported/queue.
  • On a stack that also sets bundle, it names which stack to load from another project’s pinned bundle. We’ll use this below.
  • Anywhere else in another project’s bundle, it can’t be resolved at bundle time and is recorded in the manifest as an external reference, to be resolved when that bundle is composed. This is how an exported stack can use a shared definition from the project that composes it.

The // follows the Terraform convention for “sub-directory within a source”.

Composing stacks from another project

Now the app repository. It’s its own project, with its own name and no exports:

.vectroot
project {
  name = "shop"
}

And its root stack calls the platform’s exported stack:

main.hcl
global "env" {
  type  = string
  value = "prod"
}

global "platform_bundle" {
  type = string
}

stack "orders_queue" {
  source   = "platform//exported/queue"
  bundle   = platform_bundle
  lineages = ["platform@main"]

  name           = "orders"
  retention_days = 14
}

output "orders_queue_url" {
  value = stack.orders_queue.queue_url
}

Three arguments make this a bundle stack (LANG-STACK-9):

  • source names the project and the exported stack directory to load.
  • bundle is the pin: a bundle digest or a publication ID. It’s a plan-time value, so it can be a literal, a global (as here, an input global, which is how CI would pass a digest), or a plan-time data block.
  • lineages lists which publication lineages the pin may come from, each <repository>@<branch>. A lineage is a repository and branch, so platform@main means “published from the platform repo’s main branch”.

name and retention_days are the stack’s inputs, as ever. Several stack blocks can use the same pin, and a composed stack can’t itself contain bundle stacks.

What the pin guards against

A pin is a claim, and vect checks the claim before it composes anything (COMP-COMPOSE-2). The pinned bundle must exist in the bundle store, the project name in its manifest must equal the project in source, the stack must lie inside one of its exports, and its publication’s lineage must be one of yours. So a mistyped digest, a bundle from the wrong project, or a build from somebody’s feature branch is refused instead of silently deployed. The same goes for a stack that declares a global your root doesn’t provide, or a project required_version the running vect doesn’t satisfy.

A refusal fails only that stack’s subtree. The rest of the workspace is planned and applied, the run ends failed, and the records under the refused stack are never treated as orphans and never destroyed because of it. To retire a composed stack on purpose, use enabled = false or a removed block (COMP-COMPOSE-4, RUN-ORPHAN-5).

Once resolved, the pinned digests become part of the run’s pinned facts, so a worker, a retry, and an apply of a saved plan all load exactly the same tree.

Publishing and composing, end to end

Here’s the whole loop on a laptop. The platform team builds and publishes infra (start in the examples/topics/stacks folder). Paths in server.vect, such as data_dir and the key file, resolve against the directory you run vect in, not the config file’s directory. The committed file uses relative paths, which is fine for one folder. But plan and apply take the root stack from the directory they run in (or the one --chdir names), and relative paths resolve from that directory too, so infra and app would get separate stores. So make the paths absolute in your copy, once:

$ sed -i.bak "s|\"store|\"$PWD/store|" server.vect   # data_dir and key path become absolute
$ export VECT_CONFIG=$PWD/server.vect
$ vect bundle infra --lineage platform@main --source-position 1 --commit abc123
source digest: sha256:c6f0d4c8f7409db70b9ecf7a3b60d2df32f3464ac29f2b026c874f5174a49494
bundle digest: sha256:cf8fb1431968204c7bc5e5f92b46452b6fdb0964fe3cb102050b074007cb8efe
publication: pub_000001

Every upload creates an immutable publication: the bundle digest plus its commit, lineage, and a source-position that CI supplies (a monotonically increasing number per lineage). In real life the publisher is CI, and the platform team posts the digest or publication ID wherever app teams look for it.

Now the app. The pin is a fact: write the bundle digest into app/pins.facts.hcl, as a global block.

pins.facts.hcl
global "platform_bundle" {
  value = "sha256:cf8fb1431968204c7bc5e5f92b46452b6fdb0964fe3cb102050b074007cb8efe"
}

(Your digest will differ.) With no workspace, offline commands treat the composed stack as opaque, one node with outputs of unknown value. Pass a workspace and a known pin, and validate, graph, and inspect load the pinned bundle read-only through the bundle store and show the real thing (COMP-COMPOSE-5):

$ vect graph app
stack.orders_queue
output.orders_queue_url

$ vect graph app --workspace dev --facts app/pins.facts.hcl
stack.orders_queue.var.name
stack.orders_queue.var.retention_days
stack.orders_queue.terraform.queue
stack.orders_queue.output.queue_url
output.orders_queue_url

The first graph is the opaque view. The second loaded the platform’s stack under the call’s address, stack.orders_queue. inspect shows the platform’s executor evaluated against the app’s globals and inputs:

$ vect inspect app --workspace dev --facts app/pins.facts.hcl
node "stack.orders_queue.terraform.queue" {
  depends_on = ["stack.orders_queue.var.name", "stack.orders_queue.var.retention_days"]
  …
  input = {
    inputs = {
      name           = "prod-orders"
      retention_days = 14
    }
    source = "../../roots/queue"
  }
}

The prod- prefix is the app’s env global flowing into the platform’s ${env}-${var.name}. A publication ID works too (value = "pub_000001"); then the lineage guard checks that publication’s lineage. With a digest, vect picks the publication by the rule in BNDL-MAN-8 (the highest source position within one lineage), and refuses the pin if that selection fails.

Offline commands load composed pins only when you pass --workspace (or set VECT_WORKSPACE) explicitly. The default_workspace in server.vect doesn’t count, by design: a workspace turns on live reads, and an implicit one would do it silently (COMP-MODE-2). When a guard trips, graph and inspect warn and leave the stack opaque, while validate --workspace reports the same “Bundle stack not loaded” message as an error and exits 1. With lineages = ["platform@dev"]:

Warning: Bundle stack not loaded

stack.orders_queue stays opaque: publication pub_000001 of bundle
sha256:cf8fb1431968204c7bc5e5f92b46452b6fdb0964fe3cb102050b074007cb8efe has lineage "platform@main",
which is not one of platform@dev

With a pin that names nothing in the store:

stack.orders_queue stays opaque: the pin "sha256:0000" is neither a published bundle digest nor a
known publication: not_found: bundler: no such publication: "sha256:0000"

And when the app’s root forgets the global "env" the platform stack needs:

stack.orders_queue stays opaque: bundle:cf8fb1431968/exported/queue/main.hcl:1,1-13: Global not
provided; The stack declares the global "env" for its host to provide, but the host root declares no
such global (COMP-COMPOSE-7).

vect plan and vect apply (run in the root stack’s folder, or pointed at it with --chdir) perform the same load, and a refusal there is the failed-subtree behavior described above instead of a warning.

$ vect plan --chdir app --workspace dev --facts pins.facts.hcl
…
stack.orders_queue.terraform.queue | Plan: 1 to add, 0 to change, 0 to destroy.
…
plan of workspace "dev": succeeded (run 01a1e7db-e292-7bd7-adc3-35ba60be7671)
  stack.orders_queue.terraform.queue  run  will run

Moving to a new platform release

Upgrading is changing the pin. The platform team publishes a new bundle; the app team changes the value of platform_bundle, runs vect plan, and reads a plan that contains exactly the platform stack’s changes alongside the app’s own. If something’s wrong, they set the pin back. Nothing in the app repository changes except one string, and nothing about the platform changes at all. Pinning to a publication whose source position is older than the current pin in the same lineage is something the workspace spec will refuse unless the write says it’s a rollback (WS-SPEC-13), so a late CI retry can’t move a pin backwards. That check lives with the workspace spec, which isn’t landed yet; today the pin is whatever plan-time value your configuration reads.

What’s different from the module registry you have

If you step back, this is Terraform modules with three properties Terraform doesn’t give you:

  • A pin is a content digest of an immutable bundle, checked on four axes (existence, project, exports, lineage), not a version string.
  • The composed stack’s nodes live in your graph. They’re ordered with your executors, appear in your Inventory under stack.orders_queue..., run under your workspace’s leases, and are planned in your vect plan. There is no second state to read or order.
  • The exporting project controls the surface. Only the exports trees can be composed, they must be self-contained under BNDL-UNIT-15, and their required_version and declared globals are checked before anything runs.

Reference and where to go next