Skip to content

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:

main.hcl
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.

Coming from Terraform: 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’s dynamic.
  • unresolved: string: a value with a known type and no value yet. The global region is declared string but 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:

main.hcl
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.
Coming from Terraform: the same limit exists, 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:

dev.facts.hcl
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.

A default you can swap: offline is the default for 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 the secrets project, the db root has api_key marked that way, and the consumer root takes it as a sensitive variable.
  • A data source’s OutputSchema can mark attributes. aws_secretsmanager always marks secret_string; aws_ssm marks value for a SecureString parameter, or when you set sensitive = true. Offline, before the type of the parameter is known, value is marked, which is why build_id was redacted in the first inspect. In the fact-file run it printed in the clear, because the injected type was String (EXEC-DATA-12 and the aws_ssm notes).
  • 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:

roots/note/main.tf
resource "terraform_data" "note" {
  input = "release 41"
}

output "note" {
  value = terraform_data.note.output
}

The stack’s root outputs read it:

main.hcl
output "note" {
  type      = string
  value     = terraform.note.note
  sensitive = true
}

output "region" {
  value = "us-east-1"
}

Apply it, then read the outputs:

vect apply
vect output
note = 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-sensitive
note = "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 output
api_key = redacted(string)
db_host = "db.internal"
fingerprint = "80f02c37"
vect output --show-sensitive
api_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 terraform executor 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-root finds 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 the state store on a bucket with encryption and tight access (the storage guide shows how to move the state store 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:

main.hcl
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 validate
Error: 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.

Coming from Terraform: Terraform 1.10 added ephemeral resources and variables, with a different mechanism: the value is allowed only in places that are themselves not persisted. vect enforces the same idea at graph level, with a named list of sinks per executor type, and extends it across roots: the secret flows from an 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" .vect

It 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 unchanged

If 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

TermMeansShown as
unknowna typed value that exists later (an executor output) or elsewhere (an IO read, offline)unresolved: <type> in inspect
typed nulla disabled block, or an output of a disabled stacknull of the declared type
facta value you inject; wins over a live readprovided, hypothetical, observed in result_sources
sensitiveredacted when displayed; may still be stored (encrypted by vect, plain in engine state)redacted(<type>)
ephemeralnever stored by vect; may only reach declared sinksredacted(<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.