Skip to content
Executors and data

Executors, data sources, and ephemeral sources

This page lists every executor, data source, and ephemeral source built into vect, with the block syntax, each attribute’s type, whether it is required and its default, the outputs it produces, and how it behaves in plan, apply, and destroy. It then lists the meta-arguments that work on every block. The concepts behind them are in the topic guides: the graph, runs, and storage. The normative text is the executors and data sources spec.

Every snippet below comes from the example project catalog. Its blocks reach AWS and Temporal endpoints that don’t exist, so it is only validated and graphed, never applied. From a checkout of the vect repository:

cd docs/site/examples/reference/executors/catalog
vect validate
Success!
  (root)  4 blocks
vect graph
data.aws_dynamodb.pin
data.aws_s3.manifest
data.aws_secretsmanager.meta
data.aws_ssm.release
temporal_workflow.rollout
data.http.health
data.value.names
data.value.regions
ephemeral.aws_secretsmanager.token
terraform.app["euw1"]
terraform.app["use1"]
ephemeral.aws_ssm.key
aws_ecs_task.migrate
temporal_activity.notify

Conventions

  • Block syntax. An executor is executor "<type>" "<name>" { ... } and is referenced as <type>.<name>. A data source is data "<type>" "<name>", referenced as data.<type>.<name>. An ephemeral source is ephemeral "<type>" "<name>", referenced as ephemeral.<type>.<name>. A reference yields only the block’s output attributes, never its configuration (LANG-REF-2).
  • Required. A required attribute that is missing is a diagnostic. A default of null means the attribute is simply absent.
  • Credentials. Every built-in uses the ambient environment and identity of the process that runs it (EXEC-CRED-1): the worker for an executor or a DAG-deferred read, the process that starts the run for a plan-time data read. No built-in takes an access key. To give a process a credential it doesn’t have, pass an ephemeral value to an ephemeral sink (below).
  • Plan, apply, destroy. A node whose inputs are unknown (an upstream hasn’t applied) isn’t planned; it reports defer and is planned again at apply (EXEC-PLAN-7). vect never retries a mutating call itself; recovery is plan again, then apply (EXEC-IDEM-2). See runs.
  • Offline. Without a run, data and ephemeral sources that do IO produce typed unknowns, so validate and graph need no credentials.
  • Sensitive. Sensitive and ephemeral marks are preserved on outputs and redacted from output and errors; no value appears in an error.

Executors

terraform

Runs one Terraform or OpenTofu root: init, plan -out, then apply of that saved plan.

main.hcl
executor "terraform" "app" {
  source   = "./roots/app"
  for_each = data.value.regions.value
  inputs = {
    greeting = "hello ${each.value}"
    token    = ephemeral.aws_secretsmanager.token.secret_string
  }
}
AttributeTypeRequiredDefaultNotes
sourcestringyesA directory relative to the declaring stack, inside the project root. Its top-level .tf and .tf.json files define the contract.
enginestringno"opentofu""opentofu" or "terraform". Must be a literal: the bundler picks the binary from it.
inputsobjectif a variable has no defaultnullOne attribute per root variable, typed as declared (dynamic with no type). Undeclared keys are rejected.
stateanynonullAn object overriding the root state block, merged per attribute. May name backend and key_prefix; other attributes are backend configuration. The backend’s key attribute is vect’s to set.
environmentmap(string)nonullExported to the Terraform process in addition to the worker’s environment, overriding it. An ephemeral sink; values are sensitive. TF_CLI_CONFIG_FILE and TF_PLUGIN_CACHE_DIR can’t be set.

Outputs. Exactly the root’s output blocks, typed by each output’s type constraint (inferred shallowly from value when there is none). An output with sensitive = true is sensitive. An output named state, inputs, or source is an output, not a wrapper attribute.

Behavior.

  • plan runs init and plan -out in a working directory built from the node’s bundle assembly and the worker’s read-only provider mirror, with no network access for modules or providers. The saved plan is stored by digest and handed to apply.
  • apply applies exactly the saved plan. A plan made against the current state applies once; after a crash, vect plans again from current state and applies that.
  • The state key is <key_prefix>/<workspace>/<canonical address>.tfstate. Backends s3, azurerm, and local are supported (key, key, and path respectively). With no root state block the workspace’s stores.state store is used.
  • Variables the root declares ephemeral = true, and environment, are ephemeral sinks. An ephemeral value passed to a variable that isn’t declared ephemeral is a diagnostic.
  • destroy runs from the node’s recorded Inventory version, with no configuration needed.

