Values: types, unknowns, sensitive and ephemeral
In Terraform, a value is an expression result inside one root. In vect, values also cross the boundaries between executors: one terraform root’s output becomes another root’s input, a data source’s answer becomes an argument, and a secret has to reach a process without being written anywhere. This guide explains how those values are typed, what “unknown” means when nothing has run yet, how you supply or observe values offline, and how sensitive and ephemeral differ. It assumes you’ve finished First steps and read the graph guide. The rules are in the language, compilation, and executors specs.
We’ll use two small projects in docs/site/examples/topics/values/. flow shows typing, unknowns, and fact files. secrets runs for real against a local Temporal server, and shows what redaction does and doesn’t cover. Neither needs a cloud account to read or to run: the AWS-backed blocks are always fed from a fact file. Your IDs and digests will differ from ours.
How values move between nodes
Every value vect handles is a cty value, the same library Terraform uses. That’s why Terraform type constraints (string, object({...}), optional(...)) work unchanged on variable and output blocks. A value is a type plus one of three states: known, null, or unknown. Terraform has the same three; the difference is that in vect they matter across nodes, not just inside one plan.
Here’s the first project, flow:
global "region" {
type = string
}
ephemeral "aws_secretsmanager" "db" {
secret_id = "app/${region}/db-password"
}
data "aws_ssm" "build" {
name = "/app/build-id"
}
executor "terraform" "network" {
source = "./roots/network"
inputs = {
region = region
}
}
executor "terraform" "app" {
source = "./roots/app"
inputs = {
network_id = terraform.network.network_id
build_id = data.aws_ssm.build.value
password = ephemeral.aws_secretsmanager.db.secret_string
}
}Reference syntax decides what a value is. terraform.network.network_id is an executor result, available only after network has run. data.aws_ssm.build.value comes from a data source. ephemeral.aws_secretsmanager.db.secret_string comes from an ephemeral source. A global like region is bound by its bare name in every stack (LANG-GLOBAL-1). Each of these is also an edge in the graph, so the graph guide’s ordering rules apply to values too.
A reference to an executor, data, or ephemeral block gives you only the attributes its type declares in its OutputSchema (LANG-REF-2). For a terraform executor, that’s one attribute per root output. Wrapper arguments like source or inputs are never visible to a reference. When the schema is known, a reference to an attribute that doesn’t exist is a diagnostic.
terraform_remote_state reads another root’s state file, whatever its shape, and fails at plan time if the other root hasn’t applied. In vect the producer is a node in the same graph. You refer to its output by name, vect runs it first, and the typed contract is the root’s output list. There’s no state file to read and no ordering to arrange by hand.Unknowns, typed nulls, and what “deferred” means
Before a node runs, the value of terraform.network.network_id doesn’t exist. vect doesn’t guess: it’s an unknown, and it keeps whatever type information it has. Look at what vect inspect prints for the project with nothing supplied, trimmed to the second node:
vect inspect…
node "terraform.app" {
depends_on = ["terraform.network", "data.aws_ssm.build", "ephemeral.aws_secretsmanager.db"]
# lookup data.aws_ssm.build.value
# lookup ephemeral.aws_secretsmanager.db.secret_string
# lookup terraform.network.network_id
type = object({
inputs = object({
build_id = string
network_id = dynamic
password = string
})
source = string
})
input = {
inputs = {
build_id = redacted(string)
network_id = /* unresolved: dynamic */ terraform.network.network_id
password = redacted(string)
}
source = "./roots/app"
}
}(The same output for terraform.network shows region = /* unresolved: string */ region, because no value was supplied for the global either.) Three kinds of “not known” are visible here:
unresolved: dynamic: an executor output. It will exist after the node runs, and its type is only fully known then, so it’sdynamic.unresolved: string: a value with a known type and no value yet. The globalregionis declaredstringbut nobody supplied it.redacted(string): not about unknowns at all; the value is marked sensitive or ephemeral. We’ll come back to this.
Where an unknown is allowed
An unknown is fine as a node’s input. The value gets filled in when the producer finishes, and the run passes it along. It isn’t fine in places that decide the shape of the graph. enabled, count, for_each keys, and a stack’s source have to be wholly known at plan time (COMP-PLANTIME-1), because vect has to know which nodes exist before it can order them. The invalid-unknown-count example makes app conditional on an executor output:
executor "terraform" "app" {
source = "./roots/app"
enabled = terraform.network.network_id != ""
…
}vect validate --global 'region="us-east-1"'Error: Invalid enabled
on main.hcl line 14, in executor "terraform" "app":
14: enabled = terraform.network.network_id != ""
enabled is a plan-time value (COMP-PLANTIME-1), but it references terraform.network, whose result
exists only after it runs.count and for_each can’t depend on values “known after apply”. The difference is how it surfaces. Terraform reports it during plan of that root. vect reports it from validate, before anything runs, and names the plan-time rule.Plan-time and DAG-deferred data
data blocks have two timings, and the rule is mechanical (COMP-PLANTIME-3). A data block is plan-time when everything it reads is plan-time: literals, globals, and other plan-time data. vect reads it before building the graph, and its value is pinned for the run, so the same run sees the same value everywhere. A data block that references an executor output is DAG-deferred: it’s read inside the run, after its upstreams finish, and until then its outputs are typed unknowns. That’s the “deferred” you’ll see in docs and diagnostics: the value will exist, but not yet.
There’s also a third reason for an unknown, and it’s about where you ran the command. Without --workspace, validate, graph, and inspect do no network IO, so a plan-time data block whose type does IO is a typed unknown too (COMP-MODE-1). That’s why data.aws_ssm.build.value was redacted(string) rather than a value above: it wasn’t read. data "value" is the exception, since it never touches the network and is evaluated in every mode. Adding --workspace dev makes those commands read plan-time data live for that workspace.
Typed nulls
A typed null is “nothing here” with a type attached. vect produces one when a block is disabled. A disabled executor, data, or ephemeral block evaluates to a typed null of its output type, and every output of a disabled stack is a typed null of the output’s declared type (COMP-ENABLED-1, COMP-ENABLED-2). Keeping the type means downstream expressions like terraform.canary.url == null ? ... : ... still type-check. It’s the count = 0 situation, but at node level.
Supplying values with fact files
If a value is unknown only because the command didn’t read the outside world, you can provide it. A fact file is an HCL file named *.facts.hcl that holds values for globals, data blocks, ephemeral blocks, and (for inspect only) hypothetical executor results. Here’s the one for flow:
global "region" {
value = "us-east-1"
}
data "data.aws_ssm.build" {
value = {
value = "build-417"
type = "String"
arn = "arn:aws:ssm:us-east-1:123456789012:parameter/app/build-id"
version = 3
}
}
ephemeral "ephemeral.aws_secretsmanager.db" {
value = {
arn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:app-db"
name = "app/us-east-1/db-password"
version_id = "v1"
secret_string = "hunter2"
secret_binary = null
}
}
result "terraform.network" {
value = { network_id = "net-us-east-1" }
}A few things to notice. The block labels are full addresses: data.aws_ssm.build, not aws_ssm.build (LANG-FACTS-1). An injected data or ephemeral value must fill the type’s whole output object, not just the attribute you use. Leave out arn and vect says missing attribute "arn", because the value is checked against the same OutputSchema a real read would produce (COMP-INJECT-3). And a fact always wins: an injected value replaces the read, so no request is made (COMP-INJECT-2, COMP-INJECT-7).
Now the same inspect, with --facts (again trimmed to the second node, so the block starts with …):
vect inspect --facts dev.facts.hcl…
node "terraform.app" {
depends_on = ["terraform.network", "data.aws_ssm.build", "ephemeral.aws_secretsmanager.db"]
result_sources = [{
address = "data.aws_ssm.build"
provenance = "provided"
}, {
address = "terraform.network"
provenance = "hypothetical"
}]
type = object({
inputs = object({
build_id = string
network_id = string
password = string
})
source = string
})
input = {
inputs = {
build_id = "build-417"
network_id = "net-us-east-1"
password = redacted(string)
}
source = "./roots/app"
}
}Every unknown turned into a value, and the type of network_id sharpened from dynamic to string. Two more details are worth a look. result_sources records where each input came from: provided for a fact you supplied, hypothetical for a result block. That’s the provenance every evaluated node carries (COMP-FACT-2, COMP-FACT-3). And build_id printed in the clear while password stayed redacted; we’ll explain that in a moment.
result blocks, the hypothetical executor outputs, are accepted by inspect only. Other commands reject them, since a plan or apply must use real results (LANG-FACTS-3). When several facts name the same block, injected values replace whole values, never merge, and later --facts files beat earlier ones. --global name=<expr> beats --global-file, which beats fact files (COMP-INJECT-8). Fact files can live outside the project root; they’re read through your own filesystem, not the contained one.
Observing what’s deployed
Hypothetical results are for “what if”. To see what a node actually produced, vect inspect --observe <address> reads the executor’s deployed outputs from the workspace’s Inventory and uses them like a fact, with provenance observed and the Inventory version it came from (COMP-MODE-4). It needs --workspace. In the secrets project (set up below), after an apply:
vect inspect --workspace dev --observe terraform.db --facts dev.facts.hcl…
node "terraform.consumer" {
depends_on = ["terraform.db"]
result_sources = [{
address = "terraform.db"
provenance = "observed"
version = 1
}]
type = object({
inputs = object({
api_key = string
})
source = string
})
input = {
inputs = {
api_key = redacted(string)
}
source = "./roots/consumer"
}
}(Trimmed to the second node.) The api_key input is the deployed, sensitive value from Inventory version 1 of terraform.db, and it’s redacted. It’s the quickest way to answer “what would my next plan feed into this node?” without planning.
validate, graph, and inspect, and the workspace is the online switch. The command line always tells you whether the command touches the network: --workspace dev means live plan-time reads for dev, no --workspace means none. --facts works in both modes and wins over live reads.Sensitive values
A value can carry a sensitive mark, as in Terraform. The mark rides along with the value through expressions, so anything derived from a sensitive value is sensitive, and vect redacts it wherever a human might read it: inspect, plan output, vect output, and the logs it captures.
Where marks come from:
- A Terraform root’s own
output ... { sensitive = true }marks that output in vect. In thesecretsproject, thedbroot hasapi_keymarked that way, and theconsumerroot takes it as asensitivevariable. - A data source’s
OutputSchemacan mark attributes.aws_secretsmanageralways markssecret_string;aws_ssmmarksvaluefor aSecureStringparameter, or when you setsensitive = true. Offline, before the type of the parameter is known,valueis marked, which is whybuild_idwas redacted in the firstinspect. In the fact-file run it printed in the clear, because the injectedtypewasString(EXEC-DATA-12 and theaws_ssmnotes). - Marks survive injection: values you supply keep the schema’s marks, and a global keeps the marks of the facts it came from (COMP-GLOBAL-4).
Your own output blocks can add a mark too. A vect output block with sensitive = true marks the output’s whole value sensitive for every reader (the calling stack, root outputs, deployment pointers, and cross-workspace reads). The flag must be a literal, like ephemeral, and sensitive = false never removes a mark the value already carries (LANG-STACK-4).
The smallest case is the sensitive-output project: one terraform executor and two root outputs, one of them marked. The executor’s root is a plain Terraform root whose output is the string release 41:
resource "terraform_data" "note" {
input = "release 41"
}
output "note" {
value = terraform_data.note.output
}The stack’s root outputs read it:
output "note" {
type = string
value = terraform.note.note
sensitive = true
}
output "region" {
value = "us-east-1"
}Apply it, then read the outputs:
vect applyvect outputnote = redacted(string)
region = "us-east-1"The marked output is redacted and the plain one isn’t. --show-sensitive asks for the real value (CLI-direct there’s no policy in the way; against a server it needs permission):
vect output --show-sensitivenote = "release 41"
region = "us-east-1"Here’s what that looks like end to end. secrets has two roots; db exposes a sensitive api_key, and consumer fingerprints it. We ran it against a local Temporal dev server with the same kind of server configuration as in Part 3, with VECT_CONFIG=server.vect. In the plan, Terraform’s own output redaction shows up as it would anywhere:
terraform.db | Changes to Outputs:
terraform.db | + api_key = (sensitive value)
terraform.db | + host = (known after apply)After vect apply --facts dev.facts.hcl, reading the root outputs:
vect outputapi_key = redacted(string)
db_host = "db.internal"
fingerprint = "80f02c37"vect output --show-sensitiveapi_key = "key-from-the-db-root"
db_host = "db.internal"
fingerprint = "80f02c37"--show-sensitive asks the server for the unredacted values. Against a server, the request needs the workspace.read_sensitive_outputs action, and without it the output stays redacted and vect says so (API-AUTHZ-13). Our local run was CLI-direct, so there was no policy in the way. Human-readable output otherwise redacts sensitive values everywhere (API-CLI-4), and they aren’t allowed in errors or events.
What is stored, honestly
Redaction is about display. It isn’t encryption of everything, and it isn’t a promise that the secret appears nowhere on disk.
- vect’s own records are encrypted per workspace: the value store, the CAS, and the objects behind them (see Inventory, bundles, and storage). Sensitive values that vect carries between nodes sit there.
- The engine’s state is not vect’s to protect. A
terraformexecutor still runs OpenTofu or Terraform, which writes outputs, including sensitive ones, into its state file as plain text. After the apply above,grep key-from-the-db-rootfinds the key in.vect/data/dev/dev/terraform.db.tfstate. The same literal also appears in the cached root source,.vect/data/cache/<digest>/main.tf, because anything you write in source is part of the bundle. That’s Terraform’s behavior, unchanged, and the same advice applies: put thestatestore on a bucket with encryption and tight access (the storage guide shows how to move thestatestore to S3). vect’s redaction doesn’t reach into that file. - Third-party process output isn’t scrubbed beyond what vect marks. Fields vect knows are sensitive are redacted before a node’s output is captured as a log blob, but a tool that prints a secret it wasn’t told about can still leak it (RUN-LOG-1).
If a value must never land on disk, sensitive is the wrong tool. That’s what ephemeral is for.
Ephemeral values
An ephemeral value is a value that must never be persisted. It’s Terraform 1.10’s idea, with the same name. In vect it’s a second mark alongside sensitive, and it implies sensitive: ephemeral values are always redacted too (EXEC-EPH-2). Anything derived from one is ephemeral.
There are two sources. An ephemeral block opens a secret at run time (aws_secretsmanager and aws_ssm are the built-in types), and a variable or non-root output can be declared ephemeral = true to pass one through a stack boundary. The secrets project’s source:
ephemeral "aws_secretsmanager" "db" {
secret_id = "app/db-password"
}
executor "terraform" "db" {
source = "./roots/db"
environment = {
DB_PASSWORD = ephemeral.aws_secretsmanager.db.secret_string
}
}The data and ephemeral namespaces are kept apart on purpose: ephemeral.<type>.<name> is always ephemeral, and data.<type>.<name> never is (LANG-EPH-3). So you can tell, at every reference, whether a value could end up on disk.
Where an ephemeral value may go
An ephemeral value may flow only into an ephemeral sink, an attribute its executor type declares as one, or into an ephemeral variable or output, or a local that feeds those (EXEC-EPH-5). The built-in sinks are the terraform executor’s environment, its Terraform variables declared ephemeral = true, aws_ecs_task’s environment, and data "http"’s request_headers. temporal_activity and temporal_workflow inputs are not sinks, because Temporal records them in the target workflow’s history. A root output, a trigger keeper, and the arguments that shape the graph are off limits too.
Misuse is a validate-time diagnostic with a source range, not a leak you find later. The invalid-ephemeral-leak example puts the secret in an ordinary input:
vect validateError: Ephemeral value in a non-ephemeral position
on main.hcl line 18, in executor "terraform" "app":
18: inputs = {
19: network_id = terraform.network.network_id
20: build_id = ephemeral.aws_secretsmanager.db.secret_string
21: password = ephemeral.aws_secretsmanager.db.secret_string
22: }
Argument "inputs" of executor terraform.app, which is not an ephemeral sink, field "build_id" of it
receives an ephemeral value. An ephemeral value may flow only into ephemeral sinks, ephemeral
variables and outputs, and locals that feed them (EXEC-EPH-5).The same configuration in flow passes because its app root declares variable "password" with ephemeral = true, which makes that one input an ephemeral sink. build_id has no such declaration, so only it is flagged. The sink is declared in the Terraform root, not in the vect configuration.
ephemeral block into one root’s process environment without being recorded by vect either.When the secret is opened, and what is recorded
An ephemeral block isn’t read at plan time and isn’t pinned into the run’s facts. It’s opened for each consumer immediately before that consumer’s activity starts, and closed when the activity ends, in every phase: plan, apply, and destroy (EXEC-EPH-7, EXEC-EPH-8). validate, graph, inspect, and bundle never open one at all. They show a typed unknown unless a fact file injects a value, as we did above (COMP-MODE-3).
Ephemeral values never enter the Inventory, plan files, Temporal history, logs, or the value store beyond run-scoped references that are deleted when the run ends (EXEC-EPH-9). We checked this on the secrets run. The secret was injected with --facts, so the fact file is where it’s visible, and nothing under .vect/ contains it:
grep -rl "correct-horse-battery-staple" .vectIt printed nothing and exited with status 1. A second consequence follows from the same rule. Ephemeral inputs are left out of a node’s trigger fingerprint (EXEC-EPH-6), so rotating a password doesn’t make vect think the executor’s inputs changed. Planning again after the apply gave this (without the engine’s own lines):
terraform.db: running
terraform.db: planned inputs unchanged
terraform.consumer: running
terraform.consumer: planned inputs unchanged
plan of workspace "dev": succeeded (run 01a1e26a-cf68-7576-b2d4-58f83ee623d6)
terraform.consumer no-op inputs unchanged
terraform.db no-op inputs unchangedIf you want a rotation to re-run a node, drive it with a value that isn’t ephemeral, such as a version number in a plain input.
Planning and destroying without the block
There’s a catch, and vect handles it explicitly. After an apply, you might delete the ephemeral block from your configuration, or a destroy might run after the code is gone. The node’s sink input still needs a value. So for every ephemeral sink attribute, the node’s Inventory record keeps a replay recipe: the attribute’s expression, the non-ephemeral values it read, and the sources it referenced. A source is an ephemeral address with its recorded non-ephemeral configuration, or an executor output to read again (EXEC-EPH-10). When the node is planned or destroyed with no block in configuration, vect re-evaluates the recipe: it reads the producer’s current output, or opens the ephemeral source again with its recorded configuration (EXEC-EPH-11). The recipe holds the way to get the secret, never the secret. If the source can’t be opened, the plan or destroy fails with a diagnostic naming the source, and you can supply the value with --facts on plan, apply, or destroy (EXEC-EPH-12). The server keeps it in a run-scoped reference so Temporal sees only the reference.
What to take away
| Term | Means | Shown as |
|---|---|---|
| unknown | a typed value that exists later (an executor output) or elsewhere (an IO read, offline) | unresolved: <type> in inspect |
| typed null | a disabled block, or an output of a disabled stack | null of the declared type |
| fact | a value you inject; wins over a live read | provided, hypothetical, observed in result_sources |
| sensitive | redacted when displayed; may still be stored (encrypted by vect, plain in engine state) | redacted(<type>) |
| ephemeral | never stored by vect; may only reach declared sinks | redacted(<type>), a validate error elsewhere |
The practical rules: supply facts to make offline commands useful; keep structural arguments (enabled, count, for_each, source) off executor outputs; treat sensitive as display redaction and your engine’s state store as the place secrets can still live; and use ephemeral for anything that must not be recorded at all.