Skip to content
Part 2: Composing roots

Writing your first vect project, part 2

In this part we add a second Terraform root that uses the first one’s output, let vect work out the order, split the two into stacks, and see values flow through the graph before anything runs. We pick up in the vect-tutorial folder from Part 1.

Where to get help: open an issue on the issue tracker.

Run every command from inside vect-tutorial.

A second root

Create a folder for it:

mkdir -p roots/greeting

The greeting root takes a name variable and builds a message from it. It uses terraform_data, which is built into Terraform and needs no provider.

roots/greeting/main.tf
variable "name" {
  type = string
}

resource "terraform_data" "greeting" {
  input = "Hello, ${var.name}!"
}

output "message" {
  value = terraform_data.greeting.output
}

Wire the roots together

Replace main.hcl with both executors. The greeting executor passes terraform.pet.name as its name input:

main.hcl
executor "terraform" "pet" {
  source = "./roots/pet"
}

executor "terraform" "greeting" {
  source = "./roots/greeting"
  inputs = {
    name = terraform.pet.name
  }
}

terraform.pet.name reads as: the executor of type terraform named pet, and its Terraform output name. That reference is the whole dependency declaration.

vect validate
Success!
  (root)  2 blocks
vect graph
terraform.pet
terraform.greeting

vect saw the reference and ordered pet before greeting. The order doesn’t depend on where the blocks sit in the file.

Coming from Terraform: with plain Terraform you’d apply pet, then read its state from greeting through a terraform_remote_state data source, which means greeting has to know where pet keeps its state, and you have to remember the order. Here neither root knows about the other. The greeting root just declares a name variable, and the configuration above does the wiring and the ordering.
vect inspect
node "terraform.pet" {
  depends_on = []
  type = object({
    source = string
  })
  input = {
    source = "./roots/pet"
  }
}

node "terraform.greeting" {
  depends_on = ["terraform.pet"]
  # lookup terraform.pet.name
  type = object({
    inputs = object({
      name = dynamic
    })
    source = string
  })
  input = {
    inputs = {
      name = /* unresolved: dynamic */ terraform.pet.name
    }
    source = "./roots/greeting"
  }
}

greeting now has depends_on = ["terraform.pet"]. Its name input is marked unresolved: the pet doesn’t exist yet, so vect can’t know the value.

Split into stacks

A flat file is fine for two roots, but a real project has many. A stack is a folder of .hcl files that vect loads as one scope, and a stack exposes what it chooses through output blocks. Create a folder for each:

mkdir -p stacks/pet stacks/greeting

The pet stack wraps the first root and publishes its result as an output. Its source is relative to the stack’s own folder:

stacks/pet/main.hcl
executor "terraform" "pet" {
  source = "../../roots/pet"
}

output "name" {
  value = terraform.pet.name
}

The greeting stack declares a variable for what it needs, so it can’t see anything it wasn’t given:

stacks/greeting/main.hcl
variable "name" {
  type = string
}

executor "terraform" "greeting" {
  source = "../../roots/greeting"
  inputs = {
    name = var.name
  }
}

output "message" {
  value = terraform.greeting.message
}

Now main.hcl only composes the stacks. Replace it with:

main.hcl
stack "pet" {
  source = "./stacks/pet"
}

stack "greeting" {
  source = "./stacks/greeting"
  name   = stack.pet.name
}

output "message" {
  value = stack.greeting.message
}

The name attribute on the greeting stack fills the variable "name" we declared there. stack.pet.name is the pet stack’s output. The root’s own output "message" re-exports the greeting.

The project now looks like this:

vect-tutorial/
  main.hcl
  roots/
    greeting/
      main.tf
    pet/
      main.tf
  stacks/
    greeting/
      main.hcl
    pet/
      main.hcl
vect validate
Success!
  (root)          0 blocks
  stack.greeting  1 block
  stack.pet       1 block
vect graph
stack.pet.terraform.pet
stack.pet.output.name
stack.greeting.var.name
stack.greeting.terraform.greeting
stack.greeting.output.message
output.message

Addresses now carry the stack path: stack.pet.terraform.pet. The graph is still a single one, flattened across stack boundaries, so greeting still waits for pet even though they live in different stacks. The output and var nodes show how the value travels: out of pet, into greeting, and out again at the root.

A stack is vect’s grouping unit. It plays the role a module does in Terraform, but the word module is kept for Terraform modules, and a module block in a vect file is an error that suggests stack.

See values flow before anything runs

Nothing has run, so pet has no name yet. vect inspect on its own shows the dependent input as unresolved:

vect inspect
node "stack.pet.terraform.pet" {
  depends_on = []
  type = object({
    source = string
  })
  input = {
    source = "../../roots/pet"
  }
}

node "stack.greeting.terraform.greeting" {
  depends_on = ["stack.greeting.var.name"]
  # lookup var.name
  type = object({
    inputs = object({
      name = string
    })
    source = string
  })
  input = {
    inputs = {
      name = /* unresolved: string */ var.name
    }
    source = "../../roots/greeting"
  }
}

To see what the input would be, give vect a pretend result for pet. Create a fact file; any file ending in .facts.hcl is ignored when the folder is loaded and used only when you pass it with --facts. The result block names an executor by its address and gives the outputs it would produce:

Save it next to main.hcl:

pet.facts.hcl
result "stack.pet.terraform.pet" {
  value = {
    name = "gentle-heron"
  }
}
vect inspect --facts pet.facts.hcl
node "stack.pet.terraform.pet" {
  depends_on = []
  type = object({
    source = string
  })
  input = {
    source = "../../roots/pet"
  }
}

node "stack.greeting.terraform.greeting" {
  depends_on = ["stack.greeting.var.name"]
  result_sources = [{
    address    = "stack.pet.terraform.pet"
    provenance = "hypothetical"
  }]
  type = object({
    inputs = object({
      name = string
    })
    source = string
  })
  input = {
    inputs = {
      name = "gentle-heron"
    }
    source = "../../roots/greeting"
  }
}

The name input of greeting is now "gentle-heron". result_sources records where that value came from: hypothetical means you supplied it, as opposed to reading it from something vect applied. You can check what a change does to downstream inputs before running a thing.

result blocks are only accepted by vect inspect. Other commands reject them, so a pretend value can never leak into a real run.

What we’ve done

Two Terraform roots now form one ordered graph, with the dependency expressed as a reference and the values passed through declared stack outputs. All of it was checked offline. In Part 3 we run it.