Approvals. Every resource the plan would destroy, including a replacement (-/+), is reported as a :: destroy target and becomes a destroy approval request. -target flags are forwarded for :: targets.

Process environment. The child gets VECT_RUN_ID and VECT_NODE. The worker kills the child if a lease renewal fails and rechecks its lease immediately before apply.

aws_ecs_task

Runs one Amazon ECS task to completion. A task executor (one that runs a unit of work rather than owning infrastructure, so it has no destroy): its result is memoized by trigger.

main.hcl
executor "aws_ecs_task" "migrate" {
  cluster         = "prod"
  task_definition = "migrate:3"
  subnets         = ["subnet-0abc"]
  container       = "migrate"
  command         = ["migrate", "up"]
  environment = {
    API_KEY = ephemeral.aws_ssm.key.value
  }
  trigger = {
    keepers = { release = data.aws_ssm.release.value }
  }
}
AttributeTypeRequiredDefaultNotes
clusterstringyesCluster name or ARN.
task_definitionstringyesFamily, family:revision, or ARN.
subnetslist(string)nonullWhen set, the task runs with awsvpc networking.
security_groupslist(string)nonullUsed with subnets.
containerstringnonullThe container whose overrides and exit code count. Required (a diagnostic otherwise) when the task definition has more than one container.
commandlist(string)nonullCommand override for container. Never put in errors.
environmentmap(string)nonullEnvironment overrides for container. An ephemeral sink.

Outputs. exit_code (number, always 0: a non-zero or missing exit code fails apply) and task_arn (string). Outputs do not inherit sensitive marks from inputs: the type declares its outputs independent of its inputs (IndependentOutputs, internal/executor/awsecstask/awsecstask.go; EXEC-TYPE-7).

Behavior. plan always reports run with unknown outputs (reuse is decided by trigger). apply starts the task, waits for it to stop, and fails on a non-zero exit code. RunTask carries a clientToken derived from the run ID and address, so a repeated apply in one run returns the same task. A recovering run adopts the previous run’s task if it stopped with exit code 0, and reports adopted previous execution; a failed or missing task runs again. There is no destroy: a task owns nothing, so teardown retires its record without calling the executor. It raises no approvals. The container gets VECT_RUN_ID and VECT_NODE after your environment, which can’t replace them.

temporal_activity

Schedules one Temporal standalone activity and waits for its result. A task executor (see aws_ecs_task). The “diagnostic” rules below on timeouts, on_conflict, and id_prefix are raised when the node is planned or applied, not by vect validate. It needs a Temporal server and Go SDK that support standalone activities.

main.hcl
executor "temporal_activity" "notify" {
  task_queue             = "notifications"
  activity               = "Notify"
  input                  = { release = data.aws_ssm.release.value }
  start_to_close_timeout = "5m"
  retry_policy = {
    max_attempts = 3
  }
  depends_on = [aws_ecs_task.migrate]
}
AttributeTypeRequiredDefaultNotes
endpointobject({ address = string, namespace = optional(string), enable_tls = optional(bool) })nonullThe Temporal frontend to use. address is required; namespace defaults to default; TLS is on only when enable_tls is true. Unknown keys are a diagnostic. When null, the worker’s ambient connection and namespace apply.
task_queuestringyesThe task queue the activity runs on.
activitystringyesThe activity type name.
inputanynonullSent as the single activity argument as JSON; null sends none. Sensitive marks are stripped before sending and mark result. An ephemeral value here is a diagnostic: Temporal persists it.
start_to_close_timeoutstringnonullPositive Go duration. At least one of this and schedule_to_close_timeout is required.
schedule_to_close_timeoutstringnonullPositive Go duration, including retries.
heartbeat_timeoutstringnonullPositive Go duration.
retry_policyobject({ max_attempts, initial_interval, backoff_coefficient, maximum_interval, non_retryable_error_types })nonullPassed to Temporal; every field is optional and omitted ones keep Temporal’s defaults. Durations are Go durations. vect adds no retries of its own.

