Approvals

Nothing applies in TerraDesk until the apply gate passes. The gate is the change-control point: it decides whether a plan may transition from planned into running terraform apply, and every part of it is attributable to a person.

The apply gate

A plan may apply when both are true:

The count is met: every resource policy governing one of the plan's changes has its approvals, and the plan meets the workspace baseline if any of its changes is still on it.
Every active reservation is answered: a reservation held by a person needs that person's own approval, and a reservation held by a role needs an approval from at least one current member of the role.

Approvals are recorded on the plan itself, each one carrying the organization user who gave it and the time they gave it. Plans are never deleted, so the record of who approved what survives the workspace being archived.

The gate is evaluated at apply time, not when the plan was created. A requirement added while a plan is already sitting at planned applies to it.

Baseline approvals

A workspace's required approvals is the baseline: the number of approvals needed for every resource change that no resource policy sets a count for. It defaults to 0, which means anyone who can see the workspace can apply.

A resource policy with an explicit count replaces the baseline for the resources it governs. The baseline still applies to the plan as a whole whenever at least one of its changes is left on it.

Approving requires the approve permission on the workspace, granted per workspace to an organization user or to a role. super_admin short-circuits every permission check in the organization.

Reservations

A reservation is a standing claim that every apply on a workspace needs a particular approval, until the reservation is released. There are two kinds:

Held by a person. Every apply needs that person's own approval. Reserve a workspace for yourself when you are actively working in it and want to be certain nothing lands underneath you.
Held by a role. Every apply needs an approval from any one current member of the role. Reserve a workspace for a role to say "someone from DevOps must approve every apply here" without needing two DevOps engineers online.

Choose Reserve workspace from a workspace's actions. If there is a role you can reserve for, you are asked whether to reserve for yourself or for one of them.

Who can reserve

Reserving for yourself requires the approve permission on the workspace.
Reserving for a role requires approve on the workspace and membership of that role. A super_admin can reserve for any role, member or not.
A role that already holds a reservation on the workspace is not offered again, and only roles of your own organization can be chosen.

What a reservation requires

Reservations are workspace-scoped. There are no per-resource reservations.
Several reservations can be active on the same workspace at once, held by people, by roles, or both. Every one of them must be answered before a plan can apply.
A role's reservation is answered by one approval, whatever the size of the role. Membership is read when the apply is checked, not when the approval was given. If the member who approved is removed from the role before the apply, the reservation is missing again and the plan page shows the role's current members.
A reservation adds a required approval. It gives nobody permission to approve. A member of the role still needs approve on the workspace, or to be a named approver on a resource policy, to approve a plan. Once the gate passes, anyone holding approve may start the apply.
An approval that answers a reservation counts toward the baseline count too, when its approver holds approve. There is no double counting.
No resource policy lowers a reservation. It applies to every plan on the workspace, whatever the plan changes and however it was triggered.

The workspace page, the plan page and the workspace list all show who a workspace is reserved for, and who placed the reservation.

Releasing

Anyone holding a personal reservation may release their own. Any current member of a role may release the role's reservation. A super_admin can release any reservation in their organization.
Reservations never expire. A role with no members left keeps blocking applies until a super_admin releases its reservation.
Deleting a role releases every reservation it holds. The role's settings page lists the workspaces first, and the admin who deletes the role is recorded as the releaser.
Releases are recorded, not deleted: the row keeps who released it and when.

A reservation is not a Terraform state lock. It never touches the lock that terraform force-unlock clears.

Resource policies

A resource policy is an organization-level rule applied to one or many workspaces that sets what an apply touching certain resources needs. It is how you express "deleting a database needs three approvals, one of them from the data team" without making every apply in the workspace expensive, and "the status page module needs one approval" without lowering the bar for everything else.

Scoping resources

A policy governs a resource in two additive ways:

Assigned — someone picked that resource for the policy by hand.
Matched — one of the policy's address patterns covers it.

An address pattern is a glob over Terraform addresses where * matches any run of characters and everything else is literal:

module.prod_db.*
aws_db_instance.primary
*.aws_s3_bucket.*

Matching is exact against the whole address, so a root-level resource needs its own pattern rather than a leading *..

There is no way to carve a resource out of a pattern. Assignment and matching are additive, so assigning a resource to a new policy never takes it off one that already covered it — a policy can only ever be added.

Requirements

Each policy carries one requirement per resource change action — create, update, delete, replace. A requirement is:

A count of approvals (1, 2 or 3), or Auto, meaning the workspace's baseline decides.
A list of named approvers — organization users and/or roles.

It is satisfied when the count is met and at least one named approver has approved.

An explicit count replaces the workspace baseline for the resources the policy governs, whether it is higher or lower. In a workspace with a baseline of 2, a change governed by a policy asking for 1 needs one approval, and a change governed by a policy asking for 3 needs three. There is no count of zero: a policy cannot wave a change through with no approval at all.

The baseline keeps applying to:

a change no policy governs, and
a change whose policies all say Auto for that action.

A plan is approved as a whole, so one change on the baseline holds the whole plan to it:

Every change governed by an explicit count. The baseline does not apply. The plan needs only what its policies ask.
A mix. A plan that changes one resource governed at 1 and one resource no policy covers still needs the baseline. The plan page names the changes holding it there.
A targeted plan. Targeting a governed module does not guarantee the lower number. If Terraform pulls in a dependency outside the policy, that dependency is on the baseline and so is the plan. The targeted plan picker shows each resource's count before the plan runs, using the action the workspace's current plan has for it, and the total can rise once the plan shows what it really changes.

Overlapping policies

Where several policies cover the same change:

The count is the strictest of them.
Each approver list is satisfied separately. They are not merged — merging would let a narrow policy dilute a broad one. Two overlapping policies means one approver from each list.

The number shown against a resource is the strictest requirement covering it: a change governed by policies asking for 1 and 3 needs 3. Meeting that number does not discharge the other policies' approver lists.

Named approvers

Being named on a requirement is itself the grant to approve for that policy. Someone named may approve a plan without holding approve on the workspace — otherwise a policy could deadlock a workspace it does not administer.

Their approval counts toward that policy's own number, but not toward the workspace baseline. Only an approval from someone who does hold approve counts toward that, on any plan the baseline still applies to.

Auditing the gate

Everything the gate consults is a stored, attributable record:

Each approval names an organization user and the moment they approved.
Each reservation names the person or role it is held by and the person who placed it, and its release names who released it and when. A reservation released because its role was deleted names the admin who deleted the role.
Each plan stores the resource changes it proposed, so the requirement that applied to it can be recomputed after the fact.
Plans and their approvals are never deleted; workspaces are archived rather than removed.

See Security for how this fits into the wider architecture.