Skip to content
Part 1: Your first configuration

Writing your first vect project, part 1

In this part we wrap one ordinary Terraform root in a vect configuration, and check it with vect validate, vect graph, and vect inspect. Nothing runs yet, so you need no server and no cloud account.

Where to get help: if you get stuck, open an issue on the issue tracker. To check that vect is installed, run vect version; if it isn’t, see Installation.

Create the project

A vect project is a folder. Create one and move into it:

mkdir vect-tutorial
cd vect-tutorial
mkdir -p roots/pet

Run every command in this tutorial from inside vect-tutorial. By the end of this part the folder looks like this:

vect-tutorial/
  main.hcl
  roots/
    pet/
      main.tf

The Terraform root

roots/pet is a plain Terraform root. It uses the random provider, which needs no account, and it exposes one output.

roots/pet/main.tf
terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

resource "random_pet" "this" {
  length = 2
}

output "name" {
  value = random_pet.this.id
}
Coming from Terraform: vect doesn’t replace your root and doesn’t ask you to change it. The .tf files stay exactly as they are; vect wraps the root and runs it with an engine it fetches for you (OpenTofu by default). Your state, providers, and modules keep working the way they do today.

The vect configuration

Next to roots/, create main.hcl. It declares one executor: a unit of work that vect plans and applies. Here the executor is of type terraform, named pet, and its source points at the root.

main.hcl
executor "terraform" "pet" {
  source = "./roots/pet"
}
A default you can swap: this executor runs your root with OpenTofu, the default engine. To use Terraform instead, set engine = "terraform" on the executor (it must be a literal, "opentofu" or "terraform"). vect then fetches the Terraform binary, and in Part 3 you’d add terraform_version next to opentofu_version in defaults, unless the root or its modules already set a Terraform version constraint. Details are in the executor reference.

vect loads every .hcl file in the folder you run it from. That folder is the root stack; you meet nested stacks in Part 2.

Validate it

vect validate
Success!
  (root)  1 block

validate loads the configuration and checks it: syntax, references, and the settings each executor accepts. It changes nothing. We have one block in the root stack, as expected.

See the graph

vect graph
terraform.pet

graph prints the evaluation order, one node per line. There is one node, named terraform.pet: the executor type, then its name. With more executors the lines come out in dependency order, which is what Part 2 is about.

Inspect the evaluated input

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

inspect shows what vect would hand to each executor, after it has evaluated every expression. For now that’s just the source, and depends_on is empty because pet needs nothing from anywhere else.

What we’ve done

You have one Terraform root, one executor block that wraps it, and three commands that read the configuration without running anything. Continue with Part 2, where a second root consumes this root’s output.