Outputs. result (any): the activity’s JSON result.

Behavior. plan always reports run with an unknown result. The activity ID is vect- plus the hex SHA-256 of the run ID and canonical address, with the USE_EXISTING conflict policy, so a repeated apply attaches to the same execution (or reads its closed result). Cancelling the apply stops the wait but doesn’t cancel the remote activity. A recovering run adopts a closed, completed activity from the previous run and reports adopted previous execution. No destroy, no approvals, no local process. Errors never carry input or result.

temporal_workflow

Starts one Temporal workflow and waits for its result. A task executor (see aws_ecs_task).

main.hcl
executor "temporal_workflow" "rollout" {
  task_queue  = "rollouts"
  workflow    = "Rollout"
  input       = { release = data.aws_ssm.release.value }
  on_conflict = "attach"
  endpoint = {
    address = "temporal.example.com:7233"
  }
}
AttributeTypeRequiredDefaultNotes
endpointsame object as temporal_activitynonullSee temporal_activity.
id_prefixstringno"vect"The leading segment of the workflow ID. An empty string is an error when the node is planned or applied, not at vect validate.
workflowstringyesThe workflow type name.
task_queuestringyesThe task queue the workflow starts on.
inputanynonullSent as the single workflow argument as JSON. Sensitive marks are stripped and mark result; an ephemeral value is a diagnostic.
on_conflictstringno"fail""fail" or "attach". Any other value is an error when the node is planned or applied, not at vect validate.
execution_timeoutstringnonullPositive Go duration, across retries and continue-as-new.
run_timeoutstringnonullPositive Go duration for one run.

Outputs. result (any): the workflow’s JSON result.

Behavior. The workflow ID is <id_prefix>/<workspace>/<canonical address>, started with the memo vect_run_id. A closed workflow with that ID and this run’s memo is read, never started again. A running workflow with that ID is attached to when on_conflict = "attach" or when its memo names this run; otherwise apply fails, naming the ID. A closed workflow from another run doesn’t block a new start. apply fails if the workflow fails, is terminated, times out, or is cancelled. Cancelling the apply stops the wait but doesn’t cancel the workflow. A recovering run adopts a closed, completed workflow from the previous run. No destroy. Errors name only the workflow type, ID, and failure kind.

Data sources

A data block reads a value; it owns no infrastructure, is never recorded as an owned node, and never causes a destroy. A read is plan-time (before the graph expands, in the process that starts the run, then pinned into the run’s facts) unless its configuration references an executor, in which case it is DAG-deferred (see the graph) and read inside the run after its upstreams finish. A DAG-deferred read honors requires_execution and timeout (default 1m). Plan-time values can be overridden with a fact file. See runs.

Every data source also accepts a schema { type = ... } block to refine its output type (see schema).

data "value"

An in-memory value and fan-in barrier. No IO.

main.hcl
data "value" "regions" {
  value = { use1 = "us-east-1", euw1 = "eu-west-1" }
}
AttributeTypeRequiredDefaultNotes
valueanynonullAny expression. If it references an executor the block is DAG-deferred.

Outputs. value (any): the configured value, typed as given, keeping sensitive marks. Reference it as data.value.<name>.value. It is evaluated in every mode, including offline.

data "http"

An HTTP GET or HEAD.

main.hcl
data "http" "health" {
  url             = "https://example.com/health"
  expected_status = [200, 204]
  timeout         = "30s"
}
AttributeTypeRequiredDefaultNotes
urlstringyesAn absolute http or https URL.
methodstringnoGETGET or HEAD.
request_headersmap(string)nononeAn ephemeral sink: ephemeral and sensitive values are accepted and sent.
expected_statuslist(number)no[200]Non-empty whole numbers, 100 to 599.
ca_cert_pemstringnononePEM certificates added to the system roots.
max_bytesnumberno1048576A positive whole number. A larger body is an error.
sensitiveboolnofalseMarks response_body and response_headers sensitive.

