Writ

Glossary

The terms the docs use, each with one meaning and its Terraform equivalent.

Each term in Writ's docs has one meaning, listed here. Where Terraform or OpenTofu has a term for the same thing, the last column gives it.

TermMeaningIn Terraform
stackA directory of a repository that has .tf or .tofu files and a committed .terraform.lock.hcl, which writ serve plans with OpenTofu. Its name is its path under the repository's path, with the repository's prefix before it. See OpenTofu stacks.Root module
environmentA named target of the config, written env "NAME" { ... }: the key that seals its states and saved plans, its plan and apply roles, and the variables its providers get. A stack is planned in an environment, written stack@env, and each stack@env has its own state.Workspace
resourceOne object that a provider manages, declared as resource "TYPE" "NAME" { ... }.Resource
objectThe real thing that a provider created, such as a file or a security group.
providerA Terraform provider binary. OpenTofu runs it for a plan or an apply, and writ import bulk runs it through Writ's own client of the plugin protocol.Provider
provider configurationOne provider block of OpenTofu code, identified by its address, such as aws.west.Provider configuration, alias
provider uidOne of the config's provider_uids: the user that OpenTofu and its providers run as for one run, with no groups and no access to the keys or the database of writ serve. See How providers are kept from the keys.
addressOpenTofu's name of a resource in a stack, such as random_pet.name or module.net.aws_subnet.a["eu"].Resource address
variableAn input of a stack, declared with variable. One declared sensitive = true contains a secret.Input variable
outputA value that a stack exposes, declared with output.Output value
moduleA directory of OpenTofu code that a stack calls with a module block. writ serve allows local paths, registry addresses, and remote addresses, and refuses every other source.Module
annotation layerWrit's table of facts that a provider schema doesn't have, which writ import bulk reads: the references between resource types, and the attributes a provider fills itself.
secretA value that the mask must keep out of everything writ serve stores or shows: a value OpenTofu marks sensitive, a variable declared sensitive = true, and a value of provider_env. See Secrets and the mask.Sensitive value
maskThe one package, internal/mask, that writes everything that leaves an OpenTofu run: the masked plan, the text and events of a plan and an apply, and the rows of the state index. It replaces each secret it knows or finds with (sensitive).
masked planThe document of a plan that writ serve keeps and shows: OpenTofu's plan JSON after the mask, with only the keys the mask keeps. Policy checks it, and writ plan --remote prints it.
secret setThe secrets that a run's mask knew, sealed with each state version or serial that its apply wrote, so that the mask of a later run of that state starts from them. A state with no secret set can't be approved until a person adopts it.
sealTo encrypt with an environment's key: a state on the http backend, a saved plan, or a secret set.
stateOpenTofu's record of the objects that a stack@env manages, in the stack's backend: backend "http" {}, which writ serve serves, or the stack's own backend "s3".State
state versionOne state of a stack@env that the http backend stored. Each apply's write is a new version.State version
serialOpenTofu's number of a state, which each write raises. A stack on S3 identifies a state by its serial.Serial
state tokenThe token a run gets for the http backend. A plan's token reads its stack's state and nothing else, and an apply's token also locks and writes it. It ends with its run, and writ serve keeps only its SHA-256.
lockOpenTofu's claim on a state while an apply writes it: the http backend's LOCK route, or the lock of the S3 backend.State lock
state indexThe rows of what each stack@env's state manages, kept in the control database: each resource's address, type, and provider, and a few attributes that identify its object. Only the mask writes them. See The state index.
rowOne record of a table in the control database.
planThe changes that OpenTofu proposes for one commit of a stack in one environment, and the command that asks writ serve for them, writ plan --remote.Plan
commit planA plan of the files of one commit, which the control plane fetched from the repository.
speculative planA plan of files that a client sent, kept from before writ serve planned only commits. No control plane applies one.Speculative plan
saved planOpenTofu's plan file of a plan, sealed under the environment's key. An apply runs tofu apply of it. No API route returns it.Saved plan
risk classWhat a change risks, which grants and approval rules list: create, update, replace, delete, or data-loss. In an OpenTofu plan, a forget counts as delete and an import as create, and no change carries data-loss.
applyThe run of an approved saved plan on the control plane, and the command that asks for it, writ apply --remote.Apply
runOne apply that writ serve started. writ runs --remote lists them.Run
actorWho started a run, as the run records it.
audit logThe control database's rows of every request to writ serve, to the API, the control UI, or the state backend, and of every decision it makes on its own, with the stacks each refers to. GET /healthz, GET /v1/server, and requests that the limit on each client address refuses with 429 leave no row.Audit trail
policyRego rules, in the policy sets that the config lists, that check each masked plan at the plan and again before its apply. See Policy.Policy as code
policy setA directory of .rego files that a set block of the config's policy block points to, mandatory or advisory. An advisory set's deny only warns.Policy set
driftA change to an object outside Writ.Drift
drift checkA plan of an OpenTofu stack that writ serve creates on a timer, at the head of its default branch, to find drift and changes that no apply has made. It's never approved or applied.Drift detection, health assessment
agentA program driven by a language model that edits code and runs writ.
control planeThe one writ serve process that plans for CI jobs that have no cloud credential and no state key, keeps the plans, and writes the audit log. See How the control plane works.HCP Terraform, for remote runs
dev control planewrit serve --dev: a control plane for one user, on loopback, with its store in SQLite. The remote commands find it with no flag. See writ serve --dev.None
issuerAn OIDC token issuer that writ serve trusts, such as https://gitlab.com, with a kind: gitlab-ci, github-actions, or people. People sign in with an issuer of kind people.
identityThe name an issuer's config gives the Git host or identity provider that the user ids in its tokens come from. Issuers of one Git host share it. See Who a person is.
person idIDENTITY/user/ID, such as gitlab/user/1001: the stable id of a person, which approvals compare.
principalWhat a verified token or a session speaks for: a CI job and the person who started it, or a signed-in person.
sessionA person's sign-in to writ serve, which lasts 12 hours by default. writ serve keeps only the SHA-256 of its token. A browser session's token lives in a cookie.
control UIThe web pages that writ serve serves under /ui/. See The control UI.
teamA named rule over the claims of one issuer's tokens. A principal with a token that matches it is a member.Team
grantA rule that lets teams do some operations on some stack@env, and apply some risk classes. In its stack patterns, * matches within one part of a stack name, and a part ** matches any number of parts.Permission
repositoryA GitLab project, or a local Git repository under writ serve --dev, that the control plane reads code from, with the path in it under which its stacks are. Short form "repo" in commands and the API. See Repositories.VCS connection
forgeThe Git host that hosts repositories, GitLab. The control plane reads it with a read-only token from a file the config points to. forge is also the config block.VCS provider
approvalA person's record that they read one plan, by its id, and agree that it can be applied. The plan's author can't give one. See Approvals.Approval of a run
approval ruleA rule of the config that says how many approvals a plan of some stacks, environments, and risk classes needs.Policy, in HCP Terraform
overrideAn apply of a plan without the approvals its rules need, by a person with override, with a reason that the run records.
adoptionA person's writ state adopt of an OpenTofu state that has no secret set: writ serve seals with it each value the state marks sensitive, with a reason that the audit log records. See Adopt a state. Taking existing objects into a stack is an import, never an adoption.
importTaking existing objects into a stack: import blocks in a commit, which writ import bulk can write, planned and applied like any other change. See Import many objects.Import
supersededThe status of a plan after its state or its branch moved. It can no longer be applied.

This page is built from docs/glossary.md in the repository. It is also served as plain Markdown.