OpenTofu
units.gitops.nyl/v1
Orchestration Resources · Download JSON Schema · Usage guide
A Terraform or OpenTofu infrastructure unit, preserving native state and locks.
Example
apiVersion: units.gitops.nyl/v1
kind: OpenTofu
metadata:
name: workloads
spec:
backend:
bucket: acme-state
key: production/network
outputs:
id:
type: string
source:
path: infra/network
variables:
region: eu-west-1Fields
Required means required within the containing object. Optional and nullable are distinct; contextual defaults and requirements are explained with each field.
apiVersion
Required · string
The built-in unit API version, units.gitops.nyl/v1.
const: "units.gitops.nyl/v1"
kind
Required · string
Terraform or OpenTofu, selecting the native executable.
const: "OpenTofu"
metadata
Required · object
Literal unit name and labels used for environment selection.
Unknown fields are rejected.
metadata.labels
Optional · object
Literal labels used for organization and target selection.
metadata.labels[key]
Optional · string
metadata.name
Required · string
Project-local identity, validated by the resource kind; remains static during discovery.
spec
Required · object
Pinned configuration, native backend, variables, outputs, and common policy.
Unknown fields are rejected.
spec.approval
Optional · string or object
Whether executions need an invocation’s approval.
Match one or more variants:
Variant 1
Type: string
Allowed values: "auto" · "manual"
Variant 2
Type: object
When a unit’s executions need an invocation’s approval.
Written as auto (the default), manual (short for
{mode: manual, bind: desired}), or {mode, bind, requireDigest}.
spec.approval.bind
Required · string
What an approval authorizes: one execution of the desired document, or the changes a reviewed plan showed.
Allowed values: "desired" · "plan"
spec.approval.mode
Required · string
auto executes without approval; manual waits for --approve.
Allowed values: "auto" · "manual"
spec.approval.requireDigest
Optional · boolean
Refuse approvals without a change digest, for bind: plan.
spec.attestations
Optional · array
Attestations of the unit’s receipts: names its kind produces itself, or entries with from: external that only nyl attest supplies.
spec.attestations[]
Required · object
One attestation a unit’s receipts can carry.
Unknown fields are rejected.
spec.attestations[].from
Optional · string or null
external for an attestation only nyl attest supplies; omitted for one the kind produces itself.
Allowed values: "external" · null
spec.attestations[].name
Required · string
Attestation name, such as healthy.
spec.backend
Optional · object
Backend configuration passed to init through a private temporary file. Credentials belong in env, never here.
Additional keys may contain any value.
spec.deletionPolicy
Optional · string or null
What happens to the unit’s resources when it leaves the ownership set. Default Teardown where the kind supports teardown, else Retain.
Allowed values:
| Value | Meaning |
|---|---|
"Teardown" | Tear the resources down, after --allow-teardown. |
"Retain" | Leave the resources in place. |
null |
spec.dependsOn
Optional · array
Units that must have a current receipt first, for ordering without a data reference.
spec.dependsOn[]
Required · string
A unit that must have a current receipt before this one runs: a name, or an entry naming another declared environment or stronger evidence.
Match one or more variants:
Variant 1
Type: string
A unit of the same environment.
Variant 2
Type: object
A unit, optionally of another declared environment, with required evidence.
Unknown fields are rejected.
spec.dependsOn[].attestations
Optional · array
The producer’s attestations to require, instead of all it declares.
spec.dependsOn[].attestations[]
Required · string
spec.dependsOn[].environment
Optional · string or null
Another declared environment; default this one.
spec.dependsOn[].evidence
Optional · string or null
Required evidence: published (a current receipt, the default) or attested.
Allowed values:
| Value | Meaning |
|---|---|
"published" | A current receipt. |
"attested" | A current receipt whose required attestations pass. |
null |
spec.dependsOn[].unit
Required · string
The producing unit.
spec.enabled
Optional · boolean
Evaluated after rendering; false leaves the environment’s ownership set, which deletes the unit under its deletionPolicy.
spec.env
Optional · object
Variables and secrets admitted into the unit’s otherwise empty tool environment.
Unknown fields are rejected.
spec.env.passthrough
Optional · array
Names of runner environment variables copied as they are.
spec.env.passthrough[]
Required · string
spec.env.secrets
Optional · object
Variables read from the project’s secrets provider, by variable name and secret key. An object or array secret is passed as compact JSON.
spec.env.secrets[key]
Optional · string
spec.files
Optional · array
Files entering the execution key, relative to the source project’s nyl.toml or worktree-rooted. Defaults to source.path/**, excluding .terraform.
spec.files[]
Required · string
spec.outputs
Optional · object
Declared outputs, for kinds that let units declare them. Only declared outputs are recorded.
spec.outputs[key]
Optional · object
One declared output: a type from the Release input type set.
Unknown fields are rejected.
spec.outputs[key].description
Optional · string or null
Documentation, surfaced in inspection.
spec.outputs[key].sensitive
Optional · boolean
Validated but never persisted, and never referenceable.
spec.outputs[key].type
Required · string
Value type: string, integer, number, boolean, object, or array.
Allowed values:
| Value | Meaning |
|---|---|
"string" | A JSON string. |
"integer" | A JSON integer; numbers with a fractional part are rejected. |
"number" | Any JSON number. |
"boolean" | true or false. |
"object" | A JSON object. Only the top-level type is checked. |
"array" | A JSON array. Only the top-level type is checked. |
spec.source
Required · object
Configuration directory at the effective source revision. Relative local modules use the same checkout.
spec.source.commit
Optional · string or null
Full 40-character lowercase commit ID that is read, refreshed by nyl update source-locks.
spec.source.path
Required · string
Path in the repository. In this repository it follows the local path rule: relative to the directory containing nyl.toml, may begin with .. segments, or starts with / to name a path from the Git worktree root, and never leaves the worktree. In a remote repository it is relative to the checkout root, with an optional leading /.
spec.source.repository
Optional · object or null
Inline repository coordinates to read from. Mutually exclusive with repositoryRef.
Unknown fields are rejected.
spec.source.repository.repoURL
Required · string
Git read URL. Source checkouts never publish to this repository.
spec.source.repositoryRef
Optional · object or null
Project-local gitops.nyl/v1 GitRepository to read from. Mutually exclusive with inline repository.
Unknown fields are rejected.
spec.source.repositoryRef.name
Required · string
Project-local name of the referenced resource; its kind and API group are determined by the containing field.
spec.source.revision
Optional · string or null
Human-readable branch or tag that nyl update source-locks resolves.
spec.timeout
Optional · string or null
Deadline for one execution, teardown, or verification, at most 7d. Default per kind.
pattern: "^(?=.)([0-9]+d)?([0-9]+h)?([0-9]+m)?([0-9]+s)?$"
spec.varFiles
Optional · array
Native variable files, evaluated in order before explicit variables.
spec.varFiles[]
Required · string
spec.variables
Optional · object
Native input variables; fromUnit references may appear at any depth.
Additional keys may contain any value.
spec.version
Optional · string or null
Exact required native tool version. Without it, the installed version is audited but does not trigger execution.
spec.workspace
Optional · string or null
Terraform workspace, defaulting to the native default workspace.