Outputs. status_code (number), response_body (string, valid UTF-8, empty for HEAD), response_headers (map(string), canonical names, repeated values joined with ", ").

Behavior. A status outside expected_status is an error naming the method and the URL without its query string or user info. No retries. Redirects follow the Go default. Proxies come from the ambient environment.

data "aws_ssm"

Reads an SSM Parameter Store parameter (GetParameter).

main.hcl
data "aws_ssm" "release" {
  name = "/app/release"
}
AttributeTypeRequiredDefaultNotes
namestringyesParameter name or path.
regionstringnoambientOverrides the AWS region.
with_decryptionboolnotrueForwarded to GetParameter.
sensitiveboolnofalseMarks value sensitive whatever the type.
allow_missingboolnofalseA missing parameter makes every output null instead of an error.

Outputs. value (string, comma-separated for StringList), type (String, StringList, or SecureString), arn (string), version (number).

Behavior. value is sensitive for a SecureString or when sensitive = true. Before a read it is always marked, since the type isn’t known yet.

data "aws_s3"

Reads an S3 object (GetObject).

main.hcl
data "aws_s3" "manifest" {
  bucket = "example-releases"
  key    = "manifest.json"
}
AttributeTypeRequiredDefaultNotes
bucketstringyesBucket name.
keystringyesObject key.
regionstringnoambientOverrides the AWS region.
version_idstringnolatestReads that object version.
sensitiveboolnofalseMarks body and metadata sensitive.
max_bytesnumberno1048576A positive whole number. A larger object is an error.
allow_missingboolnofalseA missing key or version makes every output null.

Outputs. body (string, must be valid UTF-8), etag (string), version_id (string, null for an unversioned bucket), content_type (string), metadata (map(string)).

data "aws_dynamodb"

Reads one DynamoDB item (GetItem), decoding attribute values losslessly.

main.hcl
data "aws_dynamodb" "pin" {
  table = "pins"
  key   = { app = "web" }
}
AttributeTypeRequiredDefaultNotes
tablestringyesTable name.
keyobject or map of scalarsyesThe primary key, one entry per key attribute. string, number, bool, and null encode to S, N, BOOL, NULL; any other type is a diagnostic.
regionstringnoambientOverrides the AWS region.
consistent_readboolnofalseForwarded to GetItem.
allow_missingboolnofalseA missing item yields a null item instead of an error.

Outputs. item (any): the decoded item. S becomes string, N a number at exact precision, BOOL bool, NULL null, L a tuple, M an object, SS a set(string), NS a set(number), and B/BS base64 strings (a set of them for BS).

Behavior. It can serve stale reads (a global table replica lags even with consistent_read), so vect validate warns when it has no monotonic_key and the loaded server configuration defines a loop for the workspace.

data "aws_secretsmanager"

Reads a Secrets Manager secret (GetSecretValue).

main.hcl
data "aws_secretsmanager" "meta" {
  secret_id = "app/meta"
}
AttributeTypeRequiredDefaultNotes
secret_idstringyesSecret name or ARN.
regionstringnoambientOverrides the AWS region.
version_idstringnocurrentSetting it together with version_stage is a diagnostic.
version_stagestringnounsetForwarded to GetSecretValue when set; when neither it nor version_id is set, AWS returns the AWSCURRENT version.
allow_missingboolnofalseA missing or deleted secret makes every output null.

Outputs. arn, name, version_id, secret_string (null for a binary secret), secret_binary (base64; null for a string secret), all string. secret_string and secret_binary are always sensitive, including when injected from a fact file. Prefer the ephemeral source for credentials: a data source’s value is recorded in the run’s facts.

data "vect_workspace"

Another workspace’s last applied root outputs. This snippet is the example vect-workspace, kept apart from the catalog:

../vect-workspace/main.hcl
data "vect_workspace" "network" {
  name = "network"
}
AttributeTypeRequiredDefaultNotes
namestringyesThe workspace to read. Naming the run’s own workspace is a diagnostic.

Outputs. name, bundle_digest, source_digest, and applied_at (RFC 3339 UTC), all string; and outputs (dynamic): an object of the root outputs of the workspace’s latest deployment pointer that has them. Each output keeps the sensitive marks it had there; before a read, outputs is a sensitive unknown.

Behavior. A plan-time source, pinned in the run’s facts. It reads through the server’s configuration and is authorized with workspace.read_outputs; a principal without workspace.read_sensitive_outputs gets sensitive outputs redacted. An unknown name, a refused read, a workspace with no applied outputs, and an unreachable workspace are each an error naming the workspace. Only an unreachable workspace is subject to fallback. Each call to another runner times out after 10s.

Ephemeral sources

An ephemeral block reads a value that is never stored: not in Inventory, plan files, Temporal history, logs, or facts. Every output is ephemeral, which implies sensitive. The block is opened immediately before the consuming node’s activity, on that node’s task queue, and closed when the activity ends; it is opened again for every consumer in every phase. If it fails to open, its consumer fails with a diagnostic naming the block and no executor call is made.

An ephemeral value may flow only into an ephemeral sink: terraform’s environment and its variables declared ephemeral = true, aws_ecs_task’s environment, and data "http"’s request_headers. Anywhere else it is an error. temporal_activity and temporal_workflow input are not sinks, because Temporal persists input in workflow history. Ephemeral inputs are excluded from trigger fingerprints.

Validating the invalid-ephemeral-sink example, a sibling of the catalog, shows the error (the last line returns to the catalog):

cd ../invalid-ephemeral-sink
vect validate
cd ../catalog
Error: Ephemeral value in a non-ephemeral position

  on main.hcl line 8, in executor "aws_ecs_task" "migrate":
   8:   command         = ["migrate", ephemeral.aws_ssm.key.value]

Argument "command" of executor aws_ecs_task.migrate, which is not an ephemeral sink, 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).

That is the invalid-ephemeral-sink example. An ephemeral block accepts the meta-arguments enabled, count, for_each, depends_on, and timeout (default 1m), and never requires_execution. Neither built-in implements Renew or Close, because their values don’t expire and hold nothing to release. For replay on destroy, each node’s Inventory version records a recipe for how to open its ephemeral inputs again, so a root stays destroyable after its block is deleted; see storage.

ephemeral "aws_secretsmanager"

main.hcl
ephemeral "aws_secretsmanager" "token" {
  secret_id = "app/api-token"
}

Attributes are those of data "aws_secretsmanager": secret_id (required), region, version_id, version_stage (unset; AWS returns AWSCURRENT), and allow_missing (default false). Outputs are the same five, arn, name, version_id, secret_string, and secret_binary, all ephemeral.

ephemeral "aws_ssm"

main.hcl
ephemeral "aws_ssm" "key" {
  name = "/app/key"
}

Attributes are those of data "aws_ssm": name (required), region, with_decryption (default true), allow_missing (default false), and sensitive, which is accepted for parity and has no effect. Outputs are value, type, arn, and version, all ephemeral.

Meta-arguments

Meta-arguments are removed by the compiler before a block’s configuration reaches its type’s schema, so they never collide with a type’s own attributes. Which block kinds accept each:

Meta-argumentTypestackdataephemeralexecutor
enabledbool, default trueyesyesyesyes
countnumberyesyesyesyes
for_eachmap or set(string)yesyesyesyes
depends_onlist of referencesyesyesyesyes
timeoutGo duration stringnoyesyesyes
provides_executionstringnononoyes
requires_executionstringnoDAG-deferred onlynoyes
triggerobjectnononotask executors
concurrencyblockexclusive onlynonoyes
fallback"last_applied"noplan-time onlynono
monotonic_keystringnoplan-time onlynono
schemablocknoyesnono

Using a meta-argument on a block kind that doesn’t accept it is a diagnostic (LANG-META-2). deploy, output, variable, moved, and removed accept none, except depends_on on output.

enabled

A bool, default true. When false the block has no instances. Plan-time known. See the graph.

count and for_each

count is a non-negative whole number; instances are <address>[0], [1], and so on. for_each is a map or a set of strings whose keys are known; instances are keyed <address>["<key>"], with each.key and each.value available. Both are plan-time known. Setting both on one block is a diagnostic. Validating invalid-meta, another sibling of the catalog, prints:

Error: count and for_each together

  on main.hcl line 3, in data "value" "v":
   2:   count    = 1
   3:   for_each = { a = 1 }

count and for_each cannot both be set on one block: they expand it in incompatible ways
(LANG-META-1).

That is invalid-meta.

depends_on

A list of references that adds an ordering edge without a value flowing. It accepts executor blocks, stack calls and their outputs, data and ephemeral blocks, var.*, and local.*; any other expression is a diagnostic. See the graph.

timeout

A positive Go duration ("30s", "10m") bounding one call: a Plan, Apply, PlanDestroy, or Destroy of an executor, or one read of a data or ephemeral block. Defaults: 1h for an executor, 1m for data and ephemeral. A zero, negative, or unparseable value is a diagnostic. See per-block timeout.

provides_execution and requires_execution

Each takes one capability name matching [a-z][a-z0-9_-]*, plan-time known. A node that provides_execution creates a place where work can run; a node that requires_execution runs only there, on the task queue the server configuration maps that capability to. requires_execution on a plan-time data block is a diagnostic. See task queues and where nodes run.

trigger

Valid only on task executors (aws_ecs_task, temporal_activity, temporal_workflow); on anything else it is a diagnostic. An object:

AttributeTypeDefaultNotes
use_inputsbooltrueInclude the node’s non-ephemeral evaluated inputs in the fingerprint.
keepersmap(any){}Extra values to include in the fingerprint. Undeclared keys are a diagnostic.

A task executor is memoized in its Inventory record. Its fingerprint is a digest of the canonical address, executor type, revision, the non-ephemeral inputs (when use_inputs is true), and keepers; map key order doesn’t change it. plan reports reuse, projecting the recorded output, when the current version is committed and not in flight, the fingerprinted inputs are all known, and the type, revision, and fingerprint match; otherwise it reports run. Memoization survives worker restarts, and ephemeral inputs never enter the fingerprint. Set use_inputs = false to run only when a keeper changes. See storage.

concurrency

A nested block, plan-time known. On an executor, it accepts:

AttributeTypeDefaultNotes
outputsstring"last_converged""last_converged" or "wait": readers of this node’s outputs use the last converged version, or wait for an in-flight apply of the node to commit.
inputsstring"last_converged"The same choice from the consumer’s side: this node waits for its upstreams’ in-flight applies.
exclusiveboolfalseA run that may change anything inside the block takes a scope lease on it first, so two such runs don’t overlap.

A plan-only run takes no leases and reads the last committed versions without waiting (FLEET-CONC-9). On a stack block only exclusive is accepted. Any other attribute or value is a diagnostic.

fallback and monotonic_key

Both are plan-time data only; on a DAG-deferred data block each is a diagnostic.

  • fallback = "last_applied": when a plan-time read fails during a maintenance run (a run the server’s loops start to keep a workspace converged, as opposed to an intent run a person or script starts with plan, apply, or destroy), reuse the value pinned for this block by the latest run that read it successfully and committed a node or published a pointer. The run is marked as running on fallback facts. With no such run, the failed read fails the run. During an intent run, a failed read always fails the run unless the value was injected.
  • monotonic_key = "<attr>": names an output attribute, or a dotted path such as "item.version" into a refined type. The attribute must be a number or an RFC 3339 timestamp string. The first read is accepted; a later read whose value is lower than the last pinned one is treated as no change and the previous value is kept. An injected value must carry the key and is rejected if lower.

schema

At most one nested block on a data block, holding only a type attribute in type-constraint syntax (including optional(...) defaults). It refines the source’s output type: it may narrow only the parts the source’s output schema types as any, and a type that contradicts a typed part or names an attribute the source lacks is a diagnostic. Attributes it omits keep their original types, and the source’s sensitive marks are kept. Reads and injected values are converted to the refined type; a value that can’t be converted is a diagnostic that never contains the value.

main.hcl
data "value" "names" {
  value = ["use1", "euw1"]
  schema {
    type = object({ value = list(string) })
  }
}

Where to go next

  • How blocks become one dependency graph: the graph.
  • What a run does with plans, approvals, and recovery: runs.
  • Where task memoization, replay recipes, and state live: storage.
  • Normative text and requirement IDs: executors and language.